1c Copyright (C) 1988-2018 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:: As in Algol and Pascal, lexical scoping of functions. 30* Constructing Calls:: Dispatching a call to another function. 31* Typeof:: @code{typeof}: referring to the type of an expression. 32* Conditionals:: Omitting the middle operand of a @samp{?:} expression. 33* __int128:: 128-bit integers---@code{__int128}. 34* Long Long:: Double-word integers---@code{long long int}. 35* Complex:: Data types for complex numbers. 36* Floating Types:: Additional Floating Types. 37* Half-Precision:: Half-Precision Floating Point. 38* Decimal Float:: Decimal Floating Types. 39* Hex Floats:: Hexadecimal floating-point constants. 40* Fixed-Point:: Fixed-Point Types. 41* Named Address Spaces::Named address spaces. 42* Zero Length:: Zero-length arrays. 43* Empty Structures:: Structures with no members. 44* Variable Length:: Arrays whose length is computed at run time. 45* Variadic Macros:: Macros with a variable number of arguments. 46* Escaped Newlines:: Slightly looser rules for escaped newlines. 47* Subscripting:: Any array can be subscripted, even if not an lvalue. 48* Pointer Arith:: Arithmetic on @code{void}-pointers and function pointers. 49* Pointers to Arrays:: Pointers to arrays with qualifiers work as expected. 50* Initializers:: Non-constant initializers. 51* Compound Literals:: Compound literals give structures, unions 52 or arrays as values. 53* Designated Inits:: Labeling elements of initializers. 54* Case Ranges:: `case 1 ... 9' and such. 55* Cast to Union:: Casting to union type from any member of the union. 56* Mixed Declarations:: Mixing declarations and code. 57* Function Attributes:: Declaring that functions have no side effects, 58 or that they can never return. 59* Variable Attributes:: Specifying attributes of variables. 60* Type Attributes:: Specifying attributes of types. 61* Label Attributes:: Specifying attributes on labels. 62* Enumerator Attributes:: Specifying attributes on enumerators. 63* Statement Attributes:: Specifying attributes on statements. 64* Attribute Syntax:: Formal syntax for attributes. 65* Function Prototypes:: Prototype declarations and old-style definitions. 66* C++ Comments:: C++ comments are recognized. 67* Dollar Signs:: Dollar sign is allowed in identifiers. 68* Character Escapes:: @samp{\e} stands for the character @key{ESC}. 69* Alignment:: Inquiring about the alignment of a type or variable. 70* Inline:: Defining inline functions (as fast as macros). 71* Volatiles:: What constitutes an access to a volatile object. 72* Using Assembly Language with C:: Instructions and extensions for interfacing C with assembler. 73* Alternate Keywords:: @code{__const__}, @code{__asm__}, etc., for header files. 74* Incomplete Enums:: @code{enum foo;}, with details to follow. 75* Function Names:: Printable strings which are the name of the current 76 function. 77* Return Address:: Getting the return or frame address of a function. 78* Vector Extensions:: Using vector instructions through built-in functions. 79* Offsetof:: Special syntax for implementing @code{offsetof}. 80* __sync Builtins:: Legacy built-in functions for atomic memory access. 81* __atomic Builtins:: Atomic built-in functions with memory model. 82* Integer Overflow Builtins:: Built-in functions to perform arithmetics and 83 arithmetic overflow checking. 84* x86 specific memory model extensions for transactional memory:: x86 memory models. 85* Object Size Checking:: Built-in functions for limited buffer overflow 86 checking. 87* Pointer Bounds Checker builtins:: Built-in functions for Pointer Bounds Checker. 88* Other Builtins:: Other built-in functions. 89* Target Builtins:: Built-in functions specific to particular targets. 90* Target Format Checks:: Format checks specific to particular targets. 91* Pragmas:: Pragmas accepted by GCC. 92* Unnamed Fields:: Unnamed struct/union fields within structs/unions. 93* Thread-Local:: Per-thread variables. 94* Binary constants:: Binary constants using the @samp{0b} prefix. 95@end menu 96 97@node Statement Exprs 98@section Statements and Declarations in Expressions 99@cindex statements inside expressions 100@cindex declarations inside expressions 101@cindex expressions containing statements 102@cindex macros, statements in expressions 103 104@c the above section title wrapped and causes an underfull hbox.. i 105@c changed it from "within" to "in". --mew 4feb93 106A compound statement enclosed in parentheses may appear as an expression 107in GNU C@. This allows you to use loops, switches, and local variables 108within an expression. 109 110Recall that a compound statement is a sequence of statements surrounded 111by braces; in this construct, parentheses go around the braces. For 112example: 113 114@smallexample 115(@{ int y = foo (); int z; 116 if (y > 0) z = y; 117 else z = - y; 118 z; @}) 119@end smallexample 120 121@noindent 122is a valid (though slightly more complex than necessary) expression 123for the absolute value of @code{foo ()}. 124 125The last thing in the compound statement should be an expression 126followed by a semicolon; the value of this subexpression serves as the 127value of the entire construct. (If you use some other kind of statement 128last within the braces, the construct has type @code{void}, and thus 129effectively no value.) 130 131This feature is especially useful in making macro definitions ``safe'' (so 132that they evaluate each operand exactly once). For example, the 133``maximum'' function is commonly defined as a macro in standard C as 134follows: 135 136@smallexample 137#define max(a,b) ((a) > (b) ? (a) : (b)) 138@end smallexample 139 140@noindent 141@cindex side effects, macro argument 142But this definition computes either @var{a} or @var{b} twice, with bad 143results if the operand has side effects. In GNU C, if you know the 144type of the operands (here taken as @code{int}), you can define 145the macro safely as follows: 146 147@smallexample 148#define maxint(a,b) \ 149 (@{int _a = (a), _b = (b); _a > _b ? _a : _b; @}) 150@end smallexample 151 152Embedded statements are not allowed in constant expressions, such as 153the value of an enumeration constant, the width of a bit-field, or 154the initial value of a static variable. 155 156If you don't know the type of the operand, you can still do this, but you 157must use @code{typeof} or @code{__auto_type} (@pxref{Typeof}). 158 159In G++, the result value of a statement expression undergoes array and 160function pointer decay, and is returned by value to the enclosing 161expression. For instance, if @code{A} is a class, then 162 163@smallexample 164 A a; 165 166 (@{a;@}).Foo () 167@end smallexample 168 169@noindent 170constructs a temporary @code{A} object to hold the result of the 171statement expression, and that is used to invoke @code{Foo}. 172Therefore the @code{this} pointer observed by @code{Foo} is not the 173address of @code{a}. 174 175In a statement expression, any temporaries created within a statement 176are destroyed at that statement's end. This makes statement 177expressions inside macros slightly different from function calls. In 178the latter case temporaries introduced during argument evaluation are 179destroyed at the end of the statement that includes the function 180call. In the statement expression case they are destroyed during 181the statement expression. For instance, 182 183@smallexample 184#define macro(a) (@{__typeof__(a) b = (a); b + 3; @}) 185template<typename T> T function(T a) @{ T b = a; return b + 3; @} 186 187void foo () 188@{ 189 macro (X ()); 190 function (X ()); 191@} 192@end smallexample 193 194@noindent 195has different places where temporaries are destroyed. For the 196@code{macro} case, the temporary @code{X} is destroyed just after 197the initialization of @code{b}. In the @code{function} case that 198temporary is destroyed when the function returns. 199 200These considerations mean that it is probably a bad idea to use 201statement expressions of this form in header files that are designed to 202work with C++. (Note that some versions of the GNU C Library contained 203header files using statement expressions that lead to precisely this 204bug.) 205 206Jumping into a statement expression with @code{goto} or using a 207@code{switch} statement outside the statement expression with a 208@code{case} or @code{default} label inside the statement expression is 209not permitted. Jumping into a statement expression with a computed 210@code{goto} (@pxref{Labels as Values}) has undefined behavior. 211Jumping out of a statement expression is permitted, but if the 212statement expression is part of a larger expression then it is 213unspecified which other subexpressions of that expression have been 214evaluated except where the language definition requires certain 215subexpressions to be evaluated before or after the statement 216expression. In any case, as with a function call, the evaluation of a 217statement expression is not interleaved with the evaluation of other 218parts of the containing expression. For example, 219 220@smallexample 221 foo (), ((@{ bar1 (); goto a; 0; @}) + bar2 ()), baz(); 222@end smallexample 223 224@noindent 225calls @code{foo} and @code{bar1} and does not call @code{baz} but 226may or may not call @code{bar2}. If @code{bar2} is called, it is 227called after @code{foo} and before @code{bar1}. 228 229@node Local Labels 230@section Locally Declared Labels 231@cindex local labels 232@cindex macros, local labels 233 234GCC allows you to declare @dfn{local labels} in any nested block 235scope. A local label is just like an ordinary label, but you can 236only reference it (with a @code{goto} statement, or by taking its 237address) within the block in which it is declared. 238 239A local label declaration looks like this: 240 241@smallexample 242__label__ @var{label}; 243@end smallexample 244 245@noindent 246or 247 248@smallexample 249__label__ @var{label1}, @var{label2}, /* @r{@dots{}} */; 250@end smallexample 251 252Local label declarations must come at the beginning of the block, 253before any ordinary declarations or statements. 254 255The label declaration defines the label @emph{name}, but does not define 256the label itself. You must do this in the usual way, with 257@code{@var{label}:}, within the statements of the statement expression. 258 259The local label feature is useful for complex macros. If a macro 260contains nested loops, a @code{goto} can be useful for breaking out of 261them. However, an ordinary label whose scope is the whole function 262cannot be used: if the macro can be expanded several times in one 263function, the label is multiply defined in that function. A 264local label avoids this problem. For example: 265 266@smallexample 267#define SEARCH(value, array, target) \ 268do @{ \ 269 __label__ found; \ 270 typeof (target) _SEARCH_target = (target); \ 271 typeof (*(array)) *_SEARCH_array = (array); \ 272 int i, j; \ 273 int value; \ 274 for (i = 0; i < max; i++) \ 275 for (j = 0; j < max; j++) \ 276 if (_SEARCH_array[i][j] == _SEARCH_target) \ 277 @{ (value) = i; goto found; @} \ 278 (value) = -1; \ 279 found:; \ 280@} while (0) 281@end smallexample 282 283This could also be written using a statement expression: 284 285@smallexample 286#define SEARCH(array, target) \ 287(@{ \ 288 __label__ found; \ 289 typeof (target) _SEARCH_target = (target); \ 290 typeof (*(array)) *_SEARCH_array = (array); \ 291 int i, j; \ 292 int value; \ 293 for (i = 0; i < max; i++) \ 294 for (j = 0; j < max; j++) \ 295 if (_SEARCH_array[i][j] == _SEARCH_target) \ 296 @{ value = i; goto found; @} \ 297 value = -1; \ 298 found: \ 299 value; \ 300@}) 301@end smallexample 302 303Local label declarations also make the labels they declare visible to 304nested functions, if there are any. @xref{Nested Functions}, for details. 305 306@node Labels as Values 307@section Labels as Values 308@cindex labels as values 309@cindex computed gotos 310@cindex goto with computed label 311@cindex address of a label 312 313You can get the address of a label defined in the current function 314(or a containing function) with the unary operator @samp{&&}. The 315value has type @code{void *}. This value is a constant and can be used 316wherever a constant of that type is valid. For example: 317 318@smallexample 319void *ptr; 320/* @r{@dots{}} */ 321ptr = &&foo; 322@end smallexample 323 324To use these values, you need to be able to jump to one. This is done 325with the computed goto statement@footnote{The analogous feature in 326Fortran is called an assigned goto, but that name seems inappropriate in 327C, where one can do more than simply store label addresses in label 328variables.}, @code{goto *@var{exp};}. For example, 329 330@smallexample 331goto *ptr; 332@end smallexample 333 334@noindent 335Any expression of type @code{void *} is allowed. 336 337One way of using these constants is in initializing a static array that 338serves as a jump table: 339 340@smallexample 341static void *array[] = @{ &&foo, &&bar, &&hack @}; 342@end smallexample 343 344@noindent 345Then you can select a label with indexing, like this: 346 347@smallexample 348goto *array[i]; 349@end smallexample 350 351@noindent 352Note that this does not check whether the subscript is in bounds---array 353indexing in C never does that. 354 355Such an array of label values serves a purpose much like that of the 356@code{switch} statement. The @code{switch} statement is cleaner, so 357use that rather than an array unless the problem does not fit a 358@code{switch} statement very well. 359 360Another use of label values is in an interpreter for threaded code. 361The labels within the interpreter function can be stored in the 362threaded code for super-fast dispatching. 363 364You may not use this mechanism to jump to code in a different function. 365If you do that, totally unpredictable things happen. The best way to 366avoid this is to store the label address only in automatic variables and 367never pass it as an argument. 368 369An alternate way to write the above example is 370 371@smallexample 372static const int array[] = @{ &&foo - &&foo, &&bar - &&foo, 373 &&hack - &&foo @}; 374goto *(&&foo + array[i]); 375@end smallexample 376 377@noindent 378This is more friendly to code living in shared libraries, as it reduces 379the number of dynamic relocations that are needed, and by consequence, 380allows the data to be read-only. 381This alternative with label differences is not supported for the AVR target, 382please use the first approach for AVR programs. 383 384The @code{&&foo} expressions for the same label might have different 385values if the containing function is inlined or cloned. If a program 386relies on them being always the same, 387@code{__attribute__((__noinline__,__noclone__))} should be used to 388prevent inlining and cloning. If @code{&&foo} is used in a static 389variable initializer, inlining and cloning is forbidden. 390 391@node Nested Functions 392@section Nested Functions 393@cindex nested functions 394@cindex downward funargs 395@cindex thunks 396 397A @dfn{nested function} is a function defined inside another function. 398Nested functions are supported as an extension in GNU C, but are not 399supported by GNU C++. 400 401The nested function's name is local to the block where it is defined. 402For example, here we define a nested function named @code{square}, and 403call it twice: 404 405@smallexample 406@group 407foo (double a, double b) 408@{ 409 double square (double z) @{ return z * z; @} 410 411 return square (a) + square (b); 412@} 413@end group 414@end smallexample 415 416The nested function can access all the variables of the containing 417function that are visible at the point of its definition. This is 418called @dfn{lexical scoping}. For example, here we show a nested 419function which uses an inherited variable named @code{offset}: 420 421@smallexample 422@group 423bar (int *array, int offset, int size) 424@{ 425 int access (int *array, int index) 426 @{ return array[index + offset]; @} 427 int i; 428 /* @r{@dots{}} */ 429 for (i = 0; i < size; i++) 430 /* @r{@dots{}} */ access (array, i) /* @r{@dots{}} */ 431@} 432@end group 433@end smallexample 434 435Nested function definitions are permitted within functions in the places 436where variable definitions are allowed; that is, in any block, mixed 437with the other declarations and statements in the block. 438 439It is possible to call the nested function from outside the scope of its 440name by storing its address or passing the address to another function: 441 442@smallexample 443hack (int *array, int size) 444@{ 445 void store (int index, int value) 446 @{ array[index] = value; @} 447 448 intermediate (store, size); 449@} 450@end smallexample 451 452Here, the function @code{intermediate} receives the address of 453@code{store} as an argument. If @code{intermediate} calls @code{store}, 454the arguments given to @code{store} are used to store into @code{array}. 455But this technique works only so long as the containing function 456(@code{hack}, in this example) does not exit. 457 458If you try to call the nested function through its address after the 459containing function exits, all hell breaks loose. If you try 460to call it after a containing scope level exits, and if it refers 461to some of the variables that are no longer in scope, you may be lucky, 462but it's not wise to take the risk. If, however, the nested function 463does not refer to anything that has gone out of scope, you should be 464safe. 465 466GCC implements taking the address of a nested function using a technique 467called @dfn{trampolines}. This technique was described in 468@cite{Lexical Closures for C++} (Thomas M. Breuel, USENIX 469C++ Conference Proceedings, October 17-21, 1988). 470 471A nested function can jump to a label inherited from a containing 472function, provided the label is explicitly declared in the containing 473function (@pxref{Local Labels}). Such a jump returns instantly to the 474containing function, exiting the nested function that did the 475@code{goto} and any intermediate functions as well. Here is an example: 476 477@smallexample 478@group 479bar (int *array, int offset, int size) 480@{ 481 __label__ failure; 482 int access (int *array, int index) 483 @{ 484 if (index > size) 485 goto failure; 486 return array[index + offset]; 487 @} 488 int i; 489 /* @r{@dots{}} */ 490 for (i = 0; i < size; i++) 491 /* @r{@dots{}} */ access (array, i) /* @r{@dots{}} */ 492 /* @r{@dots{}} */ 493 return 0; 494 495 /* @r{Control comes here from @code{access} 496 if it detects an error.} */ 497 failure: 498 return -1; 499@} 500@end group 501@end smallexample 502 503A nested function always has no linkage. Declaring one with 504@code{extern} or @code{static} is erroneous. If you need to declare the nested function 505before its definition, use @code{auto} (which is otherwise meaningless 506for function declarations). 507 508@smallexample 509bar (int *array, int offset, int size) 510@{ 511 __label__ failure; 512 auto int access (int *, int); 513 /* @r{@dots{}} */ 514 int access (int *array, int index) 515 @{ 516 if (index > size) 517 goto failure; 518 return array[index + offset]; 519 @} 520 /* @r{@dots{}} */ 521@} 522@end smallexample 523 524@node Constructing Calls 525@section Constructing Function Calls 526@cindex constructing calls 527@cindex forwarding calls 528 529Using the built-in functions described below, you can record 530the arguments a function received, and call another function 531with the same arguments, without knowing the number or types 532of the arguments. 533 534You can also record the return value of that function call, 535and later return that value, without knowing what data type 536the function tried to return (as long as your caller expects 537that data type). 538 539However, these built-in functions may interact badly with some 540sophisticated features or other extensions of the language. It 541is, therefore, not recommended to use them outside very simple 542functions acting as mere forwarders for their arguments. 543 544@deftypefn {Built-in Function} {void *} __builtin_apply_args () 545This built-in function returns a pointer to data 546describing how to perform a call with the same arguments as are passed 547to the current function. 548 549The function saves the arg pointer register, structure value address, 550and all registers that might be used to pass arguments to a function 551into a block of memory allocated on the stack. Then it returns the 552address of that block. 553@end deftypefn 554 555@deftypefn {Built-in Function} {void *} __builtin_apply (void (*@var{function})(), void *@var{arguments}, size_t @var{size}) 556This built-in function invokes @var{function} 557with a copy of the parameters described by @var{arguments} 558and @var{size}. 559 560The value of @var{arguments} should be the value returned by 561@code{__builtin_apply_args}. The argument @var{size} specifies the size 562of the stack argument data, in bytes. 563 564This function returns a pointer to data describing 565how to return whatever value is returned by @var{function}. The data 566is saved in a block of memory allocated on the stack. 567 568It is not always simple to compute the proper value for @var{size}. The 569value is used by @code{__builtin_apply} to compute the amount of data 570that should be pushed on the stack and copied from the incoming argument 571area. 572@end deftypefn 573 574@deftypefn {Built-in Function} {void} __builtin_return (void *@var{result}) 575This built-in function returns the value described by @var{result} from 576the containing function. You should specify, for @var{result}, a value 577returned by @code{__builtin_apply}. 578@end deftypefn 579 580@deftypefn {Built-in Function} {} __builtin_va_arg_pack () 581This built-in function represents all anonymous arguments of an inline 582function. It can be used only in inline functions that are always 583inlined, never compiled as a separate function, such as those using 584@code{__attribute__ ((__always_inline__))} or 585@code{__attribute__ ((__gnu_inline__))} extern inline functions. 586It must be only passed as last argument to some other function 587with variable arguments. This is useful for writing small wrapper 588inlines for variable argument functions, when using preprocessor 589macros is undesirable. For example: 590@smallexample 591extern int myprintf (FILE *f, const char *format, ...); 592extern inline __attribute__ ((__gnu_inline__)) int 593myprintf (FILE *f, const char *format, ...) 594@{ 595 int r = fprintf (f, "myprintf: "); 596 if (r < 0) 597 return r; 598 int s = fprintf (f, format, __builtin_va_arg_pack ()); 599 if (s < 0) 600 return s; 601 return r + s; 602@} 603@end smallexample 604@end deftypefn 605 606@deftypefn {Built-in Function} {size_t} __builtin_va_arg_pack_len () 607This built-in function returns the number of anonymous arguments of 608an inline function. It can be used only in inline functions that 609are always inlined, never compiled as a separate function, such 610as those using @code{__attribute__ ((__always_inline__))} or 611@code{__attribute__ ((__gnu_inline__))} extern inline functions. 612For example following does link- or run-time checking of open 613arguments for optimized code: 614@smallexample 615#ifdef __OPTIMIZE__ 616extern inline __attribute__((__gnu_inline__)) int 617myopen (const char *path, int oflag, ...) 618@{ 619 if (__builtin_va_arg_pack_len () > 1) 620 warn_open_too_many_arguments (); 621 622 if (__builtin_constant_p (oflag)) 623 @{ 624 if ((oflag & O_CREAT) != 0 && __builtin_va_arg_pack_len () < 1) 625 @{ 626 warn_open_missing_mode (); 627 return __open_2 (path, oflag); 628 @} 629 return open (path, oflag, __builtin_va_arg_pack ()); 630 @} 631 632 if (__builtin_va_arg_pack_len () < 1) 633 return __open_2 (path, oflag); 634 635 return open (path, oflag, __builtin_va_arg_pack ()); 636@} 637#endif 638@end smallexample 639@end deftypefn 640 641@node Typeof 642@section Referring to a Type with @code{typeof} 643@findex typeof 644@findex sizeof 645@cindex macros, types of arguments 646 647Another way to refer to the type of an expression is with @code{typeof}. 648The syntax of using of this keyword looks like @code{sizeof}, but the 649construct acts semantically like a type name defined with @code{typedef}. 650 651There are two ways of writing the argument to @code{typeof}: with an 652expression or with a type. Here is an example with an expression: 653 654@smallexample 655typeof (x[0](1)) 656@end smallexample 657 658@noindent 659This assumes that @code{x} is an array of pointers to functions; 660the type described is that of the values of the functions. 661 662Here is an example with a typename as the argument: 663 664@smallexample 665typeof (int *) 666@end smallexample 667 668@noindent 669Here the type described is that of pointers to @code{int}. 670 671If you are writing a header file that must work when included in ISO C 672programs, write @code{__typeof__} instead of @code{typeof}. 673@xref{Alternate Keywords}. 674 675A @code{typeof} construct can be used anywhere a typedef name can be 676used. For example, you can use it in a declaration, in a cast, or inside 677of @code{sizeof} or @code{typeof}. 678 679The operand of @code{typeof} is evaluated for its side effects if and 680only if it is an expression of variably modified type or the name of 681such a type. 682 683@code{typeof} is often useful in conjunction with 684statement expressions (@pxref{Statement Exprs}). 685Here is how the two together can 686be used to define a safe ``maximum'' macro which operates on any 687arithmetic type and evaluates each of its arguments exactly once: 688 689@smallexample 690#define max(a,b) \ 691 (@{ typeof (a) _a = (a); \ 692 typeof (b) _b = (b); \ 693 _a > _b ? _a : _b; @}) 694@end smallexample 695 696@cindex underscores in variables in macros 697@cindex @samp{_} in variables in macros 698@cindex local variables in macros 699@cindex variables, local, in macros 700@cindex macros, local variables in 701 702The reason for using names that start with underscores for the local 703variables is to avoid conflicts with variable names that occur within the 704expressions that are substituted for @code{a} and @code{b}. Eventually we 705hope to design a new form of declaration syntax that allows you to declare 706variables whose scopes start only after their initializers; this will be a 707more reliable way to prevent such conflicts. 708 709@noindent 710Some more examples of the use of @code{typeof}: 711 712@itemize @bullet 713@item 714This declares @code{y} with the type of what @code{x} points to. 715 716@smallexample 717typeof (*x) y; 718@end smallexample 719 720@item 721This declares @code{y} as an array of such values. 722 723@smallexample 724typeof (*x) y[4]; 725@end smallexample 726 727@item 728This declares @code{y} as an array of pointers to characters: 729 730@smallexample 731typeof (typeof (char *)[4]) y; 732@end smallexample 733 734@noindent 735It is equivalent to the following traditional C declaration: 736 737@smallexample 738char *y[4]; 739@end smallexample 740 741To see the meaning of the declaration using @code{typeof}, and why it 742might be a useful way to write, rewrite it with these macros: 743 744@smallexample 745#define pointer(T) typeof(T *) 746#define array(T, N) typeof(T [N]) 747@end smallexample 748 749@noindent 750Now the declaration can be rewritten this way: 751 752@smallexample 753array (pointer (char), 4) y; 754@end smallexample 755 756@noindent 757Thus, @code{array (pointer (char), 4)} is the type of arrays of 4 758pointers to @code{char}. 759@end itemize 760 761In GNU C, but not GNU C++, you may also declare the type of a variable 762as @code{__auto_type}. In that case, the declaration must declare 763only one variable, whose declarator must just be an identifier, the 764declaration must be initialized, and the type of the variable is 765determined by the initializer; the name of the variable is not in 766scope until after the initializer. (In C++, you should use C++11 767@code{auto} for this purpose.) Using @code{__auto_type}, the 768``maximum'' macro above could be written as: 769 770@smallexample 771#define max(a,b) \ 772 (@{ __auto_type _a = (a); \ 773 __auto_type _b = (b); \ 774 _a > _b ? _a : _b; @}) 775@end smallexample 776 777Using @code{__auto_type} instead of @code{typeof} has two advantages: 778 779@itemize @bullet 780@item Each argument to the macro appears only once in the expansion of 781the macro. This prevents the size of the macro expansion growing 782exponentially when calls to such macros are nested inside arguments of 783such macros. 784 785@item If the argument to the macro has variably modified type, it is 786evaluated only once when using @code{__auto_type}, but twice if 787@code{typeof} is used. 788@end itemize 789 790@node Conditionals 791@section Conditionals with Omitted Operands 792@cindex conditional expressions, extensions 793@cindex omitted middle-operands 794@cindex middle-operands, omitted 795@cindex extensions, @code{?:} 796@cindex @code{?:} extensions 797 798The middle operand in a conditional expression may be omitted. Then 799if the first operand is nonzero, its value is the value of the conditional 800expression. 801 802Therefore, the expression 803 804@smallexample 805x ? : y 806@end smallexample 807 808@noindent 809has the value of @code{x} if that is nonzero; otherwise, the value of 810@code{y}. 811 812This example is perfectly equivalent to 813 814@smallexample 815x ? x : y 816@end smallexample 817 818@cindex side effect in @code{?:} 819@cindex @code{?:} side effect 820@noindent 821In this simple case, the ability to omit the middle operand is not 822especially useful. When it becomes useful is when the first operand does, 823or may (if it is a macro argument), contain a side effect. Then repeating 824the operand in the middle would perform the side effect twice. Omitting 825the middle operand uses the value already computed without the undesirable 826effects of recomputing it. 827 828@node __int128 829@section 128-bit Integers 830@cindex @code{__int128} data types 831 832As an extension the integer scalar type @code{__int128} is supported for 833targets which have an integer mode wide enough to hold 128 bits. 834Simply write @code{__int128} for a signed 128-bit integer, or 835@code{unsigned __int128} for an unsigned 128-bit integer. There is no 836support in GCC for expressing an integer constant of type @code{__int128} 837for targets with @code{long long} integer less than 128 bits wide. 838 839@node Long Long 840@section Double-Word Integers 841@cindex @code{long long} data types 842@cindex double-word arithmetic 843@cindex multiprecision arithmetic 844@cindex @code{LL} integer suffix 845@cindex @code{ULL} integer suffix 846 847ISO C99 supports data types for integers that are at least 64 bits wide, 848and as an extension GCC supports them in C90 mode and in C++. 849Simply write @code{long long int} for a signed integer, or 850@code{unsigned long long int} for an unsigned integer. To make an 851integer constant of type @code{long long int}, add the suffix @samp{LL} 852to the integer. To make an integer constant of type @code{unsigned long 853long int}, add the suffix @samp{ULL} to the integer. 854 855You can use these types in arithmetic like any other integer types. 856Addition, subtraction, and bitwise boolean operations on these types 857are open-coded on all types of machines. Multiplication is open-coded 858if the machine supports a fullword-to-doubleword widening multiply 859instruction. Division and shifts are open-coded only on machines that 860provide special support. The operations that are not open-coded use 861special library routines that come with GCC@. 862 863There may be pitfalls when you use @code{long long} types for function 864arguments without function prototypes. If a function 865expects type @code{int} for its argument, and you pass a value of type 866@code{long long int}, confusion results because the caller and the 867subroutine disagree about the number of bytes for the argument. 868Likewise, if the function expects @code{long long int} and you pass 869@code{int}. The best way to avoid such problems is to use prototypes. 870 871@node Complex 872@section Complex Numbers 873@cindex complex numbers 874@cindex @code{_Complex} keyword 875@cindex @code{__complex__} keyword 876 877ISO C99 supports complex floating data types, and as an extension GCC 878supports them in C90 mode and in C++. GCC also supports complex integer data 879types which are not part of ISO C99. You can declare complex types 880using the keyword @code{_Complex}. As an extension, the older GNU 881keyword @code{__complex__} is also supported. 882 883For example, @samp{_Complex double x;} declares @code{x} as a 884variable whose real part and imaginary part are both of type 885@code{double}. @samp{_Complex short int y;} declares @code{y} to 886have real and imaginary parts of type @code{short int}; this is not 887likely to be useful, but it shows that the set of complex types is 888complete. 889 890To write a constant with a complex data type, use the suffix @samp{i} or 891@samp{j} (either one; they are equivalent). For example, @code{2.5fi} 892has type @code{_Complex float} and @code{3i} has type 893@code{_Complex int}. Such a constant always has a pure imaginary 894value, but you can form any complex value you like by adding one to a 895real constant. This is a GNU extension; if you have an ISO C99 896conforming C library (such as the GNU C Library), and want to construct complex 897constants of floating type, you should include @code{<complex.h>} and 898use the macros @code{I} or @code{_Complex_I} instead. 899 900The ISO C++14 library also defines the @samp{i} suffix, so C++14 code 901that includes the @samp{<complex>} header cannot use @samp{i} for the 902GNU extension. The @samp{j} suffix still has the GNU meaning. 903 904@cindex @code{__real__} keyword 905@cindex @code{__imag__} keyword 906To extract the real part of a complex-valued expression @var{exp}, write 907@code{__real__ @var{exp}}. Likewise, use @code{__imag__} to 908extract the imaginary part. This is a GNU extension; for values of 909floating type, you should use the ISO C99 functions @code{crealf}, 910@code{creal}, @code{creall}, @code{cimagf}, @code{cimag} and 911@code{cimagl}, declared in @code{<complex.h>} and also provided as 912built-in functions by GCC@. 913 914@cindex complex conjugation 915The operator @samp{~} performs complex conjugation when used on a value 916with a complex type. This is a GNU extension; for values of 917floating type, you should use the ISO C99 functions @code{conjf}, 918@code{conj} and @code{conjl}, declared in @code{<complex.h>} and also 919provided as built-in functions by GCC@. 920 921GCC can allocate complex automatic variables in a noncontiguous 922fashion; it's even possible for the real part to be in a register while 923the imaginary part is on the stack (or vice versa). Only the DWARF 924debug info format can represent this, so use of DWARF is recommended. 925If you are using the stabs debug info format, GCC describes a noncontiguous 926complex variable as if it were two separate variables of noncomplex type. 927If the variable's actual name is @code{foo}, the two fictitious 928variables are named @code{foo$real} and @code{foo$imag}. You can 929examine and set these two fictitious variables with your debugger. 930 931@node Floating Types 932@section Additional Floating Types 933@cindex additional floating types 934@cindex @code{_Float@var{n}} data types 935@cindex @code{_Float@var{n}x} data types 936@cindex @code{__float80} data type 937@cindex @code{__float128} data type 938@cindex @code{__ibm128} data type 939@cindex @code{w} floating point suffix 940@cindex @code{q} floating point suffix 941@cindex @code{W} floating point suffix 942@cindex @code{Q} floating point suffix 943 944ISO/IEC TS 18661-3:2015 defines C support for additional floating 945types @code{_Float@var{n}} and @code{_Float@var{n}x}, and GCC supports 946these type names; the set of types supported depends on the target 947architecture. These types are not supported when compiling C++. 948Constants with these types use suffixes @code{f@var{n}} or 949@code{F@var{n}} and @code{f@var{n}x} or @code{F@var{n}x}. These type 950names can be used together with @code{_Complex} to declare complex 951types. 952 953As an extension, GNU C and GNU C++ support additional floating 954types, which are not supported by all targets. 955@itemize @bullet 956@item @code{__float128} is available on i386, x86_64, IA-64, and 957hppa HP-UX, as well as on PowerPC GNU/Linux targets that enable 958the vector scalar (VSX) instruction set. @code{__float128} supports 959the 128-bit floating type. On i386, x86_64, PowerPC, and IA-64 960other than HP-UX, @code{__float128} is an alias for @code{_Float128}. 961On hppa and IA-64 HP-UX, @code{__float128} is an alias for @code{long 962double}. 963 964@item @code{__float80} is available on the i386, x86_64, and IA-64 965targets, and supports the 80-bit (@code{XFmode}) floating type. It is 966an alias for the type name @code{_Float64x} on these targets. 967 968@item @code{__ibm128} is available on PowerPC targets, and provides 969access to the IBM extended double format which is the current format 970used for @code{long double}. When @code{long double} transitions to 971@code{__float128} on PowerPC in the future, @code{__ibm128} will remain 972for use in conversions between the two types. 973@end itemize 974 975Support for these additional types includes the arithmetic operators: 976add, subtract, multiply, divide; unary arithmetic operators; 977relational operators; equality operators; and conversions to and from 978integer and other floating types. Use a suffix @samp{w} or @samp{W} 979in a literal constant of type @code{__float80} or type 980@code{__ibm128}. Use a suffix @samp{q} or @samp{Q} for @code{_float128}. 981 982In order to use @code{_Float128}, @code{__float128}, and @code{__ibm128} 983on PowerPC Linux systems, you must use the @option{-mfloat128} option. It is 984expected in future versions of GCC that @code{_Float128} and @code{__float128} 985will be enabled automatically. 986 987The @code{_Float128} type is supported on all systems where 988@code{__float128} is supported or where @code{long double} has the 989IEEE binary128 format. The @code{_Float64x} type is supported on all 990systems where @code{__float128} is supported. The @code{_Float32} 991type is supported on all systems supporting IEEE binary32; the 992@code{_Float64} and @code{_Float32x} types are supported on all systems 993supporting IEEE binary64. The @code{_Float16} type is supported on AArch64 994systems by default, and on ARM systems when the IEEE format for 16-bit 995floating-point types is selected with @option{-mfp16-format=ieee}. 996GCC does not currently support @code{_Float128x} on any systems. 997 998On the i386, x86_64, IA-64, and HP-UX targets, you can declare complex 999types using the corresponding internal complex type, @code{XCmode} for 1000@code{__float80} type and @code{TCmode} for @code{__float128} type: 1001 1002@smallexample 1003typedef _Complex float __attribute__((mode(TC))) _Complex128; 1004typedef _Complex float __attribute__((mode(XC))) _Complex80; 1005@end smallexample 1006 1007On the PowerPC Linux VSX targets, you can declare complex types using 1008the corresponding internal complex type, @code{KCmode} for 1009@code{__float128} type and @code{ICmode} for @code{__ibm128} type: 1010 1011@smallexample 1012typedef _Complex float __attribute__((mode(KC))) _Complex_float128; 1013typedef _Complex float __attribute__((mode(IC))) _Complex_ibm128; 1014@end smallexample 1015 1016@node Half-Precision 1017@section Half-Precision Floating Point 1018@cindex half-precision floating point 1019@cindex @code{__fp16} data type 1020 1021On ARM and AArch64 targets, GCC supports half-precision (16-bit) floating 1022point via the @code{__fp16} type defined in the ARM C Language Extensions. 1023On ARM systems, you must enable this type explicitly with the 1024@option{-mfp16-format} command-line option in order to use it. 1025 1026ARM targets support two incompatible representations for half-precision 1027floating-point values. You must choose one of the representations and 1028use it consistently in your program. 1029 1030Specifying @option{-mfp16-format=ieee} selects the IEEE 754-2008 format. 1031This format can represent normalized values in the range of @math{2^{-14}} to 65504. 1032There are 11 bits of significand precision, approximately 3 1033decimal digits. 1034 1035Specifying @option{-mfp16-format=alternative} selects the ARM 1036alternative format. This representation is similar to the IEEE 1037format, but does not support infinities or NaNs. Instead, the range 1038of exponents is extended, so that this format can represent normalized 1039values in the range of @math{2^{-14}} to 131008. 1040 1041The GCC port for AArch64 only supports the IEEE 754-2008 format, and does 1042not require use of the @option{-mfp16-format} command-line option. 1043 1044The @code{__fp16} type may only be used as an argument to intrinsics defined 1045in @code{<arm_fp16.h>}, or as a storage format. For purposes of 1046arithmetic and other operations, @code{__fp16} values in C or C++ 1047expressions are automatically promoted to @code{float}. 1048 1049The ARM target provides hardware support for conversions between 1050@code{__fp16} and @code{float} values 1051as an extension to VFP and NEON (Advanced SIMD), and from ARMv8-A provides 1052hardware support for conversions between @code{__fp16} and @code{double} 1053values. GCC generates code using these hardware instructions if you 1054compile with options to select an FPU that provides them; 1055for example, @option{-mfpu=neon-fp16 -mfloat-abi=softfp}, 1056in addition to the @option{-mfp16-format} option to select 1057a half-precision format. 1058 1059Language-level support for the @code{__fp16} data type is 1060independent of whether GCC generates code using hardware floating-point 1061instructions. In cases where hardware support is not specified, GCC 1062implements conversions between @code{__fp16} and other types as library 1063calls. 1064 1065It is recommended that portable code use the @code{_Float16} type defined 1066by ISO/IEC TS 18661-3:2015. @xref{Floating Types}. 1067 1068@node Decimal Float 1069@section Decimal Floating Types 1070@cindex decimal floating types 1071@cindex @code{_Decimal32} data type 1072@cindex @code{_Decimal64} data type 1073@cindex @code{_Decimal128} data type 1074@cindex @code{df} integer suffix 1075@cindex @code{dd} integer suffix 1076@cindex @code{dl} integer suffix 1077@cindex @code{DF} integer suffix 1078@cindex @code{DD} integer suffix 1079@cindex @code{DL} integer suffix 1080 1081As an extension, GNU C supports decimal floating types as 1082defined in the N1312 draft of ISO/IEC WDTR24732. Support for decimal 1083floating types in GCC will evolve as the draft technical report changes. 1084Calling conventions for any target might also change. Not all targets 1085support decimal floating types. 1086 1087The decimal floating types are @code{_Decimal32}, @code{_Decimal64}, and 1088@code{_Decimal128}. They use a radix of ten, unlike the floating types 1089@code{float}, @code{double}, and @code{long double} whose radix is not 1090specified by the C standard but is usually two. 1091 1092Support for decimal floating types includes the arithmetic operators 1093add, subtract, multiply, divide; unary arithmetic operators; 1094relational operators; equality operators; and conversions to and from 1095integer and other floating types. Use a suffix @samp{df} or 1096@samp{DF} in a literal constant of type @code{_Decimal32}, @samp{dd} 1097or @samp{DD} for @code{_Decimal64}, and @samp{dl} or @samp{DL} for 1098@code{_Decimal128}. 1099 1100GCC support of decimal float as specified by the draft technical report 1101is incomplete: 1102 1103@itemize @bullet 1104@item 1105When the value of a decimal floating type cannot be represented in the 1106integer type to which it is being converted, the result is undefined 1107rather than the result value specified by the draft technical report. 1108 1109@item 1110GCC does not provide the C library functionality associated with 1111@file{math.h}, @file{fenv.h}, @file{stdio.h}, @file{stdlib.h}, and 1112@file{wchar.h}, which must come from a separate C library implementation. 1113Because of this the GNU C compiler does not define macro 1114@code{__STDC_DEC_FP__} to indicate that the implementation conforms to 1115the technical report. 1116@end itemize 1117 1118Types @code{_Decimal32}, @code{_Decimal64}, and @code{_Decimal128} 1119are supported by the DWARF debug information format. 1120 1121@node Hex Floats 1122@section Hex Floats 1123@cindex hex floats 1124 1125ISO C99 supports floating-point numbers written not only in the usual 1126decimal notation, such as @code{1.55e1}, but also numbers such as 1127@code{0x1.fp3} written in hexadecimal format. As a GNU extension, GCC 1128supports this in C90 mode (except in some cases when strictly 1129conforming) and in C++. In that format the 1130@samp{0x} hex introducer and the @samp{p} or @samp{P} exponent field are 1131mandatory. The exponent is a decimal number that indicates the power of 11322 by which the significant part is multiplied. Thus @samp{0x1.f} is 1133@tex 1134$1 {15\over16}$, 1135@end tex 1136@ifnottex 11371 15/16, 1138@end ifnottex 1139@samp{p3} multiplies it by 8, and the value of @code{0x1.fp3} 1140is the same as @code{1.55e1}. 1141 1142Unlike for floating-point numbers in the decimal notation the exponent 1143is always required in the hexadecimal notation. Otherwise the compiler 1144would not be able to resolve the ambiguity of, e.g., @code{0x1.f}. This 1145could mean @code{1.0f} or @code{1.9375} since @samp{f} is also the 1146extension for floating-point constants of type @code{float}. 1147 1148@node Fixed-Point 1149@section Fixed-Point Types 1150@cindex fixed-point types 1151@cindex @code{_Fract} data type 1152@cindex @code{_Accum} data type 1153@cindex @code{_Sat} data type 1154@cindex @code{hr} fixed-suffix 1155@cindex @code{r} fixed-suffix 1156@cindex @code{lr} fixed-suffix 1157@cindex @code{llr} fixed-suffix 1158@cindex @code{uhr} fixed-suffix 1159@cindex @code{ur} fixed-suffix 1160@cindex @code{ulr} fixed-suffix 1161@cindex @code{ullr} fixed-suffix 1162@cindex @code{hk} fixed-suffix 1163@cindex @code{k} fixed-suffix 1164@cindex @code{lk} fixed-suffix 1165@cindex @code{llk} fixed-suffix 1166@cindex @code{uhk} fixed-suffix 1167@cindex @code{uk} fixed-suffix 1168@cindex @code{ulk} fixed-suffix 1169@cindex @code{ullk} fixed-suffix 1170@cindex @code{HR} fixed-suffix 1171@cindex @code{R} fixed-suffix 1172@cindex @code{LR} fixed-suffix 1173@cindex @code{LLR} fixed-suffix 1174@cindex @code{UHR} fixed-suffix 1175@cindex @code{UR} fixed-suffix 1176@cindex @code{ULR} fixed-suffix 1177@cindex @code{ULLR} fixed-suffix 1178@cindex @code{HK} fixed-suffix 1179@cindex @code{K} fixed-suffix 1180@cindex @code{LK} fixed-suffix 1181@cindex @code{LLK} fixed-suffix 1182@cindex @code{UHK} fixed-suffix 1183@cindex @code{UK} fixed-suffix 1184@cindex @code{ULK} fixed-suffix 1185@cindex @code{ULLK} fixed-suffix 1186 1187As an extension, GNU C supports fixed-point types as 1188defined in the N1169 draft of ISO/IEC DTR 18037. Support for fixed-point 1189types in GCC will evolve as the draft technical report changes. 1190Calling conventions for any target might also change. Not all targets 1191support fixed-point types. 1192 1193The fixed-point types are 1194@code{short _Fract}, 1195@code{_Fract}, 1196@code{long _Fract}, 1197@code{long long _Fract}, 1198@code{unsigned short _Fract}, 1199@code{unsigned _Fract}, 1200@code{unsigned long _Fract}, 1201@code{unsigned long long _Fract}, 1202@code{_Sat short _Fract}, 1203@code{_Sat _Fract}, 1204@code{_Sat long _Fract}, 1205@code{_Sat long long _Fract}, 1206@code{_Sat unsigned short _Fract}, 1207@code{_Sat unsigned _Fract}, 1208@code{_Sat unsigned long _Fract}, 1209@code{_Sat unsigned long long _Fract}, 1210@code{short _Accum}, 1211@code{_Accum}, 1212@code{long _Accum}, 1213@code{long long _Accum}, 1214@code{unsigned short _Accum}, 1215@code{unsigned _Accum}, 1216@code{unsigned long _Accum}, 1217@code{unsigned long long _Accum}, 1218@code{_Sat short _Accum}, 1219@code{_Sat _Accum}, 1220@code{_Sat long _Accum}, 1221@code{_Sat long long _Accum}, 1222@code{_Sat unsigned short _Accum}, 1223@code{_Sat unsigned _Accum}, 1224@code{_Sat unsigned long _Accum}, 1225@code{_Sat unsigned long long _Accum}. 1226 1227Fixed-point data values contain fractional and optional integral parts. 1228The format of fixed-point data varies and depends on the target machine. 1229 1230Support for fixed-point types includes: 1231@itemize @bullet 1232@item 1233prefix and postfix increment and decrement operators (@code{++}, @code{--}) 1234@item 1235unary arithmetic operators (@code{+}, @code{-}, @code{!}) 1236@item 1237binary arithmetic operators (@code{+}, @code{-}, @code{*}, @code{/}) 1238@item 1239binary shift operators (@code{<<}, @code{>>}) 1240@item 1241relational operators (@code{<}, @code{<=}, @code{>=}, @code{>}) 1242@item 1243equality operators (@code{==}, @code{!=}) 1244@item 1245assignment operators (@code{+=}, @code{-=}, @code{*=}, @code{/=}, 1246@code{<<=}, @code{>>=}) 1247@item 1248conversions to and from integer, floating-point, or fixed-point types 1249@end itemize 1250 1251Use a suffix in a fixed-point literal constant: 1252@itemize 1253@item @samp{hr} or @samp{HR} for @code{short _Fract} and 1254@code{_Sat short _Fract} 1255@item @samp{r} or @samp{R} for @code{_Fract} and @code{_Sat _Fract} 1256@item @samp{lr} or @samp{LR} for @code{long _Fract} and 1257@code{_Sat long _Fract} 1258@item @samp{llr} or @samp{LLR} for @code{long long _Fract} and 1259@code{_Sat long long _Fract} 1260@item @samp{uhr} or @samp{UHR} for @code{unsigned short _Fract} and 1261@code{_Sat unsigned short _Fract} 1262@item @samp{ur} or @samp{UR} for @code{unsigned _Fract} and 1263@code{_Sat unsigned _Fract} 1264@item @samp{ulr} or @samp{ULR} for @code{unsigned long _Fract} and 1265@code{_Sat unsigned long _Fract} 1266@item @samp{ullr} or @samp{ULLR} for @code{unsigned long long _Fract} 1267and @code{_Sat unsigned long long _Fract} 1268@item @samp{hk} or @samp{HK} for @code{short _Accum} and 1269@code{_Sat short _Accum} 1270@item @samp{k} or @samp{K} for @code{_Accum} and @code{_Sat _Accum} 1271@item @samp{lk} or @samp{LK} for @code{long _Accum} and 1272@code{_Sat long _Accum} 1273@item @samp{llk} or @samp{LLK} for @code{long long _Accum} and 1274@code{_Sat long long _Accum} 1275@item @samp{uhk} or @samp{UHK} for @code{unsigned short _Accum} and 1276@code{_Sat unsigned short _Accum} 1277@item @samp{uk} or @samp{UK} for @code{unsigned _Accum} and 1278@code{_Sat unsigned _Accum} 1279@item @samp{ulk} or @samp{ULK} for @code{unsigned long _Accum} and 1280@code{_Sat unsigned long _Accum} 1281@item @samp{ullk} or @samp{ULLK} for @code{unsigned long long _Accum} 1282and @code{_Sat unsigned long long _Accum} 1283@end itemize 1284 1285GCC support of fixed-point types as specified by the draft technical report 1286is incomplete: 1287 1288@itemize @bullet 1289@item 1290Pragmas to control overflow and rounding behaviors are not implemented. 1291@end itemize 1292 1293Fixed-point types are supported by the DWARF debug information format. 1294 1295@node Named Address Spaces 1296@section Named Address Spaces 1297@cindex Named Address Spaces 1298 1299As an extension, GNU C supports named address spaces as 1300defined in the N1275 draft of ISO/IEC DTR 18037. Support for named 1301address spaces in GCC will evolve as the draft technical report 1302changes. Calling conventions for any target might also change. At 1303present, only the AVR, SPU, M32C, RL78, and x86 targets support 1304address spaces other than the generic address space. 1305 1306Address space identifiers may be used exactly like any other C type 1307qualifier (e.g., @code{const} or @code{volatile}). See the N1275 1308document for more details. 1309 1310@anchor{AVR Named Address Spaces} 1311@subsection AVR Named Address Spaces 1312 1313On the AVR target, there are several address spaces that can be used 1314in order to put read-only data into the flash memory and access that 1315data by means of the special instructions @code{LPM} or @code{ELPM} 1316needed to read from flash. 1317 1318Devices belonging to @code{avrtiny} and @code{avrxmega3} can access 1319flash memory by means of @code{LD*} instructions because the flash 1320memory is mapped into the RAM address space. There is @emph{no need} 1321for language extensions like @code{__flash} or attribute 1322@ref{AVR Variable Attributes,,@code{progmem}}. 1323The default linker description files for these devices cater for that 1324feature and @code{.rodata} stays in flash: The compiler just generates 1325@code{LD*} instructions, and the linker script adds core specific 1326offsets to all @code{.rodata} symbols: @code{0x4000} in the case of 1327@code{avrtiny} and @code{0x8000} in the case of @code{avrxmega3}. 1328See @ref{AVR Options} for a list of respective devices. 1329 1330For devices not in @code{avrtiny} or @code{avrxmega3}, 1331any data including read-only data is located in RAM (the generic 1332address space) because flash memory is not visible in the RAM address 1333space. In order to locate read-only data in flash memory @emph{and} 1334to generate the right instructions to access this data without 1335using (inline) assembler code, special address spaces are needed. 1336 1337@table @code 1338@item __flash 1339@cindex @code{__flash} AVR Named Address Spaces 1340The @code{__flash} qualifier locates data in the 1341@code{.progmem.data} section. Data is read using the @code{LPM} 1342instruction. Pointers to this address space are 16 bits wide. 1343 1344@item __flash1 1345@itemx __flash2 1346@itemx __flash3 1347@itemx __flash4 1348@itemx __flash5 1349@cindex @code{__flash1} AVR Named Address Spaces 1350@cindex @code{__flash2} AVR Named Address Spaces 1351@cindex @code{__flash3} AVR Named Address Spaces 1352@cindex @code{__flash4} AVR Named Address Spaces 1353@cindex @code{__flash5} AVR Named Address Spaces 1354These are 16-bit address spaces locating data in section 1355@code{.progmem@var{N}.data} where @var{N} refers to 1356address space @code{__flash@var{N}}. 1357The compiler sets the @code{RAMPZ} segment register appropriately 1358before reading data by means of the @code{ELPM} instruction. 1359 1360@item __memx 1361@cindex @code{__memx} AVR Named Address Spaces 1362This is a 24-bit address space that linearizes flash and RAM: 1363If the high bit of the address is set, data is read from 1364RAM using the lower two bytes as RAM address. 1365If the high bit of the address is clear, data is read from flash 1366with @code{RAMPZ} set according to the high byte of the address. 1367@xref{AVR Built-in Functions,,@code{__builtin_avr_flash_segment}}. 1368 1369Objects in this address space are located in @code{.progmemx.data}. 1370@end table 1371 1372@b{Example} 1373 1374@smallexample 1375char my_read (const __flash char ** p) 1376@{ 1377 /* p is a pointer to RAM that points to a pointer to flash. 1378 The first indirection of p reads that flash pointer 1379 from RAM and the second indirection reads a char from this 1380 flash address. */ 1381 1382 return **p; 1383@} 1384 1385/* Locate array[] in flash memory */ 1386const __flash int array[] = @{ 3, 5, 7, 11, 13, 17, 19 @}; 1387 1388int i = 1; 1389 1390int main (void) 1391@{ 1392 /* Return 17 by reading from flash memory */ 1393 return array[array[i]]; 1394@} 1395@end smallexample 1396 1397@noindent 1398For each named address space supported by avr-gcc there is an equally 1399named but uppercase built-in macro defined. 1400The purpose is to facilitate testing if respective address space 1401support is available or not: 1402 1403@smallexample 1404#ifdef __FLASH 1405const __flash int var = 1; 1406 1407int read_var (void) 1408@{ 1409 return var; 1410@} 1411#else 1412#include <avr/pgmspace.h> /* From AVR-LibC */ 1413 1414const int var PROGMEM = 1; 1415 1416int read_var (void) 1417@{ 1418 return (int) pgm_read_word (&var); 1419@} 1420#endif /* __FLASH */ 1421@end smallexample 1422 1423@noindent 1424Notice that attribute @ref{AVR Variable Attributes,,@code{progmem}} 1425locates data in flash but 1426accesses to these data read from generic address space, i.e.@: 1427from RAM, 1428so that you need special accessors like @code{pgm_read_byte} 1429from @w{@uref{http://nongnu.org/avr-libc/user-manual/,AVR-LibC}} 1430together with attribute @code{progmem}. 1431 1432@noindent 1433@b{Limitations and caveats} 1434 1435@itemize 1436@item 1437Reading across the 64@tie{}KiB section boundary of 1438the @code{__flash} or @code{__flash@var{N}} address spaces 1439shows undefined behavior. The only address space that 1440supports reading across the 64@tie{}KiB flash segment boundaries is 1441@code{__memx}. 1442 1443@item 1444If you use one of the @code{__flash@var{N}} address spaces 1445you must arrange your linker script to locate the 1446@code{.progmem@var{N}.data} sections according to your needs. 1447 1448@item 1449Any data or pointers to the non-generic address spaces must 1450be qualified as @code{const}, i.e.@: as read-only data. 1451This still applies if the data in one of these address 1452spaces like software version number or calibration lookup table are intended to 1453be changed after load time by, say, a boot loader. In this case 1454the right qualification is @code{const} @code{volatile} so that the compiler 1455must not optimize away known values or insert them 1456as immediates into operands of instructions. 1457 1458@item 1459The following code initializes a variable @code{pfoo} 1460located in static storage with a 24-bit address: 1461@smallexample 1462extern const __memx char foo; 1463const __memx void *pfoo = &foo; 1464@end smallexample 1465 1466@item 1467On the reduced Tiny devices like ATtiny40, no address spaces are supported. 1468Just use vanilla C / C++ code without overhead as outlined above. 1469Attribute @code{progmem} is supported but works differently, 1470see @ref{AVR Variable Attributes}. 1471 1472@end itemize 1473 1474@subsection M32C Named Address Spaces 1475@cindex @code{__far} M32C Named Address Spaces 1476 1477On the M32C target, with the R8C and M16C CPU variants, variables 1478qualified with @code{__far} are accessed using 32-bit addresses in 1479order to access memory beyond the first 64@tie{}Ki bytes. If 1480@code{__far} is used with the M32CM or M32C CPU variants, it has no 1481effect. 1482 1483@subsection RL78 Named Address Spaces 1484@cindex @code{__far} RL78 Named Address Spaces 1485 1486On the RL78 target, variables qualified with @code{__far} are accessed 1487with 32-bit pointers (20-bit addresses) rather than the default 16-bit 1488addresses. Non-far variables are assumed to appear in the topmost 148964@tie{}KiB of the address space. 1490 1491@subsection SPU Named Address Spaces 1492@cindex @code{__ea} SPU Named Address Spaces 1493 1494On the SPU target variables may be declared as 1495belonging to another address space by qualifying the type with the 1496@code{__ea} address space identifier: 1497 1498@smallexample 1499extern int __ea i; 1500@end smallexample 1501 1502@noindent 1503The compiler generates special code to access the variable @code{i}. 1504It may use runtime library 1505support, or generate special machine instructions to access that address 1506space. 1507 1508@subsection x86 Named Address Spaces 1509@cindex x86 named address spaces 1510 1511On the x86 target, variables may be declared as being relative 1512to the @code{%fs} or @code{%gs} segments. 1513 1514@table @code 1515@item __seg_fs 1516@itemx __seg_gs 1517@cindex @code{__seg_fs} x86 named address space 1518@cindex @code{__seg_gs} x86 named address space 1519The object is accessed with the respective segment override prefix. 1520 1521The respective segment base must be set via some method specific to 1522the operating system. Rather than require an expensive system call 1523to retrieve the segment base, these address spaces are not considered 1524to be subspaces of the generic (flat) address space. This means that 1525explicit casts are required to convert pointers between these address 1526spaces and the generic address space. In practice the application 1527should cast to @code{uintptr_t} and apply the segment base offset 1528that it installed previously. 1529 1530The preprocessor symbols @code{__SEG_FS} and @code{__SEG_GS} are 1531defined when these address spaces are supported. 1532@end table 1533 1534@node Zero Length 1535@section Arrays of Length Zero 1536@cindex arrays of length zero 1537@cindex zero-length arrays 1538@cindex length-zero arrays 1539@cindex flexible array members 1540 1541Zero-length arrays are allowed in GNU C@. They are very useful as the 1542last element of a structure that is really a header for a variable-length 1543object: 1544 1545@smallexample 1546struct line @{ 1547 int length; 1548 char contents[0]; 1549@}; 1550 1551struct line *thisline = (struct line *) 1552 malloc (sizeof (struct line) + this_length); 1553thisline->length = this_length; 1554@end smallexample 1555 1556In ISO C90, you would have to give @code{contents} a length of 1, which 1557means either you waste space or complicate the argument to @code{malloc}. 1558 1559In ISO C99, you would use a @dfn{flexible array member}, which is 1560slightly different in syntax and semantics: 1561 1562@itemize @bullet 1563@item 1564Flexible array members are written as @code{contents[]} without 1565the @code{0}. 1566 1567@item 1568Flexible array members have incomplete type, and so the @code{sizeof} 1569operator may not be applied. As a quirk of the original implementation 1570of zero-length arrays, @code{sizeof} evaluates to zero. 1571 1572@item 1573Flexible array members may only appear as the last member of a 1574@code{struct} that is otherwise non-empty. 1575 1576@item 1577A structure containing a flexible array member, or a union containing 1578such a structure (possibly recursively), may not be a member of a 1579structure or an element of an array. (However, these uses are 1580permitted by GCC as extensions.) 1581@end itemize 1582 1583Non-empty initialization of zero-length 1584arrays is treated like any case where there are more initializer 1585elements than the array holds, in that a suitable warning about ``excess 1586elements in array'' is given, and the excess elements (all of them, in 1587this case) are ignored. 1588 1589GCC allows static initialization of flexible array members. 1590This is equivalent to defining a new structure containing the original 1591structure followed by an array of sufficient size to contain the data. 1592E.g.@: in the following, @code{f1} is constructed as if it were declared 1593like @code{f2}. 1594 1595@smallexample 1596struct f1 @{ 1597 int x; int y[]; 1598@} f1 = @{ 1, @{ 2, 3, 4 @} @}; 1599 1600struct f2 @{ 1601 struct f1 f1; int data[3]; 1602@} f2 = @{ @{ 1 @}, @{ 2, 3, 4 @} @}; 1603@end smallexample 1604 1605@noindent 1606The convenience of this extension is that @code{f1} has the desired 1607type, eliminating the need to consistently refer to @code{f2.f1}. 1608 1609This has symmetry with normal static arrays, in that an array of 1610unknown size is also written with @code{[]}. 1611 1612Of course, this extension only makes sense if the extra data comes at 1613the end of a top-level object, as otherwise we would be overwriting 1614data at subsequent offsets. To avoid undue complication and confusion 1615with initialization of deeply nested arrays, we simply disallow any 1616non-empty initialization except when the structure is the top-level 1617object. For example: 1618 1619@smallexample 1620struct foo @{ int x; int y[]; @}; 1621struct bar @{ struct foo z; @}; 1622 1623struct foo a = @{ 1, @{ 2, 3, 4 @} @}; // @r{Valid.} 1624struct bar b = @{ @{ 1, @{ 2, 3, 4 @} @} @}; // @r{Invalid.} 1625struct bar c = @{ @{ 1, @{ @} @} @}; // @r{Valid.} 1626struct foo d[1] = @{ @{ 1, @{ 2, 3, 4 @} @} @}; // @r{Invalid.} 1627@end smallexample 1628 1629@node Empty Structures 1630@section Structures with No Members 1631@cindex empty structures 1632@cindex zero-size structures 1633 1634GCC permits a C structure to have no members: 1635 1636@smallexample 1637struct empty @{ 1638@}; 1639@end smallexample 1640 1641The structure has size zero. In C++, empty structures are part 1642of the language. G++ treats empty structures as if they had a single 1643member of type @code{char}. 1644 1645@node Variable Length 1646@section Arrays of Variable Length 1647@cindex variable-length arrays 1648@cindex arrays of variable length 1649@cindex VLAs 1650 1651Variable-length automatic arrays are allowed in ISO C99, and as an 1652extension GCC accepts them in C90 mode and in C++. These arrays are 1653declared like any other automatic arrays, but with a length that is not 1654a constant expression. The storage is allocated at the point of 1655declaration and deallocated when the block scope containing the declaration 1656exits. For 1657example: 1658 1659@smallexample 1660FILE * 1661concat_fopen (char *s1, char *s2, char *mode) 1662@{ 1663 char str[strlen (s1) + strlen (s2) + 1]; 1664 strcpy (str, s1); 1665 strcat (str, s2); 1666 return fopen (str, mode); 1667@} 1668@end smallexample 1669 1670@cindex scope of a variable length array 1671@cindex variable-length array scope 1672@cindex deallocating variable length arrays 1673Jumping or breaking out of the scope of the array name deallocates the 1674storage. Jumping into the scope is not allowed; you get an error 1675message for it. 1676 1677@cindex variable-length array in a structure 1678As an extension, GCC accepts variable-length arrays as a member of 1679a structure or a union. For example: 1680 1681@smallexample 1682void 1683foo (int n) 1684@{ 1685 struct S @{ int x[n]; @}; 1686@} 1687@end smallexample 1688 1689@cindex @code{alloca} vs variable-length arrays 1690You can use the function @code{alloca} to get an effect much like 1691variable-length arrays. The function @code{alloca} is available in 1692many other C implementations (but not in all). On the other hand, 1693variable-length arrays are more elegant. 1694 1695There are other differences between these two methods. Space allocated 1696with @code{alloca} exists until the containing @emph{function} returns. 1697The space for a variable-length array is deallocated as soon as the array 1698name's scope ends, unless you also use @code{alloca} in this scope. 1699 1700You can also use variable-length arrays as arguments to functions: 1701 1702@smallexample 1703struct entry 1704tester (int len, char data[len][len]) 1705@{ 1706 /* @r{@dots{}} */ 1707@} 1708@end smallexample 1709 1710The length of an array is computed once when the storage is allocated 1711and is remembered for the scope of the array in case you access it with 1712@code{sizeof}. 1713 1714If you want to pass the array first and the length afterward, you can 1715use a forward declaration in the parameter list---another GNU extension. 1716 1717@smallexample 1718struct entry 1719tester (int len; char data[len][len], int len) 1720@{ 1721 /* @r{@dots{}} */ 1722@} 1723@end smallexample 1724 1725@cindex parameter forward declaration 1726The @samp{int len} before the semicolon is a @dfn{parameter forward 1727declaration}, and it serves the purpose of making the name @code{len} 1728known when the declaration of @code{data} is parsed. 1729 1730You can write any number of such parameter forward declarations in the 1731parameter list. They can be separated by commas or semicolons, but the 1732last one must end with a semicolon, which is followed by the ``real'' 1733parameter declarations. Each forward declaration must match a ``real'' 1734declaration in parameter name and data type. ISO C99 does not support 1735parameter forward declarations. 1736 1737@node Variadic Macros 1738@section Macros with a Variable Number of Arguments. 1739@cindex variable number of arguments 1740@cindex macro with variable arguments 1741@cindex rest argument (in macro) 1742@cindex variadic macros 1743 1744In the ISO C standard of 1999, a macro can be declared to accept a 1745variable number of arguments much as a function can. The syntax for 1746defining the macro is similar to that of a function. Here is an 1747example: 1748 1749@smallexample 1750#define debug(format, ...) fprintf (stderr, format, __VA_ARGS__) 1751@end smallexample 1752 1753@noindent 1754Here @samp{@dots{}} is a @dfn{variable argument}. In the invocation of 1755such a macro, it represents the zero or more tokens until the closing 1756parenthesis that ends the invocation, including any commas. This set of 1757tokens replaces the identifier @code{__VA_ARGS__} in the macro body 1758wherever it appears. See the CPP manual for more information. 1759 1760GCC has long supported variadic macros, and used a different syntax that 1761allowed you to give a name to the variable arguments just like any other 1762argument. Here is an example: 1763 1764@smallexample 1765#define debug(format, args...) fprintf (stderr, format, args) 1766@end smallexample 1767 1768@noindent 1769This is in all ways equivalent to the ISO C example above, but arguably 1770more readable and descriptive. 1771 1772GNU CPP has two further variadic macro extensions, and permits them to 1773be used with either of the above forms of macro definition. 1774 1775In standard C, you are not allowed to leave the variable argument out 1776entirely; but you are allowed to pass an empty argument. For example, 1777this invocation is invalid in ISO C, because there is no comma after 1778the string: 1779 1780@smallexample 1781debug ("A message") 1782@end smallexample 1783 1784GNU CPP permits you to completely omit the variable arguments in this 1785way. In the above examples, the compiler would complain, though since 1786the expansion of the macro still has the extra comma after the format 1787string. 1788 1789To help solve this problem, CPP behaves specially for variable arguments 1790used with the token paste operator, @samp{##}. If instead you write 1791 1792@smallexample 1793#define debug(format, ...) fprintf (stderr, format, ## __VA_ARGS__) 1794@end smallexample 1795 1796@noindent 1797and if the variable arguments are omitted or empty, the @samp{##} 1798operator causes the preprocessor to remove the comma before it. If you 1799do provide some variable arguments in your macro invocation, GNU CPP 1800does not complain about the paste operation and instead places the 1801variable arguments after the comma. Just like any other pasted macro 1802argument, these arguments are not macro expanded. 1803 1804@node Escaped Newlines 1805@section Slightly Looser Rules for Escaped Newlines 1806@cindex escaped newlines 1807@cindex newlines (escaped) 1808 1809The preprocessor treatment of escaped newlines is more relaxed 1810than that specified by the C90 standard, which requires the newline 1811to immediately follow a backslash. 1812GCC's implementation allows whitespace in the form 1813of spaces, horizontal and vertical tabs, and form feeds between the 1814backslash and the subsequent newline. The preprocessor issues a 1815warning, but treats it as a valid escaped newline and combines the two 1816lines to form a single logical line. This works within comments and 1817tokens, as well as between tokens. Comments are @emph{not} treated as 1818whitespace for the purposes of this relaxation, since they have not 1819yet been replaced with spaces. 1820 1821@node Subscripting 1822@section Non-Lvalue Arrays May Have Subscripts 1823@cindex subscripting 1824@cindex arrays, non-lvalue 1825 1826@cindex subscripting and function values 1827In ISO C99, arrays that are not lvalues still decay to pointers, and 1828may be subscripted, although they may not be modified or used after 1829the next sequence point and the unary @samp{&} operator may not be 1830applied to them. As an extension, GNU C allows such arrays to be 1831subscripted in C90 mode, though otherwise they do not decay to 1832pointers outside C99 mode. For example, 1833this is valid in GNU C though not valid in C90: 1834 1835@smallexample 1836@group 1837struct foo @{int a[4];@}; 1838 1839struct foo f(); 1840 1841bar (int index) 1842@{ 1843 return f().a[index]; 1844@} 1845@end group 1846@end smallexample 1847 1848@node Pointer Arith 1849@section Arithmetic on @code{void}- and Function-Pointers 1850@cindex void pointers, arithmetic 1851@cindex void, size of pointer to 1852@cindex function pointers, arithmetic 1853@cindex function, size of pointer to 1854 1855In GNU C, addition and subtraction operations are supported on pointers to 1856@code{void} and on pointers to functions. This is done by treating the 1857size of a @code{void} or of a function as 1. 1858 1859A consequence of this is that @code{sizeof} is also allowed on @code{void} 1860and on function types, and returns 1. 1861 1862@opindex Wpointer-arith 1863The option @option{-Wpointer-arith} requests a warning if these extensions 1864are used. 1865 1866@node Pointers to Arrays 1867@section Pointers to Arrays with Qualifiers Work as Expected 1868@cindex pointers to arrays 1869@cindex const qualifier 1870 1871In GNU C, pointers to arrays with qualifiers work similar to pointers 1872to other qualified types. For example, a value of type @code{int (*)[5]} 1873can be used to initialize a variable of type @code{const int (*)[5]}. 1874These types are incompatible in ISO C because the @code{const} qualifier 1875is formally attached to the element type of the array and not the 1876array itself. 1877 1878@smallexample 1879extern void 1880transpose (int N, int M, double out[M][N], const double in[N][M]); 1881double x[3][2]; 1882double y[2][3]; 1883@r{@dots{}} 1884transpose(3, 2, y, x); 1885@end smallexample 1886 1887@node Initializers 1888@section Non-Constant Initializers 1889@cindex initializers, non-constant 1890@cindex non-constant initializers 1891 1892As in standard C++ and ISO C99, the elements of an aggregate initializer for an 1893automatic variable are not required to be constant expressions in GNU C@. 1894Here is an example of an initializer with run-time varying elements: 1895 1896@smallexample 1897foo (float f, float g) 1898@{ 1899 float beat_freqs[2] = @{ f-g, f+g @}; 1900 /* @r{@dots{}} */ 1901@} 1902@end smallexample 1903 1904@node Compound Literals 1905@section Compound Literals 1906@cindex constructor expressions 1907@cindex initializations in expressions 1908@cindex structures, constructor expression 1909@cindex expressions, constructor 1910@cindex compound literals 1911@c The GNU C name for what C99 calls compound literals was "constructor expressions". 1912 1913A compound literal looks like a cast of a brace-enclosed aggregate 1914initializer list. Its value is an object of the type specified in 1915the cast, containing the elements specified in the initializer. 1916Unlike the result of a cast, a compound literal is an lvalue. ISO 1917C99 and later support compound literals. As an extension, GCC 1918supports compound literals also in C90 mode and in C++, although 1919as explained below, the C++ semantics are somewhat different. 1920 1921Usually, the specified type of a compound literal is a structure. Assume 1922that @code{struct foo} and @code{structure} are declared as shown: 1923 1924@smallexample 1925struct foo @{int a; char b[2];@} structure; 1926@end smallexample 1927 1928@noindent 1929Here is an example of constructing a @code{struct foo} with a compound literal: 1930 1931@smallexample 1932structure = ((struct foo) @{x + y, 'a', 0@}); 1933@end smallexample 1934 1935@noindent 1936This is equivalent to writing the following: 1937 1938@smallexample 1939@{ 1940 struct foo temp = @{x + y, 'a', 0@}; 1941 structure = temp; 1942@} 1943@end smallexample 1944 1945You can also construct an array, though this is dangerous in C++, as 1946explained below. If all the elements of the compound literal are 1947(made up of) simple constant expressions suitable for use in 1948initializers of objects of static storage duration, then the compound 1949literal can be coerced to a pointer to its first element and used in 1950such an initializer, as shown here: 1951 1952@smallexample 1953char **foo = (char *[]) @{ "x", "y", "z" @}; 1954@end smallexample 1955 1956Compound literals for scalar types and union types are also allowed. In 1957the following example the variable @code{i} is initialized to the value 1958@code{2}, the result of incrementing the unnamed object created by 1959the compound literal. 1960 1961@smallexample 1962int i = ++(int) @{ 1 @}; 1963@end smallexample 1964 1965As a GNU extension, GCC allows initialization of objects with static storage 1966duration by compound literals (which is not possible in ISO C99 because 1967the initializer is not a constant). 1968It is handled as if the object were initialized only with the brace-enclosed 1969list if the types of the compound literal and the object match. 1970The elements of the compound literal must be constant. 1971If the object being initialized has array type of unknown size, the size is 1972determined by the size of the compound literal. 1973 1974@smallexample 1975static struct foo x = (struct foo) @{1, 'a', 'b'@}; 1976static int y[] = (int []) @{1, 2, 3@}; 1977static int z[] = (int [3]) @{1@}; 1978@end smallexample 1979 1980@noindent 1981The above lines are equivalent to the following: 1982@smallexample 1983static struct foo x = @{1, 'a', 'b'@}; 1984static int y[] = @{1, 2, 3@}; 1985static int z[] = @{1, 0, 0@}; 1986@end smallexample 1987 1988In C, a compound literal designates an unnamed object with static or 1989automatic storage duration. In C++, a compound literal designates a 1990temporary object that only lives until the end of its full-expression. 1991As a result, well-defined C code that takes the address of a subobject 1992of a compound literal can be undefined in C++, so G++ rejects 1993the conversion of a temporary array to a pointer. For instance, if 1994the array compound literal example above appeared inside a function, 1995any subsequent use of @code{foo} in C++ would have undefined behavior 1996because the lifetime of the array ends after the declaration of @code{foo}. 1997 1998As an optimization, G++ sometimes gives array compound literals longer 1999lifetimes: when the array either appears outside a function or has 2000a @code{const}-qualified type. If @code{foo} and its initializer had 2001elements of type @code{char *const} rather than @code{char *}, or if 2002@code{foo} were a global variable, the array would have static storage 2003duration. But it is probably safest just to avoid the use of array 2004compound literals in C++ code. 2005 2006@node Designated Inits 2007@section Designated Initializers 2008@cindex initializers with labeled elements 2009@cindex labeled elements in initializers 2010@cindex case labels in initializers 2011@cindex designated initializers 2012 2013Standard C90 requires the elements of an initializer to appear in a fixed 2014order, the same as the order of the elements in the array or structure 2015being initialized. 2016 2017In ISO C99 you can give the elements in any order, specifying the array 2018indices or structure field names they apply to, and GNU C allows this as 2019an extension in C90 mode as well. This extension is not 2020implemented in GNU C++. 2021 2022To specify an array index, write 2023@samp{[@var{index}] =} before the element value. For example, 2024 2025@smallexample 2026int a[6] = @{ [4] = 29, [2] = 15 @}; 2027@end smallexample 2028 2029@noindent 2030is equivalent to 2031 2032@smallexample 2033int a[6] = @{ 0, 0, 15, 0, 29, 0 @}; 2034@end smallexample 2035 2036@noindent 2037The index values must be constant expressions, even if the array being 2038initialized is automatic. 2039 2040An alternative syntax for this that has been obsolete since GCC 2.5 but 2041GCC still accepts is to write @samp{[@var{index}]} before the element 2042value, with no @samp{=}. 2043 2044To initialize a range of elements to the same value, write 2045@samp{[@var{first} ... @var{last}] = @var{value}}. This is a GNU 2046extension. For example, 2047 2048@smallexample 2049int widths[] = @{ [0 ... 9] = 1, [10 ... 99] = 2, [100] = 3 @}; 2050@end smallexample 2051 2052@noindent 2053If the value in it has side effects, the side effects happen only once, 2054not for each initialized field by the range initializer. 2055 2056@noindent 2057Note that the length of the array is the highest value specified 2058plus one. 2059 2060In a structure initializer, specify the name of a field to initialize 2061with @samp{.@var{fieldname} =} before the element value. For example, 2062given the following structure, 2063 2064@smallexample 2065struct point @{ int x, y; @}; 2066@end smallexample 2067 2068@noindent 2069the following initialization 2070 2071@smallexample 2072struct point p = @{ .y = yvalue, .x = xvalue @}; 2073@end smallexample 2074 2075@noindent 2076is equivalent to 2077 2078@smallexample 2079struct point p = @{ xvalue, yvalue @}; 2080@end smallexample 2081 2082Another syntax that has the same meaning, obsolete since GCC 2.5, is 2083@samp{@var{fieldname}:}, as shown here: 2084 2085@smallexample 2086struct point p = @{ y: yvalue, x: xvalue @}; 2087@end smallexample 2088 2089Omitted field members are implicitly initialized the same as objects 2090that have static storage duration. 2091 2092@cindex designators 2093The @samp{[@var{index}]} or @samp{.@var{fieldname}} is known as a 2094@dfn{designator}. You can also use a designator (or the obsolete colon 2095syntax) when initializing a union, to specify which element of the union 2096should be used. For example, 2097 2098@smallexample 2099union foo @{ int i; double d; @}; 2100 2101union foo f = @{ .d = 4 @}; 2102@end smallexample 2103 2104@noindent 2105converts 4 to a @code{double} to store it in the union using 2106the second element. By contrast, casting 4 to type @code{union foo} 2107stores it into the union as the integer @code{i}, since it is 2108an integer. @xref{Cast to Union}. 2109 2110You can combine this technique of naming elements with ordinary C 2111initialization of successive elements. Each initializer element that 2112does not have a designator applies to the next consecutive element of the 2113array or structure. For example, 2114 2115@smallexample 2116int a[6] = @{ [1] = v1, v2, [4] = v4 @}; 2117@end smallexample 2118 2119@noindent 2120is equivalent to 2121 2122@smallexample 2123int a[6] = @{ 0, v1, v2, 0, v4, 0 @}; 2124@end smallexample 2125 2126Labeling the elements of an array initializer is especially useful 2127when the indices are characters or belong to an @code{enum} type. 2128For example: 2129 2130@smallexample 2131int whitespace[256] 2132 = @{ [' '] = 1, ['\t'] = 1, ['\h'] = 1, 2133 ['\f'] = 1, ['\n'] = 1, ['\r'] = 1 @}; 2134@end smallexample 2135 2136@cindex designator lists 2137You can also write a series of @samp{.@var{fieldname}} and 2138@samp{[@var{index}]} designators before an @samp{=} to specify a 2139nested subobject to initialize; the list is taken relative to the 2140subobject corresponding to the closest surrounding brace pair. For 2141example, with the @samp{struct point} declaration above: 2142 2143@smallexample 2144struct point ptarray[10] = @{ [2].y = yv2, [2].x = xv2, [0].x = xv0 @}; 2145@end smallexample 2146 2147@noindent 2148If the same field is initialized multiple times, it has the value from 2149the last initialization. If any such overridden initialization has 2150side effect, it is unspecified whether the side effect happens or not. 2151Currently, GCC discards them and issues a warning. 2152 2153@node Case Ranges 2154@section Case Ranges 2155@cindex case ranges 2156@cindex ranges in case statements 2157 2158You can specify a range of consecutive values in a single @code{case} label, 2159like this: 2160 2161@smallexample 2162case @var{low} ... @var{high}: 2163@end smallexample 2164 2165@noindent 2166This has the same effect as the proper number of individual @code{case} 2167labels, one for each integer value from @var{low} to @var{high}, inclusive. 2168 2169This feature is especially useful for ranges of ASCII character codes: 2170 2171@smallexample 2172case 'A' ... 'Z': 2173@end smallexample 2174 2175@strong{Be careful:} Write spaces around the @code{...}, for otherwise 2176it may be parsed wrong when you use it with integer values. For example, 2177write this: 2178 2179@smallexample 2180case 1 ... 5: 2181@end smallexample 2182 2183@noindent 2184rather than this: 2185 2186@smallexample 2187case 1...5: 2188@end smallexample 2189 2190@node Cast to Union 2191@section Cast to a Union Type 2192@cindex cast to a union 2193@cindex union, casting to a 2194 2195A cast to union type looks similar to other casts, except that the type 2196specified is a union type. You can specify the type either with the 2197@code{union} keyword or with a @code{typedef} name that refers to 2198a union. A cast to a union actually creates a compound literal and 2199yields an lvalue, not an rvalue like true casts do. 2200@xref{Compound Literals}. 2201 2202The types that may be cast to the union type are those of the members 2203of the union. Thus, given the following union and variables: 2204 2205@smallexample 2206union foo @{ int i; double d; @}; 2207int x; 2208double y; 2209@end smallexample 2210 2211@noindent 2212both @code{x} and @code{y} can be cast to type @code{union foo}. 2213 2214Using the cast as the right-hand side of an assignment to a variable of 2215union type is equivalent to storing in a member of the union: 2216 2217@smallexample 2218union foo u; 2219/* @r{@dots{}} */ 2220u = (union foo) x @equiv{} u.i = x 2221u = (union foo) y @equiv{} u.d = y 2222@end smallexample 2223 2224You can also use the union cast as a function argument: 2225 2226@smallexample 2227void hack (union foo); 2228/* @r{@dots{}} */ 2229hack ((union foo) x); 2230@end smallexample 2231 2232@node Mixed Declarations 2233@section Mixed Declarations and Code 2234@cindex mixed declarations and code 2235@cindex declarations, mixed with code 2236@cindex code, mixed with declarations 2237 2238ISO C99 and ISO C++ allow declarations and code to be freely mixed 2239within compound statements. As an extension, GNU C also allows this in 2240C90 mode. For example, you could do: 2241 2242@smallexample 2243int i; 2244/* @r{@dots{}} */ 2245i++; 2246int j = i + 2; 2247@end smallexample 2248 2249Each identifier is visible from where it is declared until the end of 2250the enclosing block. 2251 2252@node Function Attributes 2253@section Declaring Attributes of Functions 2254@cindex function attributes 2255@cindex declaring attributes of functions 2256@cindex @code{volatile} applied to function 2257@cindex @code{const} applied to function 2258 2259In GNU C, you can use function attributes to declare certain things 2260about functions called in your program which help the compiler 2261optimize calls and check your code more carefully. For example, you 2262can use attributes to declare that a function never returns 2263(@code{noreturn}), returns a value depending only on its arguments 2264(@code{pure}), or has @code{printf}-style arguments (@code{format}). 2265 2266You can also use attributes to control memory placement, code 2267generation options or call/return conventions within the function 2268being annotated. Many of these attributes are target-specific. For 2269example, many targets support attributes for defining interrupt 2270handler functions, which typically must follow special register usage 2271and return conventions. 2272 2273Function attributes are introduced by the @code{__attribute__} keyword 2274on a declaration, followed by an attribute specification inside double 2275parentheses. You can specify multiple attributes in a declaration by 2276separating them by commas within the double parentheses or by 2277immediately following an attribute declaration with another attribute 2278declaration. @xref{Attribute Syntax}, for the exact rules on attribute 2279syntax and placement. Compatible attribute specifications on distinct 2280declarations of the same function are merged. An attribute specification 2281that is not compatible with attributes already applied to a declaration 2282of the same function is ignored with a warning. 2283 2284GCC also supports attributes on 2285variable declarations (@pxref{Variable Attributes}), 2286labels (@pxref{Label Attributes}), 2287enumerators (@pxref{Enumerator Attributes}), 2288statements (@pxref{Statement Attributes}), 2289and types (@pxref{Type Attributes}). 2290 2291There is some overlap between the purposes of attributes and pragmas 2292(@pxref{Pragmas,,Pragmas Accepted by GCC}). It has been 2293found convenient to use @code{__attribute__} to achieve a natural 2294attachment of attributes to their corresponding declarations, whereas 2295@code{#pragma} is of use for compatibility with other compilers 2296or constructs that do not naturally form part of the grammar. 2297 2298In addition to the attributes documented here, 2299GCC plugins may provide their own attributes. 2300 2301@menu 2302* Common Function Attributes:: 2303* AArch64 Function Attributes:: 2304* ARC Function Attributes:: 2305* ARM Function Attributes:: 2306* AVR Function Attributes:: 2307* Blackfin Function Attributes:: 2308* CR16 Function Attributes:: 2309* Epiphany Function Attributes:: 2310* H8/300 Function Attributes:: 2311* IA-64 Function Attributes:: 2312* M32C Function Attributes:: 2313* M32R/D Function Attributes:: 2314* m68k Function Attributes:: 2315* MCORE Function Attributes:: 2316* MeP Function Attributes:: 2317* MicroBlaze Function Attributes:: 2318* Microsoft Windows Function Attributes:: 2319* MIPS Function Attributes:: 2320* MSP430 Function Attributes:: 2321* NDS32 Function Attributes:: 2322* Nios II Function Attributes:: 2323* Nvidia PTX Function Attributes:: 2324* PowerPC Function Attributes:: 2325* RISC-V Function Attributes:: 2326* RL78 Function Attributes:: 2327* RX Function Attributes:: 2328* S/390 Function Attributes:: 2329* SH Function Attributes:: 2330* SPU Function Attributes:: 2331* Symbian OS Function Attributes:: 2332* V850 Function Attributes:: 2333* Visium Function Attributes:: 2334* x86 Function Attributes:: 2335* Xstormy16 Function Attributes:: 2336@end menu 2337 2338@node Common Function Attributes 2339@subsection Common Function Attributes 2340 2341The following attributes are supported on most targets. 2342 2343@table @code 2344@c Keep this table alphabetized by attribute name. Treat _ as space. 2345 2346@item alias ("@var{target}") 2347@cindex @code{alias} function attribute 2348The @code{alias} attribute causes the declaration to be emitted as an 2349alias for another symbol, which must be specified. For instance, 2350 2351@smallexample 2352void __f () @{ /* @r{Do something.} */; @} 2353void f () __attribute__ ((weak, alias ("__f"))); 2354@end smallexample 2355 2356@noindent 2357defines @samp{f} to be a weak alias for @samp{__f}. In C++, the 2358mangled name for the target must be used. It is an error if @samp{__f} 2359is not defined in the same translation unit. 2360 2361This attribute requires assembler and object file support, 2362and may not be available on all targets. 2363 2364@item aligned (@var{alignment}) 2365@cindex @code{aligned} function attribute 2366This attribute specifies a minimum alignment for the function, 2367measured in bytes. 2368 2369You cannot use this attribute to decrease the alignment of a function, 2370only to increase it. However, when you explicitly specify a function 2371alignment this overrides the effect of the 2372@option{-falign-functions} (@pxref{Optimize Options}) option for this 2373function. 2374 2375Note that the effectiveness of @code{aligned} attributes may be 2376limited by inherent limitations in your linker. On many systems, the 2377linker is only able to arrange for functions to be aligned up to a 2378certain maximum alignment. (For some linkers, the maximum supported 2379alignment may be very very small.) See your linker documentation for 2380further information. 2381 2382The @code{aligned} attribute can also be used for variables and fields 2383(@pxref{Variable Attributes}.) 2384 2385@item alloc_align 2386@cindex @code{alloc_align} function attribute 2387The @code{alloc_align} attribute is used to tell the compiler that the 2388function return value points to memory, where the returned pointer minimum 2389alignment is given by one of the functions parameters. GCC uses this 2390information to improve pointer alignment analysis. 2391 2392The function parameter denoting the allocated alignment is specified by 2393one integer argument, whose number is the argument of the attribute. 2394Argument numbering starts at one. 2395 2396For instance, 2397 2398@smallexample 2399void* my_memalign(size_t, size_t) __attribute__((alloc_align(1))) 2400@end smallexample 2401 2402@noindent 2403declares that @code{my_memalign} returns memory with minimum alignment 2404given by parameter 1. 2405 2406@item alloc_size 2407@cindex @code{alloc_size} function attribute 2408The @code{alloc_size} attribute is used to tell the compiler that the 2409function return value points to memory, where the size is given by 2410one or two of the functions parameters. GCC uses this 2411information to improve the correctness of @code{__builtin_object_size}. 2412 2413The function parameter(s) denoting the allocated size are specified by 2414one or two integer arguments supplied to the attribute. The allocated size 2415is either the value of the single function argument specified or the product 2416of the two function arguments specified. Argument numbering starts at 2417one. 2418 2419For instance, 2420 2421@smallexample 2422void* my_calloc(size_t, size_t) __attribute__((alloc_size(1,2))) 2423void* my_realloc(void*, size_t) __attribute__((alloc_size(2))) 2424@end smallexample 2425 2426@noindent 2427declares that @code{my_calloc} returns memory of the size given by 2428the product of parameter 1 and 2 and that @code{my_realloc} returns memory 2429of the size given by parameter 2. 2430 2431@item always_inline 2432@cindex @code{always_inline} function attribute 2433Generally, functions are not inlined unless optimization is specified. 2434For functions declared inline, this attribute inlines the function 2435independent of any restrictions that otherwise apply to inlining. 2436Failure to inline such a function is diagnosed as an error. 2437Note that if such a function is called indirectly the compiler may 2438or may not inline it depending on optimization level and a failure 2439to inline an indirect call may or may not be diagnosed. 2440 2441@item artificial 2442@cindex @code{artificial} function attribute 2443This attribute is useful for small inline wrappers that if possible 2444should appear during debugging as a unit. Depending on the debug 2445info format it either means marking the function as artificial 2446or using the caller location for all instructions within the inlined 2447body. 2448 2449@item assume_aligned 2450@cindex @code{assume_aligned} function attribute 2451The @code{assume_aligned} attribute is used to tell the compiler that the 2452function return value points to memory, where the returned pointer minimum 2453alignment is given by the first argument. 2454If the attribute has two arguments, the second argument is misalignment offset. 2455 2456For instance 2457 2458@smallexample 2459void* my_alloc1(size_t) __attribute__((assume_aligned(16))) 2460void* my_alloc2(size_t) __attribute__((assume_aligned(32, 8))) 2461@end smallexample 2462 2463@noindent 2464declares that @code{my_alloc1} returns 16-byte aligned pointer and 2465that @code{my_alloc2} returns a pointer whose value modulo 32 is equal 2466to 8. 2467 2468@item bnd_instrument 2469@cindex @code{bnd_instrument} function attribute 2470The @code{bnd_instrument} attribute on functions is used to inform the 2471compiler that the function should be instrumented when compiled 2472with the @option{-fchkp-instrument-marked-only} option. 2473 2474@item bnd_legacy 2475@cindex @code{bnd_legacy} function attribute 2476@cindex Pointer Bounds Checker attributes 2477The @code{bnd_legacy} attribute on functions is used to inform the 2478compiler that the function should not be instrumented when compiled 2479with the @option{-fcheck-pointer-bounds} option. 2480 2481@item cold 2482@cindex @code{cold} function attribute 2483The @code{cold} attribute on functions is used to inform the compiler that 2484the function is unlikely to be executed. The function is optimized for 2485size rather than speed and on many targets it is placed into a special 2486subsection of the text section so all cold functions appear close together, 2487improving code locality of non-cold parts of program. The paths leading 2488to calls of cold functions within code are marked as unlikely by the branch 2489prediction mechanism. It is thus useful to mark functions used to handle 2490unlikely conditions, such as @code{perror}, as cold to improve optimization 2491of hot functions that do call marked functions in rare occasions. 2492 2493When profile feedback is available, via @option{-fprofile-use}, cold functions 2494are automatically detected and this attribute is ignored. 2495 2496@item const 2497@cindex @code{const} function attribute 2498@cindex functions that have no side effects 2499Many functions do not examine any values except their arguments, and 2500have no effects except to return a value. Calls to such functions lend 2501themselves to optimization such as common subexpression elimination. 2502The @code{const} attribute imposes greater restrictions on a function's 2503definition than the similar @code{pure} attribute below because it prohibits 2504the function from reading global variables. Consequently, the presence of 2505the attribute on a function declaration allows GCC to emit more efficient 2506code for some calls to the function. Decorating the same function with 2507both the @code{const} and the @code{pure} attribute is diagnosed. 2508 2509@cindex pointer arguments 2510Note that a function that has pointer arguments and examines the data 2511pointed to must @emph{not} be declared @code{const}. Likewise, a 2512function that calls a non-@code{const} function usually must not be 2513@code{const}. Because a @code{const} function cannot have any side 2514effects it does not make sense for such a function to return @code{void}. 2515Declaring such a function is diagnosed. 2516 2517@item constructor 2518@itemx destructor 2519@itemx constructor (@var{priority}) 2520@itemx destructor (@var{priority}) 2521@cindex @code{constructor} function attribute 2522@cindex @code{destructor} function attribute 2523The @code{constructor} attribute causes the function to be called 2524automatically before execution enters @code{main ()}. Similarly, the 2525@code{destructor} attribute causes the function to be called 2526automatically after @code{main ()} completes or @code{exit ()} is 2527called. Functions with these attributes are useful for 2528initializing data that is used implicitly during the execution of 2529the program. 2530 2531You may provide an optional integer priority to control the order in 2532which constructor and destructor functions are run. A constructor 2533with a smaller priority number runs before a constructor with a larger 2534priority number; the opposite relationship holds for destructors. So, 2535if you have a constructor that allocates a resource and a destructor 2536that deallocates the same resource, both functions typically have the 2537same priority. The priorities for constructor and destructor 2538functions are the same as those specified for namespace-scope C++ 2539objects (@pxref{C++ Attributes}). However, at present, the order in which 2540constructors for C++ objects with static storage duration and functions 2541decorated with attribute @code{constructor} are invoked is unspecified. 2542In mixed declarations, attribute @code{init_priority} can be used to 2543impose a specific ordering. 2544 2545@item deprecated 2546@itemx deprecated (@var{msg}) 2547@cindex @code{deprecated} function attribute 2548The @code{deprecated} attribute results in a warning if the function 2549is used anywhere in the source file. This is useful when identifying 2550functions that are expected to be removed in a future version of a 2551program. The warning also includes the location of the declaration 2552of the deprecated function, to enable users to easily find further 2553information about why the function is deprecated, or what they should 2554do instead. Note that the warnings only occurs for uses: 2555 2556@smallexample 2557int old_fn () __attribute__ ((deprecated)); 2558int old_fn (); 2559int (*fn_ptr)() = old_fn; 2560@end smallexample 2561 2562@noindent 2563results in a warning on line 3 but not line 2. The optional @var{msg} 2564argument, which must be a string, is printed in the warning if 2565present. 2566 2567The @code{deprecated} attribute can also be used for variables and 2568types (@pxref{Variable Attributes}, @pxref{Type Attributes}.) 2569 2570@item error ("@var{message}") 2571@itemx warning ("@var{message}") 2572@cindex @code{error} function attribute 2573@cindex @code{warning} function attribute 2574If the @code{error} or @code{warning} attribute 2575is used on a function declaration and a call to such a function 2576is not eliminated through dead code elimination or other optimizations, 2577an error or warning (respectively) that includes @var{message} is diagnosed. 2578This is useful 2579for compile-time checking, especially together with @code{__builtin_constant_p} 2580and inline functions where checking the inline function arguments is not 2581possible through @code{extern char [(condition) ? 1 : -1];} tricks. 2582 2583While it is possible to leave the function undefined and thus invoke 2584a link failure (to define the function with 2585a message in @code{.gnu.warning*} section), 2586when using these attributes the problem is diagnosed 2587earlier and with exact location of the call even in presence of inline 2588functions or when not emitting debugging information. 2589 2590@item externally_visible 2591@cindex @code{externally_visible} function attribute 2592This attribute, attached to a global variable or function, nullifies 2593the effect of the @option{-fwhole-program} command-line option, so the 2594object remains visible outside the current compilation unit. 2595 2596If @option{-fwhole-program} is used together with @option{-flto} and 2597@command{gold} is used as the linker plugin, 2598@code{externally_visible} attributes are automatically added to functions 2599(not variable yet due to a current @command{gold} issue) 2600that are accessed outside of LTO objects according to resolution file 2601produced by @command{gold}. 2602For other linkers that cannot generate resolution file, 2603explicit @code{externally_visible} attributes are still necessary. 2604 2605@item flatten 2606@cindex @code{flatten} function attribute 2607Generally, inlining into a function is limited. For a function marked with 2608this attribute, every call inside this function is inlined, if possible. 2609Whether the function itself is considered for inlining depends on its size and 2610the current inlining parameters. 2611 2612@item format (@var{archetype}, @var{string-index}, @var{first-to-check}) 2613@cindex @code{format} function attribute 2614@cindex functions with @code{printf}, @code{scanf}, @code{strftime} or @code{strfmon} style arguments 2615@opindex Wformat 2616The @code{format} attribute specifies that a function takes @code{printf}, 2617@code{scanf}, @code{strftime} or @code{strfmon} style arguments that 2618should be type-checked against a format string. For example, the 2619declaration: 2620 2621@smallexample 2622extern int 2623my_printf (void *my_object, const char *my_format, ...) 2624 __attribute__ ((format (printf, 2, 3))); 2625@end smallexample 2626 2627@noindent 2628causes the compiler to check the arguments in calls to @code{my_printf} 2629for consistency with the @code{printf} style format string argument 2630@code{my_format}. 2631 2632The parameter @var{archetype} determines how the format string is 2633interpreted, and should be @code{printf}, @code{scanf}, @code{strftime}, 2634@code{gnu_printf}, @code{gnu_scanf}, @code{gnu_strftime} or 2635@code{strfmon}. (You can also use @code{__printf__}, 2636@code{__scanf__}, @code{__strftime__} or @code{__strfmon__}.) On 2637MinGW targets, @code{ms_printf}, @code{ms_scanf}, and 2638@code{ms_strftime} are also present. 2639@var{archetype} values such as @code{printf} refer to the formats accepted 2640by the system's C runtime library, 2641while values prefixed with @samp{gnu_} always refer 2642to the formats accepted by the GNU C Library. On Microsoft Windows 2643targets, values prefixed with @samp{ms_} refer to the formats accepted by the 2644@file{msvcrt.dll} library. 2645The parameter @var{string-index} 2646specifies which argument is the format string argument (starting 2647from 1), while @var{first-to-check} is the number of the first 2648argument to check against the format string. For functions 2649where the arguments are not available to be checked (such as 2650@code{vprintf}), specify the third parameter as zero. In this case the 2651compiler only checks the format string for consistency. For 2652@code{strftime} formats, the third parameter is required to be zero. 2653Since non-static C++ methods have an implicit @code{this} argument, the 2654arguments of such methods should be counted from two, not one, when 2655giving values for @var{string-index} and @var{first-to-check}. 2656 2657In the example above, the format string (@code{my_format}) is the second 2658argument of the function @code{my_print}, and the arguments to check 2659start with the third argument, so the correct parameters for the format 2660attribute are 2 and 3. 2661 2662@opindex ffreestanding 2663@opindex fno-builtin 2664The @code{format} attribute allows you to identify your own functions 2665that take format strings as arguments, so that GCC can check the 2666calls to these functions for errors. The compiler always (unless 2667@option{-ffreestanding} or @option{-fno-builtin} is used) checks formats 2668for the standard library functions @code{printf}, @code{fprintf}, 2669@code{sprintf}, @code{scanf}, @code{fscanf}, @code{sscanf}, @code{strftime}, 2670@code{vprintf}, @code{vfprintf} and @code{vsprintf} whenever such 2671warnings are requested (using @option{-Wformat}), so there is no need to 2672modify the header file @file{stdio.h}. In C99 mode, the functions 2673@code{snprintf}, @code{vsnprintf}, @code{vscanf}, @code{vfscanf} and 2674@code{vsscanf} are also checked. Except in strictly conforming C 2675standard modes, the X/Open function @code{strfmon} is also checked as 2676are @code{printf_unlocked} and @code{fprintf_unlocked}. 2677@xref{C Dialect Options,,Options Controlling C Dialect}. 2678 2679For Objective-C dialects, @code{NSString} (or @code{__NSString__}) is 2680recognized in the same context. Declarations including these format attributes 2681are parsed for correct syntax, however the result of checking of such format 2682strings is not yet defined, and is not carried out by this version of the 2683compiler. 2684 2685The target may also provide additional types of format checks. 2686@xref{Target Format Checks,,Format Checks Specific to Particular 2687Target Machines}. 2688 2689@item format_arg (@var{string-index}) 2690@cindex @code{format_arg} function attribute 2691@opindex Wformat-nonliteral 2692The @code{format_arg} attribute specifies that a function takes a format 2693string for a @code{printf}, @code{scanf}, @code{strftime} or 2694@code{strfmon} style function and modifies it (for example, to translate 2695it into another language), so the result can be passed to a 2696@code{printf}, @code{scanf}, @code{strftime} or @code{strfmon} style 2697function (with the remaining arguments to the format function the same 2698as they would have been for the unmodified string). For example, the 2699declaration: 2700 2701@smallexample 2702extern char * 2703my_dgettext (char *my_domain, const char *my_format) 2704 __attribute__ ((format_arg (2))); 2705@end smallexample 2706 2707@noindent 2708causes the compiler to check the arguments in calls to a @code{printf}, 2709@code{scanf}, @code{strftime} or @code{strfmon} type function, whose 2710format string argument is a call to the @code{my_dgettext} function, for 2711consistency with the format string argument @code{my_format}. If the 2712@code{format_arg} attribute had not been specified, all the compiler 2713could tell in such calls to format functions would be that the format 2714string argument is not constant; this would generate a warning when 2715@option{-Wformat-nonliteral} is used, but the calls could not be checked 2716without the attribute. 2717 2718The parameter @var{string-index} specifies which argument is the format 2719string argument (starting from one). Since non-static C++ methods have 2720an implicit @code{this} argument, the arguments of such methods should 2721be counted from two. 2722 2723The @code{format_arg} attribute allows you to identify your own 2724functions that modify format strings, so that GCC can check the 2725calls to @code{printf}, @code{scanf}, @code{strftime} or @code{strfmon} 2726type function whose operands are a call to one of your own function. 2727The compiler always treats @code{gettext}, @code{dgettext}, and 2728@code{dcgettext} in this manner except when strict ISO C support is 2729requested by @option{-ansi} or an appropriate @option{-std} option, or 2730@option{-ffreestanding} or @option{-fno-builtin} 2731is used. @xref{C Dialect Options,,Options 2732Controlling C Dialect}. 2733 2734For Objective-C dialects, the @code{format-arg} attribute may refer to an 2735@code{NSString} reference for compatibility with the @code{format} attribute 2736above. 2737 2738The target may also allow additional types in @code{format-arg} attributes. 2739@xref{Target Format Checks,,Format Checks Specific to Particular 2740Target Machines}. 2741 2742@item gnu_inline 2743@cindex @code{gnu_inline} function attribute 2744This attribute should be used with a function that is also declared 2745with the @code{inline} keyword. It directs GCC to treat the function 2746as if it were defined in gnu90 mode even when compiling in C99 or 2747gnu99 mode. 2748 2749If the function is declared @code{extern}, then this definition of the 2750function is used only for inlining. In no case is the function 2751compiled as a standalone function, not even if you take its address 2752explicitly. Such an address becomes an external reference, as if you 2753had only declared the function, and had not defined it. This has 2754almost the effect of a macro. The way to use this is to put a 2755function definition in a header file with this attribute, and put 2756another copy of the function, without @code{extern}, in a library 2757file. The definition in the header file causes most calls to the 2758function to be inlined. If any uses of the function remain, they 2759refer to the single copy in the library. Note that the two 2760definitions of the functions need not be precisely the same, although 2761if they do not have the same effect your program may behave oddly. 2762 2763In C, if the function is neither @code{extern} nor @code{static}, then 2764the function is compiled as a standalone function, as well as being 2765inlined where possible. 2766 2767This is how GCC traditionally handled functions declared 2768@code{inline}. Since ISO C99 specifies a different semantics for 2769@code{inline}, this function attribute is provided as a transition 2770measure and as a useful feature in its own right. This attribute is 2771available in GCC 4.1.3 and later. It is available if either of the 2772preprocessor macros @code{__GNUC_GNU_INLINE__} or 2773@code{__GNUC_STDC_INLINE__} are defined. @xref{Inline,,An Inline 2774Function is As Fast As a Macro}. 2775 2776In C++, this attribute does not depend on @code{extern} in any way, 2777but it still requires the @code{inline} keyword to enable its special 2778behavior. 2779 2780@item hot 2781@cindex @code{hot} function attribute 2782The @code{hot} attribute on a function is used to inform the compiler that 2783the function is a hot spot of the compiled program. The function is 2784optimized more aggressively and on many targets it is placed into a special 2785subsection of the text section so all hot functions appear close together, 2786improving locality. 2787 2788When profile feedback is available, via @option{-fprofile-use}, hot functions 2789are automatically detected and this attribute is ignored. 2790 2791@item ifunc ("@var{resolver}") 2792@cindex @code{ifunc} function attribute 2793@cindex indirect functions 2794@cindex functions that are dynamically resolved 2795The @code{ifunc} attribute is used to mark a function as an indirect 2796function using the STT_GNU_IFUNC symbol type extension to the ELF 2797standard. This allows the resolution of the symbol value to be 2798determined dynamically at load time, and an optimized version of the 2799routine to be selected for the particular processor or other system 2800characteristics determined then. To use this attribute, first define 2801the implementation functions available, and a resolver function that 2802returns a pointer to the selected implementation function. The 2803implementation functions' declarations must match the API of the 2804function being implemented. The resolver should be declared to 2805be a function taking no arguments and returning a pointer to 2806a function of the same type as the implementation. For example: 2807 2808@smallexample 2809void *my_memcpy (void *dst, const void *src, size_t len) 2810@{ 2811 @dots{} 2812 return dst; 2813@} 2814 2815static void * (*resolve_memcpy (void))(void *, const void *, size_t) 2816@{ 2817 return my_memcpy; // we will just always select this routine 2818@} 2819@end smallexample 2820 2821@noindent 2822The exported header file declaring the function the user calls would 2823contain: 2824 2825@smallexample 2826extern void *memcpy (void *, const void *, size_t); 2827@end smallexample 2828 2829@noindent 2830allowing the user to call @code{memcpy} as a regular function, unaware of 2831the actual implementation. Finally, the indirect function needs to be 2832defined in the same translation unit as the resolver function: 2833 2834@smallexample 2835void *memcpy (void *, const void *, size_t) 2836 __attribute__ ((ifunc ("resolve_memcpy"))); 2837@end smallexample 2838 2839In C++, the @code{ifunc} attribute takes a string that is the mangled name 2840of the resolver function. A C++ resolver for a non-static member function 2841of class @code{C} should be declared to return a pointer to a non-member 2842function taking pointer to @code{C} as the first argument, followed by 2843the same arguments as of the implementation function. G++ checks 2844the signatures of the two functions and issues 2845a @option{-Wattribute-alias} warning for mismatches. To suppress a warning 2846for the necessary cast from a pointer to the implementation member function 2847to the type of the corresponding non-member function use 2848the @option{-Wno-pmf-conversions} option. For example: 2849 2850@smallexample 2851class S 2852@{ 2853private: 2854 int debug_impl (int); 2855 int optimized_impl (int); 2856 2857 typedef int Func (S*, int); 2858 2859 static Func* resolver (); 2860public: 2861 2862 int interface (int); 2863@}; 2864 2865int S::debug_impl (int) @{ /* @r{@dots{}} */ @} 2866int S::optimized_impl (int) @{ /* @r{@dots{}} */ @} 2867 2868S::Func* S::resolver () 2869@{ 2870 int (S::*pimpl) (int) 2871 = getenv ("DEBUG") ? &S::debug_impl : &S::optimized_impl; 2872 2873 // Cast triggers -Wno-pmf-conversions. 2874 return reinterpret_cast<Func*>(pimpl); 2875@} 2876 2877int S::interface (int) __attribute__ ((ifunc ("_ZN1S8resolverEv"))); 2878@end smallexample 2879 2880Indirect functions cannot be weak. Binutils version 2.20.1 or higher 2881and GNU C Library version 2.11.1 are required to use this feature. 2882 2883@item interrupt 2884@itemx interrupt_handler 2885Many GCC back ends support attributes to indicate that a function is 2886an interrupt handler, which tells the compiler to generate function 2887entry and exit sequences that differ from those from regular 2888functions. The exact syntax and behavior are target-specific; 2889refer to the following subsections for details. 2890 2891@item leaf 2892@cindex @code{leaf} function attribute 2893Calls to external functions with this attribute must return to the 2894current compilation unit only by return or by exception handling. In 2895particular, a leaf function is not allowed to invoke callback functions 2896passed to it from the current compilation unit, directly call functions 2897exported by the unit, or @code{longjmp} into the unit. Leaf functions 2898might still call functions from other compilation units and thus they 2899are not necessarily leaf in the sense that they contain no function 2900calls at all. 2901 2902The attribute is intended for library functions to improve dataflow 2903analysis. The compiler takes the hint that any data not escaping the 2904current compilation unit cannot be used or modified by the leaf 2905function. For example, the @code{sin} function is a leaf function, but 2906@code{qsort} is not. 2907 2908Note that leaf functions might indirectly run a signal handler defined 2909in the current compilation unit that uses static variables. Similarly, 2910when lazy symbol resolution is in effect, leaf functions might invoke 2911indirect functions whose resolver function or implementation function is 2912defined in the current compilation unit and uses static variables. There 2913is no standard-compliant way to write such a signal handler, resolver 2914function, or implementation function, and the best that you can do is to 2915remove the @code{leaf} attribute or mark all such static variables 2916@code{volatile}. Lastly, for ELF-based systems that support symbol 2917interposition, care should be taken that functions defined in the 2918current compilation unit do not unexpectedly interpose other symbols 2919based on the defined standards mode and defined feature test macros; 2920otherwise an inadvertent callback would be added. 2921 2922The attribute has no effect on functions defined within the current 2923compilation unit. This is to allow easy merging of multiple compilation 2924units into one, for example, by using the link-time optimization. For 2925this reason the attribute is not allowed on types to annotate indirect 2926calls. 2927 2928@item malloc 2929@cindex @code{malloc} function attribute 2930@cindex functions that behave like malloc 2931This tells the compiler that a function is @code{malloc}-like, i.e., 2932that the pointer @var{P} returned by the function cannot alias any 2933other pointer valid when the function returns, and moreover no 2934pointers to valid objects occur in any storage addressed by @var{P}. 2935 2936Using this attribute can improve optimization. Functions like 2937@code{malloc} and @code{calloc} have this property because they return 2938a pointer to uninitialized or zeroed-out storage. However, functions 2939like @code{realloc} do not have this property, as they can return a 2940pointer to storage containing pointers. 2941 2942@item no_icf 2943@cindex @code{no_icf} function attribute 2944This function attribute prevents a functions from being merged with another 2945semantically equivalent function. 2946 2947@item no_instrument_function 2948@cindex @code{no_instrument_function} function attribute 2949@opindex finstrument-functions 2950If @option{-finstrument-functions} is given, profiling function calls are 2951generated at entry and exit of most user-compiled functions. 2952Functions with this attribute are not so instrumented. 2953 2954@item no_profile_instrument_function 2955@cindex @code{no_profile_instrument_function} function attribute 2956The @code{no_profile_instrument_function} attribute on functions is used 2957to inform the compiler that it should not process any profile feedback based 2958optimization code instrumentation. 2959 2960@item no_reorder 2961@cindex @code{no_reorder} function attribute 2962Do not reorder functions or variables marked @code{no_reorder} 2963against each other or top level assembler statements the executable. 2964The actual order in the program will depend on the linker command 2965line. Static variables marked like this are also not removed. 2966This has a similar effect 2967as the @option{-fno-toplevel-reorder} option, but only applies to the 2968marked symbols. 2969 2970@item no_sanitize ("@var{sanitize_option}") 2971@cindex @code{no_sanitize} function attribute 2972The @code{no_sanitize} attribute on functions is used 2973to inform the compiler that it should not do sanitization of all options 2974mentioned in @var{sanitize_option}. A list of values acceptable by 2975@option{-fsanitize} option can be provided. 2976 2977@smallexample 2978void __attribute__ ((no_sanitize ("alignment", "object-size"))) 2979f () @{ /* @r{Do something.} */; @} 2980void __attribute__ ((no_sanitize ("alignment,object-size"))) 2981g () @{ /* @r{Do something.} */; @} 2982@end smallexample 2983 2984@item no_sanitize_address 2985@itemx no_address_safety_analysis 2986@cindex @code{no_sanitize_address} function attribute 2987The @code{no_sanitize_address} attribute on functions is used 2988to inform the compiler that it should not instrument memory accesses 2989in the function when compiling with the @option{-fsanitize=address} option. 2990The @code{no_address_safety_analysis} is a deprecated alias of the 2991@code{no_sanitize_address} attribute, new code should use 2992@code{no_sanitize_address}. 2993 2994@item no_sanitize_thread 2995@cindex @code{no_sanitize_thread} function attribute 2996The @code{no_sanitize_thread} attribute on functions is used 2997to inform the compiler that it should not instrument memory accesses 2998in the function when compiling with the @option{-fsanitize=thread} option. 2999 3000@item no_sanitize_undefined 3001@cindex @code{no_sanitize_undefined} function attribute 3002The @code{no_sanitize_undefined} attribute on functions is used 3003to inform the compiler that it should not check for undefined behavior 3004in the function when compiling with the @option{-fsanitize=undefined} option. 3005 3006@item no_split_stack 3007@cindex @code{no_split_stack} function attribute 3008@opindex fsplit-stack 3009If @option{-fsplit-stack} is given, functions have a small 3010prologue which decides whether to split the stack. Functions with the 3011@code{no_split_stack} attribute do not have that prologue, and thus 3012may run with only a small amount of stack space available. 3013 3014@item no_stack_limit 3015@cindex @code{no_stack_limit} function attribute 3016This attribute locally overrides the @option{-fstack-limit-register} 3017and @option{-fstack-limit-symbol} command-line options; it has the effect 3018of disabling stack limit checking in the function it applies to. 3019 3020@item noclone 3021@cindex @code{noclone} function attribute 3022This function attribute prevents a function from being considered for 3023cloning---a mechanism that produces specialized copies of functions 3024and which is (currently) performed by interprocedural constant 3025propagation. 3026 3027@item noinline 3028@cindex @code{noinline} function attribute 3029This function attribute prevents a function from being considered for 3030inlining. 3031@c Don't enumerate the optimizations by name here; we try to be 3032@c future-compatible with this mechanism. 3033If the function does not have side effects, there are optimizations 3034other than inlining that cause function calls to be optimized away, 3035although the function call is live. To keep such calls from being 3036optimized away, put 3037@smallexample 3038asm (""); 3039@end smallexample 3040 3041@noindent 3042(@pxref{Extended Asm}) in the called function, to serve as a special 3043side effect. 3044 3045@item noipa 3046@cindex @code{noipa} function attribute 3047Disable interprocedural optimizations between the function with this 3048attribute and its callers, as if the body of the function is not available 3049when optimizing callers and the callers are unavailable when optimizing 3050the body. This attribute implies @code{noinline}, @code{noclone} and 3051@code{no_icf} attributes. However, this attribute is not equivalent 3052to a combination of other attributes, because its purpose is to suppress 3053existing and future optimizations employing interprocedural analysis, 3054including those that do not have an attribute suitable for disabling 3055them individually. This attribute is supported mainly for the purpose 3056of testing the compiler. 3057 3058@item nonnull (@var{arg-index}, @dots{}) 3059@cindex @code{nonnull} function attribute 3060@cindex functions with non-null pointer arguments 3061The @code{nonnull} attribute specifies that some function parameters should 3062be non-null pointers. For instance, the declaration: 3063 3064@smallexample 3065extern void * 3066my_memcpy (void *dest, const void *src, size_t len) 3067 __attribute__((nonnull (1, 2))); 3068@end smallexample 3069 3070@noindent 3071causes the compiler to check that, in calls to @code{my_memcpy}, 3072arguments @var{dest} and @var{src} are non-null. If the compiler 3073determines that a null pointer is passed in an argument slot marked 3074as non-null, and the @option{-Wnonnull} option is enabled, a warning 3075is issued. The compiler may also choose to make optimizations based 3076on the knowledge that certain function arguments will never be null. 3077 3078If no argument index list is given to the @code{nonnull} attribute, 3079all pointer arguments are marked as non-null. To illustrate, the 3080following declaration is equivalent to the previous example: 3081 3082@smallexample 3083extern void * 3084my_memcpy (void *dest, const void *src, size_t len) 3085 __attribute__((nonnull)); 3086@end smallexample 3087 3088@item noplt 3089@cindex @code{noplt} function attribute 3090The @code{noplt} attribute is the counterpart to option @option{-fno-plt}. 3091Calls to functions marked with this attribute in position-independent code 3092do not use the PLT. 3093 3094@smallexample 3095@group 3096/* Externally defined function foo. */ 3097int foo () __attribute__ ((noplt)); 3098 3099int 3100main (/* @r{@dots{}} */) 3101@{ 3102 /* @r{@dots{}} */ 3103 foo (); 3104 /* @r{@dots{}} */ 3105@} 3106@end group 3107@end smallexample 3108 3109The @code{noplt} attribute on function @code{foo} 3110tells the compiler to assume that 3111the function @code{foo} is externally defined and that the call to 3112@code{foo} must avoid the PLT 3113in position-independent code. 3114 3115In position-dependent code, a few targets also convert calls to 3116functions that are marked to not use the PLT to use the GOT instead. 3117 3118@item noreturn 3119@cindex @code{noreturn} function attribute 3120@cindex functions that never return 3121A few standard library functions, such as @code{abort} and @code{exit}, 3122cannot return. GCC knows this automatically. Some programs define 3123their own functions that never return. You can declare them 3124@code{noreturn} to tell the compiler this fact. For example, 3125 3126@smallexample 3127@group 3128void fatal () __attribute__ ((noreturn)); 3129 3130void 3131fatal (/* @r{@dots{}} */) 3132@{ 3133 /* @r{@dots{}} */ /* @r{Print error message.} */ /* @r{@dots{}} */ 3134 exit (1); 3135@} 3136@end group 3137@end smallexample 3138 3139The @code{noreturn} keyword tells the compiler to assume that 3140@code{fatal} cannot return. It can then optimize without regard to what 3141would happen if @code{fatal} ever did return. This makes slightly 3142better code. More importantly, it helps avoid spurious warnings of 3143uninitialized variables. 3144 3145The @code{noreturn} keyword does not affect the exceptional path when that 3146applies: a @code{noreturn}-marked function may still return to the caller 3147by throwing an exception or calling @code{longjmp}. 3148 3149Do not assume that registers saved by the calling function are 3150restored before calling the @code{noreturn} function. 3151 3152It does not make sense for a @code{noreturn} function to have a return 3153type other than @code{void}. 3154 3155@item nothrow 3156@cindex @code{nothrow} function attribute 3157The @code{nothrow} attribute is used to inform the compiler that a 3158function cannot throw an exception. For example, most functions in 3159the standard C library can be guaranteed not to throw an exception 3160with the notable exceptions of @code{qsort} and @code{bsearch} that 3161take function pointer arguments. 3162 3163@item optimize 3164@cindex @code{optimize} function attribute 3165The @code{optimize} attribute is used to specify that a function is to 3166be compiled with different optimization options than specified on the 3167command line. Arguments can either be numbers or strings. Numbers 3168are assumed to be an optimization level. Strings that begin with 3169@code{O} are assumed to be an optimization option, while other options 3170are assumed to be used with a @code{-f} prefix. You can also use the 3171@samp{#pragma GCC optimize} pragma to set the optimization options 3172that affect more than one function. 3173@xref{Function Specific Option Pragmas}, for details about the 3174@samp{#pragma GCC optimize} pragma. 3175 3176This attribute should be used for debugging purposes only. It is not 3177suitable in production code. 3178 3179@item patchable_function_entry 3180@cindex @code{patchable_function_entry} function attribute 3181@cindex extra NOP instructions at the function entry point 3182In case the target's text segment can be made writable at run time by 3183any means, padding the function entry with a number of NOPs can be 3184used to provide a universal tool for instrumentation. 3185 3186The @code{patchable_function_entry} function attribute can be used to 3187change the number of NOPs to any desired value. The two-value syntax 3188is the same as for the command-line switch 3189@option{-fpatchable-function-entry=N,M}, generating @var{N} NOPs, with 3190the function entry point before the @var{M}th NOP instruction. 3191@var{M} defaults to 0 if omitted e.g. function entry point is before 3192the first NOP. 3193 3194If patchable function entries are enabled globally using the command-line 3195option @option{-fpatchable-function-entry=N,M}, then you must disable 3196instrumentation on all functions that are part of the instrumentation 3197framework with the attribute @code{patchable_function_entry (0)} 3198to prevent recursion. 3199 3200@item pure 3201@cindex @code{pure} function attribute 3202@cindex functions that have no side effects 3203Many functions have no effects except the return value and their 3204return value depends only on the parameters and/or global variables. 3205Calls to such functions can be subject 3206to common subexpression elimination and loop optimization just as an 3207arithmetic operator would be. These functions should be declared 3208with the attribute @code{pure}. For example, 3209 3210@smallexample 3211int square (int) __attribute__ ((pure)); 3212@end smallexample 3213 3214@noindent 3215says that the hypothetical function @code{square} is safe to call 3216fewer times than the program says. 3217 3218Some common examples of pure functions are @code{strlen} or @code{memcmp}. 3219Interesting non-pure functions are functions with infinite loops or those 3220depending on volatile memory or other system resource, that may change between 3221two consecutive calls (such as @code{feof} in a multithreading environment). 3222 3223The @code{pure} attribute imposes similar but looser restrictions on 3224a function's defintion than the @code{const} attribute: it allows the 3225function to read global variables. Decorating the same function with 3226both the @code{pure} and the @code{const} attribute is diagnosed. 3227Because a @code{pure} function cannot have any side effects it does not 3228make sense for such a function to return @code{void}. Declaring such 3229a function is diagnosed. 3230 3231@item returns_nonnull 3232@cindex @code{returns_nonnull} function attribute 3233The @code{returns_nonnull} attribute specifies that the function 3234return value should be a non-null pointer. For instance, the declaration: 3235 3236@smallexample 3237extern void * 3238mymalloc (size_t len) __attribute__((returns_nonnull)); 3239@end smallexample 3240 3241@noindent 3242lets the compiler optimize callers based on the knowledge 3243that the return value will never be null. 3244 3245@item returns_twice 3246@cindex @code{returns_twice} function attribute 3247@cindex functions that return more than once 3248The @code{returns_twice} attribute tells the compiler that a function may 3249return more than one time. The compiler ensures that all registers 3250are dead before calling such a function and emits a warning about 3251the variables that may be clobbered after the second return from the 3252function. Examples of such functions are @code{setjmp} and @code{vfork}. 3253The @code{longjmp}-like counterpart of such function, if any, might need 3254to be marked with the @code{noreturn} attribute. 3255 3256@item section ("@var{section-name}") 3257@cindex @code{section} function attribute 3258@cindex functions in arbitrary sections 3259Normally, the compiler places the code it generates in the @code{text} section. 3260Sometimes, however, you need additional sections, or you need certain 3261particular functions to appear in special sections. The @code{section} 3262attribute specifies that a function lives in a particular section. 3263For example, the declaration: 3264 3265@smallexample 3266extern void foobar (void) __attribute__ ((section ("bar"))); 3267@end smallexample 3268 3269@noindent 3270puts the function @code{foobar} in the @code{bar} section. 3271 3272Some file formats do not support arbitrary sections so the @code{section} 3273attribute is not available on all platforms. 3274If you need to map the entire contents of a module to a particular 3275section, consider using the facilities of the linker instead. 3276 3277@item sentinel 3278@cindex @code{sentinel} function attribute 3279This function attribute ensures that a parameter in a function call is 3280an explicit @code{NULL}. The attribute is only valid on variadic 3281functions. By default, the sentinel is located at position zero, the 3282last parameter of the function call. If an optional integer position 3283argument P is supplied to the attribute, the sentinel must be located at 3284position P counting backwards from the end of the argument list. 3285 3286@smallexample 3287__attribute__ ((sentinel)) 3288is equivalent to 3289__attribute__ ((sentinel(0))) 3290@end smallexample 3291 3292The attribute is automatically set with a position of 0 for the built-in 3293functions @code{execl} and @code{execlp}. The built-in function 3294@code{execle} has the attribute set with a position of 1. 3295 3296A valid @code{NULL} in this context is defined as zero with any pointer 3297type. If your system defines the @code{NULL} macro with an integer type 3298then you need to add an explicit cast. GCC replaces @code{stddef.h} 3299with a copy that redefines NULL appropriately. 3300 3301The warnings for missing or incorrect sentinels are enabled with 3302@option{-Wformat}. 3303 3304@item simd 3305@itemx simd("@var{mask}") 3306@cindex @code{simd} function attribute 3307This attribute enables creation of one or more function versions that 3308can process multiple arguments using SIMD instructions from a 3309single invocation. Specifying this attribute allows compiler to 3310assume that such versions are available at link time (provided 3311in the same or another translation unit). Generated versions are 3312target-dependent and described in the corresponding Vector ABI document. For 3313x86_64 target this document can be found 3314@w{@uref{https://sourceware.org/glibc/wiki/libmvec?action=AttachFile&do=view&target=VectorABI.txt,here}}. 3315 3316The optional argument @var{mask} may have the value 3317@code{notinbranch} or @code{inbranch}, 3318and instructs the compiler to generate non-masked or masked 3319clones correspondingly. By default, all clones are generated. 3320 3321If the attribute is specified and @code{#pragma omp declare simd} is 3322present on a declaration and the @option{-fopenmp} or @option{-fopenmp-simd} 3323switch is specified, then the attribute is ignored. 3324 3325@item stack_protect 3326@cindex @code{stack_protect} function attribute 3327This attribute adds stack protection code to the function if 3328flags @option{-fstack-protector}, @option{-fstack-protector-strong} 3329or @option{-fstack-protector-explicit} are set. 3330 3331@item target (@var{options}) 3332@cindex @code{target} function attribute 3333Multiple target back ends implement the @code{target} attribute 3334to specify that a function is to 3335be compiled with different target options than specified on the 3336command line. This can be used for instance to have functions 3337compiled with a different ISA (instruction set architecture) than the 3338default. You can also use the @samp{#pragma GCC target} pragma to set 3339more than one function to be compiled with specific target options. 3340@xref{Function Specific Option Pragmas}, for details about the 3341@samp{#pragma GCC target} pragma. 3342 3343For instance, on an x86, you could declare one function with the 3344@code{target("sse4.1,arch=core2")} attribute and another with 3345@code{target("sse4a,arch=amdfam10")}. This is equivalent to 3346compiling the first function with @option{-msse4.1} and 3347@option{-march=core2} options, and the second function with 3348@option{-msse4a} and @option{-march=amdfam10} options. It is up to you 3349to make sure that a function is only invoked on a machine that 3350supports the particular ISA it is compiled for (for example by using 3351@code{cpuid} on x86 to determine what feature bits and architecture 3352family are used). 3353 3354@smallexample 3355int core2_func (void) __attribute__ ((__target__ ("arch=core2"))); 3356int sse3_func (void) __attribute__ ((__target__ ("sse3"))); 3357@end smallexample 3358 3359You can either use multiple 3360strings separated by commas to specify multiple options, 3361or separate the options with a comma (@samp{,}) within a single string. 3362 3363The options supported are specific to each target; refer to @ref{x86 3364Function Attributes}, @ref{PowerPC Function Attributes}, 3365@ref{ARM Function Attributes}, @ref{AArch64 Function Attributes}, 3366@ref{Nios II Function Attributes}, and @ref{S/390 Function Attributes} 3367for details. 3368 3369@item target_clones (@var{options}) 3370@cindex @code{target_clones} function attribute 3371The @code{target_clones} attribute is used to specify that a function 3372be cloned into multiple versions compiled with different target options 3373than specified on the command line. The supported options and restrictions 3374are the same as for @code{target} attribute. 3375 3376For instance, on an x86, you could compile a function with 3377@code{target_clones("sse4.1,avx")}. GCC creates two function clones, 3378one compiled with @option{-msse4.1} and another with @option{-mavx}. 3379 3380On a PowerPC, you can compile a function with 3381@code{target_clones("cpu=power9,default")}. GCC will create two 3382function clones, one compiled with @option{-mcpu=power9} and another 3383with the default options. GCC must be configured to use GLIBC 2.23 or 3384newer in order to use the @code{target_clones} attribute. 3385 3386It also creates a resolver function (see 3387the @code{ifunc} attribute above) that dynamically selects a clone 3388suitable for current architecture. The resolver is created only if there 3389is a usage of a function with @code{target_clones} attribute. 3390 3391@item unused 3392@cindex @code{unused} function attribute 3393This attribute, attached to a function, means that the function is meant 3394to be possibly unused. GCC does not produce a warning for this 3395function. 3396 3397@item used 3398@cindex @code{used} function attribute 3399This attribute, attached to a function, means that code must be emitted 3400for the function even if it appears that the function is not referenced. 3401This is useful, for example, when the function is referenced only in 3402inline assembly. 3403 3404When applied to a member function of a C++ class template, the 3405attribute also means that the function is instantiated if the 3406class itself is instantiated. 3407 3408@item visibility ("@var{visibility_type}") 3409@cindex @code{visibility} function attribute 3410This attribute affects the linkage of the declaration to which it is attached. 3411It can be applied to variables (@pxref{Common Variable Attributes}) and types 3412(@pxref{Common Type Attributes}) as well as functions. 3413 3414There are four supported @var{visibility_type} values: default, 3415hidden, protected or internal visibility. 3416 3417@smallexample 3418void __attribute__ ((visibility ("protected"))) 3419f () @{ /* @r{Do something.} */; @} 3420int i __attribute__ ((visibility ("hidden"))); 3421@end smallexample 3422 3423The possible values of @var{visibility_type} correspond to the 3424visibility settings in the ELF gABI. 3425 3426@table @code 3427@c keep this list of visibilities in alphabetical order. 3428 3429@item default 3430Default visibility is the normal case for the object file format. 3431This value is available for the visibility attribute to override other 3432options that may change the assumed visibility of entities. 3433 3434On ELF, default visibility means that the declaration is visible to other 3435modules and, in shared libraries, means that the declared entity may be 3436overridden. 3437 3438On Darwin, default visibility means that the declaration is visible to 3439other modules. 3440 3441Default visibility corresponds to ``external linkage'' in the language. 3442 3443@item hidden 3444Hidden visibility indicates that the entity declared has a new 3445form of linkage, which we call ``hidden linkage''. Two 3446declarations of an object with hidden linkage refer to the same object 3447if they are in the same shared object. 3448 3449@item internal 3450Internal visibility is like hidden visibility, but with additional 3451processor specific semantics. Unless otherwise specified by the 3452psABI, GCC defines internal visibility to mean that a function is 3453@emph{never} called from another module. Compare this with hidden 3454functions which, while they cannot be referenced directly by other 3455modules, can be referenced indirectly via function pointers. By 3456indicating that a function cannot be called from outside the module, 3457GCC may for instance omit the load of a PIC register since it is known 3458that the calling function loaded the correct value. 3459 3460@item protected 3461Protected visibility is like default visibility except that it 3462indicates that references within the defining module bind to the 3463definition in that module. That is, the declared entity cannot be 3464overridden by another module. 3465 3466@end table 3467 3468All visibilities are supported on many, but not all, ELF targets 3469(supported when the assembler supports the @samp{.visibility} 3470pseudo-op). Default visibility is supported everywhere. Hidden 3471visibility is supported on Darwin targets. 3472 3473The visibility attribute should be applied only to declarations that 3474would otherwise have external linkage. The attribute should be applied 3475consistently, so that the same entity should not be declared with 3476different settings of the attribute. 3477 3478In C++, the visibility attribute applies to types as well as functions 3479and objects, because in C++ types have linkage. A class must not have 3480greater visibility than its non-static data member types and bases, 3481and class members default to the visibility of their class. Also, a 3482declaration without explicit visibility is limited to the visibility 3483of its type. 3484 3485In C++, you can mark member functions and static member variables of a 3486class with the visibility attribute. This is useful if you know a 3487particular method or static member variable should only be used from 3488one shared object; then you can mark it hidden while the rest of the 3489class has default visibility. Care must be taken to avoid breaking 3490the One Definition Rule; for example, it is usually not useful to mark 3491an inline method as hidden without marking the whole class as hidden. 3492 3493A C++ namespace declaration can also have the visibility attribute. 3494 3495@smallexample 3496namespace nspace1 __attribute__ ((visibility ("protected"))) 3497@{ /* @r{Do something.} */; @} 3498@end smallexample 3499 3500This attribute applies only to the particular namespace body, not to 3501other definitions of the same namespace; it is equivalent to using 3502@samp{#pragma GCC visibility} before and after the namespace 3503definition (@pxref{Visibility Pragmas}). 3504 3505In C++, if a template argument has limited visibility, this 3506restriction is implicitly propagated to the template instantiation. 3507Otherwise, template instantiations and specializations default to the 3508visibility of their template. 3509 3510If both the template and enclosing class have explicit visibility, the 3511visibility from the template is used. 3512 3513@item warn_unused_result 3514@cindex @code{warn_unused_result} function attribute 3515The @code{warn_unused_result} attribute causes a warning to be emitted 3516if a caller of the function with this attribute does not use its 3517return value. This is useful for functions where not checking 3518the result is either a security problem or always a bug, such as 3519@code{realloc}. 3520 3521@smallexample 3522int fn () __attribute__ ((warn_unused_result)); 3523int foo () 3524@{ 3525 if (fn () < 0) return -1; 3526 fn (); 3527 return 0; 3528@} 3529@end smallexample 3530 3531@noindent 3532results in warning on line 5. 3533 3534@item weak 3535@cindex @code{weak} function attribute 3536The @code{weak} attribute causes the declaration to be emitted as a weak 3537symbol rather than a global. This is primarily useful in defining 3538library functions that can be overridden in user code, though it can 3539also be used with non-function declarations. Weak symbols are supported 3540for ELF targets, and also for a.out targets when using the GNU assembler 3541and linker. 3542 3543@item weakref 3544@itemx weakref ("@var{target}") 3545@cindex @code{weakref} function attribute 3546The @code{weakref} attribute marks a declaration as a weak reference. 3547Without arguments, it should be accompanied by an @code{alias} attribute 3548naming the target symbol. Optionally, the @var{target} may be given as 3549an argument to @code{weakref} itself. In either case, @code{weakref} 3550implicitly marks the declaration as @code{weak}. Without a 3551@var{target}, given as an argument to @code{weakref} or to @code{alias}, 3552@code{weakref} is equivalent to @code{weak}. 3553 3554@smallexample 3555static int x() __attribute__ ((weakref ("y"))); 3556/* is equivalent to... */ 3557static int x() __attribute__ ((weak, weakref, alias ("y"))); 3558/* and to... */ 3559static int x() __attribute__ ((weakref)); 3560static int x() __attribute__ ((alias ("y"))); 3561@end smallexample 3562 3563A weak reference is an alias that does not by itself require a 3564definition to be given for the target symbol. If the target symbol is 3565only referenced through weak references, then it becomes a @code{weak} 3566undefined symbol. If it is directly referenced, however, then such 3567strong references prevail, and a definition is required for the 3568symbol, not necessarily in the same translation unit. 3569 3570The effect is equivalent to moving all references to the alias to a 3571separate translation unit, renaming the alias to the aliased symbol, 3572declaring it as weak, compiling the two separate translation units and 3573performing a reloadable link on them. 3574 3575At present, a declaration to which @code{weakref} is attached can 3576only be @code{static}. 3577 3578 3579@end table 3580 3581@c This is the end of the target-independent attribute table 3582 3583@node AArch64 Function Attributes 3584@subsection AArch64 Function Attributes 3585 3586The following target-specific function attributes are available for the 3587AArch64 target. For the most part, these options mirror the behavior of 3588similar command-line options (@pxref{AArch64 Options}), but on a 3589per-function basis. 3590 3591@table @code 3592@item general-regs-only 3593@cindex @code{general-regs-only} function attribute, AArch64 3594Indicates that no floating-point or Advanced SIMD registers should be 3595used when generating code for this function. If the function explicitly 3596uses floating-point code, then the compiler gives an error. This is 3597the same behavior as that of the command-line option 3598@option{-mgeneral-regs-only}. 3599 3600@item fix-cortex-a53-835769 3601@cindex @code{fix-cortex-a53-835769} function attribute, AArch64 3602Indicates that the workaround for the Cortex-A53 erratum 835769 should be 3603applied to this function. To explicitly disable the workaround for this 3604function specify the negated form: @code{no-fix-cortex-a53-835769}. 3605This corresponds to the behavior of the command line options 3606@option{-mfix-cortex-a53-835769} and @option{-mno-fix-cortex-a53-835769}. 3607 3608@item cmodel= 3609@cindex @code{cmodel=} function attribute, AArch64 3610Indicates that code should be generated for a particular code model for 3611this function. The behavior and permissible arguments are the same as 3612for the command line option @option{-mcmodel=}. 3613 3614@item strict-align 3615@cindex @code{strict-align} function attribute, AArch64 3616Indicates that the compiler should not assume that unaligned memory references 3617are handled by the system. The behavior is the same as for the command-line 3618option @option{-mstrict-align}. 3619 3620@item omit-leaf-frame-pointer 3621@cindex @code{omit-leaf-frame-pointer} function attribute, AArch64 3622Indicates that the frame pointer should be omitted for a leaf function call. 3623To keep the frame pointer, the inverse attribute 3624@code{no-omit-leaf-frame-pointer} can be specified. These attributes have 3625the same behavior as the command-line options @option{-momit-leaf-frame-pointer} 3626and @option{-mno-omit-leaf-frame-pointer}. 3627 3628@item tls-dialect= 3629@cindex @code{tls-dialect=} function attribute, AArch64 3630Specifies the TLS dialect to use for this function. The behavior and 3631permissible arguments are the same as for the command-line option 3632@option{-mtls-dialect=}. 3633 3634@item arch= 3635@cindex @code{arch=} function attribute, AArch64 3636Specifies the architecture version and architectural extensions to use 3637for this function. The behavior and permissible arguments are the same as 3638for the @option{-march=} command-line option. 3639 3640@item tune= 3641@cindex @code{tune=} function attribute, AArch64 3642Specifies the core for which to tune the performance of this function. 3643The behavior and permissible arguments are the same as for the @option{-mtune=} 3644command-line option. 3645 3646@item cpu= 3647@cindex @code{cpu=} function attribute, AArch64 3648Specifies the core for which to tune the performance of this function and also 3649whose architectural features to use. The behavior and valid arguments are the 3650same as for the @option{-mcpu=} command-line option. 3651 3652@item sign-return-address 3653@cindex @code{sign-return-address} function attribute, AArch64 3654Select the function scope on which return address signing will be applied. The 3655behavior and permissible arguments are the same as for the command-line option 3656@option{-msign-return-address=}. The default value is @code{none}. 3657 3658@end table 3659 3660The above target attributes can be specified as follows: 3661 3662@smallexample 3663__attribute__((target("@var{attr-string}"))) 3664int 3665f (int a) 3666@{ 3667 return a + 5; 3668@} 3669@end smallexample 3670 3671where @code{@var{attr-string}} is one of the attribute strings specified above. 3672 3673Additionally, the architectural extension string may be specified on its 3674own. This can be used to turn on and off particular architectural extensions 3675without having to specify a particular architecture version or core. Example: 3676 3677@smallexample 3678__attribute__((target("+crc+nocrypto"))) 3679int 3680foo (int a) 3681@{ 3682 return a + 5; 3683@} 3684@end smallexample 3685 3686In this example @code{target("+crc+nocrypto")} enables the @code{crc} 3687extension and disables the @code{crypto} extension for the function @code{foo} 3688without modifying an existing @option{-march=} or @option{-mcpu} option. 3689 3690Multiple target function attributes can be specified by separating them with 3691a comma. For example: 3692@smallexample 3693__attribute__((target("arch=armv8-a+crc+crypto,tune=cortex-a53"))) 3694int 3695foo (int a) 3696@{ 3697 return a + 5; 3698@} 3699@end smallexample 3700 3701is valid and compiles function @code{foo} for ARMv8-A with @code{crc} 3702and @code{crypto} extensions and tunes it for @code{cortex-a53}. 3703 3704@subsubsection Inlining rules 3705Specifying target attributes on individual functions or performing link-time 3706optimization across translation units compiled with different target options 3707can affect function inlining rules: 3708 3709In particular, a caller function can inline a callee function only if the 3710architectural features available to the callee are a subset of the features 3711available to the caller. 3712For example: A function @code{foo} compiled with @option{-march=armv8-a+crc}, 3713or tagged with the equivalent @code{arch=armv8-a+crc} attribute, 3714can inline a function @code{bar} compiled with @option{-march=armv8-a+nocrc} 3715because the all the architectural features that function @code{bar} requires 3716are available to function @code{foo}. Conversely, function @code{bar} cannot 3717inline function @code{foo}. 3718 3719Additionally inlining a function compiled with @option{-mstrict-align} into a 3720function compiled without @code{-mstrict-align} is not allowed. 3721However, inlining a function compiled without @option{-mstrict-align} into a 3722function compiled with @option{-mstrict-align} is allowed. 3723 3724Note that CPU tuning options and attributes such as the @option{-mcpu=}, 3725@option{-mtune=} do not inhibit inlining unless the CPU specified by the 3726@option{-mcpu=} option or the @code{cpu=} attribute conflicts with the 3727architectural feature rules specified above. 3728 3729@node ARC Function Attributes 3730@subsection ARC Function Attributes 3731 3732These function attributes are supported by the ARC back end: 3733 3734@table @code 3735@item interrupt 3736@cindex @code{interrupt} function attribute, ARC 3737Use this attribute to indicate 3738that the specified function is an interrupt handler. The compiler generates 3739function entry and exit sequences suitable for use in an interrupt handler 3740when this attribute is present. 3741 3742On the ARC, you must specify the kind of interrupt to be handled 3743in a parameter to the interrupt attribute like this: 3744 3745@smallexample 3746void f () __attribute__ ((interrupt ("ilink1"))); 3747@end smallexample 3748 3749Permissible values for this parameter are: @w{@code{ilink1}} and 3750@w{@code{ilink2}}. 3751 3752@item long_call 3753@itemx medium_call 3754@itemx short_call 3755@cindex @code{long_call} function attribute, ARC 3756@cindex @code{medium_call} function attribute, ARC 3757@cindex @code{short_call} function attribute, ARC 3758@cindex indirect calls, ARC 3759These attributes specify how a particular function is called. 3760These attributes override the 3761@option{-mlong-calls} and @option{-mmedium-calls} (@pxref{ARC Options}) 3762command-line switches and @code{#pragma long_calls} settings. 3763 3764For ARC, a function marked with the @code{long_call} attribute is 3765always called using register-indirect jump-and-link instructions, 3766thereby enabling the called function to be placed anywhere within the 376732-bit address space. A function marked with the @code{medium_call} 3768attribute will always be close enough to be called with an unconditional 3769branch-and-link instruction, which has a 25-bit offset from 3770the call site. A function marked with the @code{short_call} 3771attribute will always be close enough to be called with a conditional 3772branch-and-link instruction, which has a 21-bit offset from 3773the call site. 3774 3775@item jli_always 3776@cindex @code{jli_always} function attribute, ARC 3777Forces a particular function to be called using @code{jli} 3778instruction. The @code{jli} instruction makes use of a table stored 3779into @code{.jlitab} section, which holds the location of the functions 3780which are addressed using this instruction. 3781 3782@item jli_fixed 3783@cindex @code{jli_fixed} function attribute, ARC 3784Identical like the above one, but the location of the function in the 3785@code{jli} table is known and given as an attribute parameter. 3786 3787@item secure_call 3788@cindex @code{secure_call} function attribute, ARC 3789This attribute allows one to mark secure-code functions that are 3790callable from normal mode. The location of the secure call function 3791into the @code{sjli} table needs to be passed as argument. 3792 3793@end table 3794 3795@node ARM Function Attributes 3796@subsection ARM Function Attributes 3797 3798These function attributes are supported for ARM targets: 3799 3800@table @code 3801@item interrupt 3802@cindex @code{interrupt} function attribute, ARM 3803Use this attribute to indicate 3804that the specified function is an interrupt handler. The compiler generates 3805function entry and exit sequences suitable for use in an interrupt handler 3806when this attribute is present. 3807 3808You can specify the kind of interrupt to be handled by 3809adding an optional parameter to the interrupt attribute like this: 3810 3811@smallexample 3812void f () __attribute__ ((interrupt ("IRQ"))); 3813@end smallexample 3814 3815@noindent 3816Permissible values for this parameter are: @code{IRQ}, @code{FIQ}, 3817@code{SWI}, @code{ABORT} and @code{UNDEF}. 3818 3819On ARMv7-M the interrupt type is ignored, and the attribute means the function 3820may be called with a word-aligned stack pointer. 3821 3822@item isr 3823@cindex @code{isr} function attribute, ARM 3824Use this attribute on ARM to write Interrupt Service Routines. This is an 3825alias to the @code{interrupt} attribute above. 3826 3827@item long_call 3828@itemx short_call 3829@cindex @code{long_call} function attribute, ARM 3830@cindex @code{short_call} function attribute, ARM 3831@cindex indirect calls, ARM 3832These attributes specify how a particular function is called. 3833These attributes override the 3834@option{-mlong-calls} (@pxref{ARM Options}) 3835command-line switch and @code{#pragma long_calls} settings. For ARM, the 3836@code{long_call} attribute indicates that the function might be far 3837away from the call site and require a different (more expensive) 3838calling sequence. The @code{short_call} attribute always places 3839the offset to the function from the call site into the @samp{BL} 3840instruction directly. 3841 3842@item naked 3843@cindex @code{naked} function attribute, ARM 3844This attribute allows the compiler to construct the 3845requisite function declaration, while allowing the body of the 3846function to be assembly code. The specified function will not have 3847prologue/epilogue sequences generated by the compiler. Only basic 3848@code{asm} statements can safely be included in naked functions 3849(@pxref{Basic Asm}). While using extended @code{asm} or a mixture of 3850basic @code{asm} and C code may appear to work, they cannot be 3851depended upon to work reliably and are not supported. 3852 3853@item pcs 3854@cindex @code{pcs} function attribute, ARM 3855 3856The @code{pcs} attribute can be used to control the calling convention 3857used for a function on ARM. The attribute takes an argument that specifies 3858the calling convention to use. 3859 3860When compiling using the AAPCS ABI (or a variant of it) then valid 3861values for the argument are @code{"aapcs"} and @code{"aapcs-vfp"}. In 3862order to use a variant other than @code{"aapcs"} then the compiler must 3863be permitted to use the appropriate co-processor registers (i.e., the 3864VFP registers must be available in order to use @code{"aapcs-vfp"}). 3865For example, 3866 3867@smallexample 3868/* Argument passed in r0, and result returned in r0+r1. */ 3869double f2d (float) __attribute__((pcs("aapcs"))); 3870@end smallexample 3871 3872Variadic functions always use the @code{"aapcs"} calling convention and 3873the compiler rejects attempts to specify an alternative. 3874 3875@item target (@var{options}) 3876@cindex @code{target} function attribute 3877As discussed in @ref{Common Function Attributes}, this attribute 3878allows specification of target-specific compilation options. 3879 3880On ARM, the following options are allowed: 3881 3882@table @samp 3883@item thumb 3884@cindex @code{target("thumb")} function attribute, ARM 3885Force code generation in the Thumb (T16/T32) ISA, depending on the 3886architecture level. 3887 3888@item arm 3889@cindex @code{target("arm")} function attribute, ARM 3890Force code generation in the ARM (A32) ISA. 3891 3892Functions from different modes can be inlined in the caller's mode. 3893 3894@item fpu= 3895@cindex @code{target("fpu=")} function attribute, ARM 3896Specifies the fpu for which to tune the performance of this function. 3897The behavior and permissible arguments are the same as for the @option{-mfpu=} 3898command-line option. 3899 3900@item arch= 3901@cindex @code{arch=} function attribute, ARM 3902Specifies the architecture version and architectural extensions to use 3903for this function. The behavior and permissible arguments are the same as 3904for the @option{-march=} command-line option. 3905 3906The above target attributes can be specified as follows: 3907 3908@smallexample 3909__attribute__((target("arch=armv8-a+crc"))) 3910int 3911f (int a) 3912@{ 3913 return a + 5; 3914@} 3915@end smallexample 3916 3917Additionally, the architectural extension string may be specified on its 3918own. This can be used to turn on and off particular architectural extensions 3919without having to specify a particular architecture version or core. Example: 3920 3921@smallexample 3922__attribute__((target("+crc+nocrypto"))) 3923int 3924foo (int a) 3925@{ 3926 return a + 5; 3927@} 3928@end smallexample 3929 3930In this example @code{target("+crc+nocrypto")} enables the @code{crc} 3931extension and disables the @code{crypto} extension for the function @code{foo} 3932without modifying an existing @option{-march=} or @option{-mcpu} option. 3933 3934@end table 3935 3936@end table 3937 3938@node AVR Function Attributes 3939@subsection AVR Function Attributes 3940 3941These function attributes are supported by the AVR back end: 3942 3943@table @code 3944@item interrupt 3945@cindex @code{interrupt} function attribute, AVR 3946Use this attribute to indicate 3947that the specified function is an interrupt handler. The compiler generates 3948function entry and exit sequences suitable for use in an interrupt handler 3949when this attribute is present. 3950 3951On the AVR, the hardware globally disables interrupts when an 3952interrupt is executed. The first instruction of an interrupt handler 3953declared with this attribute is a @code{SEI} instruction to 3954re-enable interrupts. See also the @code{signal} function attribute 3955that does not insert a @code{SEI} instruction. If both @code{signal} and 3956@code{interrupt} are specified for the same function, @code{signal} 3957is silently ignored. 3958 3959@item naked 3960@cindex @code{naked} function attribute, AVR 3961This attribute allows the compiler to construct the 3962requisite function declaration, while allowing the body of the 3963function to be assembly code. The specified function will not have 3964prologue/epilogue sequences generated by the compiler. Only basic 3965@code{asm} statements can safely be included in naked functions 3966(@pxref{Basic Asm}). While using extended @code{asm} or a mixture of 3967basic @code{asm} and C code may appear to work, they cannot be 3968depended upon to work reliably and are not supported. 3969 3970@item no_gccisr 3971@cindex @code{no_gccisr} function attribute, AVR 3972Do not use @code{__gcc_isr} pseudo instructions in a function with 3973the @code{interrupt} or @code{signal} attribute aka. interrupt 3974service routine (ISR). 3975Use this attribute if the preamble of the ISR prologue should always read 3976@example 3977push __zero_reg__ 3978push __tmp_reg__ 3979in __tmp_reg__, __SREG__ 3980push __tmp_reg__ 3981clr __zero_reg__ 3982@end example 3983and accordingly for the postamble of the epilogue --- no matter whether 3984the mentioned registers are actually used in the ISR or not. 3985Situations where you might want to use this attribute include: 3986@itemize @bullet 3987@item 3988Code that (effectively) clobbers bits of @code{SREG} other than the 3989@code{I}-flag by writing to the memory location of @code{SREG}. 3990@item 3991Code that uses inline assembler to jump to a different function which 3992expects (parts of) the prologue code as outlined above to be present. 3993@end itemize 3994To disable @code{__gcc_isr} generation for the whole compilation unit, 3995there is option @option{-mno-gas-isr-prologues}, @pxref{AVR Options}. 3996 3997@item OS_main 3998@itemx OS_task 3999@cindex @code{OS_main} function attribute, AVR 4000@cindex @code{OS_task} function attribute, AVR 4001On AVR, functions with the @code{OS_main} or @code{OS_task} attribute 4002do not save/restore any call-saved register in their prologue/epilogue. 4003 4004The @code{OS_main} attribute can be used when there @emph{is 4005guarantee} that interrupts are disabled at the time when the function 4006is entered. This saves resources when the stack pointer has to be 4007changed to set up a frame for local variables. 4008 4009The @code{OS_task} attribute can be used when there is @emph{no 4010guarantee} that interrupts are disabled at that time when the function 4011is entered like for, e@.g@. task functions in a multi-threading operating 4012system. In that case, changing the stack pointer register is 4013guarded by save/clear/restore of the global interrupt enable flag. 4014 4015The differences to the @code{naked} function attribute are: 4016@itemize @bullet 4017@item @code{naked} functions do not have a return instruction whereas 4018@code{OS_main} and @code{OS_task} functions have a @code{RET} or 4019@code{RETI} return instruction. 4020@item @code{naked} functions do not set up a frame for local variables 4021or a frame pointer whereas @code{OS_main} and @code{OS_task} do this 4022as needed. 4023@end itemize 4024 4025@item signal 4026@cindex @code{signal} function attribute, AVR 4027Use this attribute on the AVR to indicate that the specified 4028function is an interrupt handler. The compiler generates function 4029entry and exit sequences suitable for use in an interrupt handler when this 4030attribute is present. 4031 4032See also the @code{interrupt} function attribute. 4033 4034The AVR hardware globally disables interrupts when an interrupt is executed. 4035Interrupt handler functions defined with the @code{signal} attribute 4036do not re-enable interrupts. It is save to enable interrupts in a 4037@code{signal} handler. This ``save'' only applies to the code 4038generated by the compiler and not to the IRQ layout of the 4039application which is responsibility of the application. 4040 4041If both @code{signal} and @code{interrupt} are specified for the same 4042function, @code{signal} is silently ignored. 4043@end table 4044 4045@node Blackfin Function Attributes 4046@subsection Blackfin Function Attributes 4047 4048These function attributes are supported by the Blackfin back end: 4049 4050@table @code 4051 4052@item exception_handler 4053@cindex @code{exception_handler} function attribute 4054@cindex exception handler functions, Blackfin 4055Use this attribute on the Blackfin to indicate that the specified function 4056is an exception handler. The compiler generates function entry and 4057exit sequences suitable for use in an exception handler when this 4058attribute is present. 4059 4060@item interrupt_handler 4061@cindex @code{interrupt_handler} function attribute, Blackfin 4062Use this attribute to 4063indicate that the specified function is an interrupt handler. The compiler 4064generates function entry and exit sequences suitable for use in an 4065interrupt handler when this attribute is present. 4066 4067@item kspisusp 4068@cindex @code{kspisusp} function attribute, Blackfin 4069@cindex User stack pointer in interrupts on the Blackfin 4070When used together with @code{interrupt_handler}, @code{exception_handler} 4071or @code{nmi_handler}, code is generated to load the stack pointer 4072from the USP register in the function prologue. 4073 4074@item l1_text 4075@cindex @code{l1_text} function attribute, Blackfin 4076This attribute specifies a function to be placed into L1 Instruction 4077SRAM@. The function is put into a specific section named @code{.l1.text}. 4078With @option{-mfdpic}, function calls with a such function as the callee 4079or caller uses inlined PLT. 4080 4081@item l2 4082@cindex @code{l2} function attribute, Blackfin 4083This attribute specifies a function to be placed into L2 4084SRAM. The function is put into a specific section named 4085@code{.l2.text}. With @option{-mfdpic}, callers of such functions use 4086an inlined PLT. 4087 4088@item longcall 4089@itemx shortcall 4090@cindex indirect calls, Blackfin 4091@cindex @code{longcall} function attribute, Blackfin 4092@cindex @code{shortcall} function attribute, Blackfin 4093The @code{longcall} attribute 4094indicates that the function might be far away from the call site and 4095require a different (more expensive) calling sequence. The 4096@code{shortcall} attribute indicates that the function is always close 4097enough for the shorter calling sequence to be used. These attributes 4098override the @option{-mlongcall} switch. 4099 4100@item nesting 4101@cindex @code{nesting} function attribute, Blackfin 4102@cindex Allow nesting in an interrupt handler on the Blackfin processor 4103Use this attribute together with @code{interrupt_handler}, 4104@code{exception_handler} or @code{nmi_handler} to indicate that the function 4105entry code should enable nested interrupts or exceptions. 4106 4107@item nmi_handler 4108@cindex @code{nmi_handler} function attribute, Blackfin 4109@cindex NMI handler functions on the Blackfin processor 4110Use this attribute on the Blackfin to indicate that the specified function 4111is an NMI handler. The compiler generates function entry and 4112exit sequences suitable for use in an NMI handler when this 4113attribute is present. 4114 4115@item saveall 4116@cindex @code{saveall} function attribute, Blackfin 4117@cindex save all registers on the Blackfin 4118Use this attribute to indicate that 4119all registers except the stack pointer should be saved in the prologue 4120regardless of whether they are used or not. 4121@end table 4122 4123@node CR16 Function Attributes 4124@subsection CR16 Function Attributes 4125 4126These function attributes are supported by the CR16 back end: 4127 4128@table @code 4129@item interrupt 4130@cindex @code{interrupt} function attribute, CR16 4131Use this attribute to indicate 4132that the specified function is an interrupt handler. The compiler generates 4133function entry and exit sequences suitable for use in an interrupt handler 4134when this attribute is present. 4135@end table 4136 4137@node Epiphany Function Attributes 4138@subsection Epiphany Function Attributes 4139 4140These function attributes are supported by the Epiphany back end: 4141 4142@table @code 4143@item disinterrupt 4144@cindex @code{disinterrupt} function attribute, Epiphany 4145This attribute causes the compiler to emit 4146instructions to disable interrupts for the duration of the given 4147function. 4148 4149@item forwarder_section 4150@cindex @code{forwarder_section} function attribute, Epiphany 4151This attribute modifies the behavior of an interrupt handler. 4152The interrupt handler may be in external memory which cannot be 4153reached by a branch instruction, so generate a local memory trampoline 4154to transfer control. The single parameter identifies the section where 4155the trampoline is placed. 4156 4157@item interrupt 4158@cindex @code{interrupt} function attribute, Epiphany 4159Use this attribute to indicate 4160that the specified function is an interrupt handler. The compiler generates 4161function entry and exit sequences suitable for use in an interrupt handler 4162when this attribute is present. It may also generate 4163a special section with code to initialize the interrupt vector table. 4164 4165On Epiphany targets one or more optional parameters can be added like this: 4166 4167@smallexample 4168void __attribute__ ((interrupt ("dma0, dma1"))) universal_dma_handler (); 4169@end smallexample 4170 4171Permissible values for these parameters are: @w{@code{reset}}, 4172@w{@code{software_exception}}, @w{@code{page_miss}}, 4173@w{@code{timer0}}, @w{@code{timer1}}, @w{@code{message}}, 4174@w{@code{dma0}}, @w{@code{dma1}}, @w{@code{wand}} and @w{@code{swi}}. 4175Multiple parameters indicate that multiple entries in the interrupt 4176vector table should be initialized for this function, i.e.@: for each 4177parameter @w{@var{name}}, a jump to the function is emitted in 4178the section @w{ivt_entry_@var{name}}. The parameter(s) may be omitted 4179entirely, in which case no interrupt vector table entry is provided. 4180 4181Note that interrupts are enabled inside the function 4182unless the @code{disinterrupt} attribute is also specified. 4183 4184The following examples are all valid uses of these attributes on 4185Epiphany targets: 4186@smallexample 4187void __attribute__ ((interrupt)) universal_handler (); 4188void __attribute__ ((interrupt ("dma1"))) dma1_handler (); 4189void __attribute__ ((interrupt ("dma0, dma1"))) 4190 universal_dma_handler (); 4191void __attribute__ ((interrupt ("timer0"), disinterrupt)) 4192 fast_timer_handler (); 4193void __attribute__ ((interrupt ("dma0, dma1"), 4194 forwarder_section ("tramp"))) 4195 external_dma_handler (); 4196@end smallexample 4197 4198@item long_call 4199@itemx short_call 4200@cindex @code{long_call} function attribute, Epiphany 4201@cindex @code{short_call} function attribute, Epiphany 4202@cindex indirect calls, Epiphany 4203These attributes specify how a particular function is called. 4204These attributes override the 4205@option{-mlong-calls} (@pxref{Adapteva Epiphany Options}) 4206command-line switch and @code{#pragma long_calls} settings. 4207@end table 4208 4209 4210@node H8/300 Function Attributes 4211@subsection H8/300 Function Attributes 4212 4213These function attributes are available for H8/300 targets: 4214 4215@table @code 4216@item function_vector 4217@cindex @code{function_vector} function attribute, H8/300 4218Use this attribute on the H8/300, H8/300H, and H8S to indicate 4219that the specified function should be called through the function vector. 4220Calling a function through the function vector reduces code size; however, 4221the function vector has a limited size (maximum 128 entries on the H8/300 4222and 64 entries on the H8/300H and H8S) 4223and shares space with the interrupt vector. 4224 4225@item interrupt_handler 4226@cindex @code{interrupt_handler} function attribute, H8/300 4227Use this attribute on the H8/300, H8/300H, and H8S to 4228indicate that the specified function is an interrupt handler. The compiler 4229generates function entry and exit sequences suitable for use in an 4230interrupt handler when this attribute is present. 4231 4232@item saveall 4233@cindex @code{saveall} function attribute, H8/300 4234@cindex save all registers on the H8/300, H8/300H, and H8S 4235Use this attribute on the H8/300, H8/300H, and H8S to indicate that 4236all registers except the stack pointer should be saved in the prologue 4237regardless of whether they are used or not. 4238@end table 4239 4240@node IA-64 Function Attributes 4241@subsection IA-64 Function Attributes 4242 4243These function attributes are supported on IA-64 targets: 4244 4245@table @code 4246@item syscall_linkage 4247@cindex @code{syscall_linkage} function attribute, IA-64 4248This attribute is used to modify the IA-64 calling convention by marking 4249all input registers as live at all function exits. This makes it possible 4250to restart a system call after an interrupt without having to save/restore 4251the input registers. This also prevents kernel data from leaking into 4252application code. 4253 4254@item version_id 4255@cindex @code{version_id} function attribute, IA-64 4256This IA-64 HP-UX attribute, attached to a global variable or function, renames a 4257symbol to contain a version string, thus allowing for function level 4258versioning. HP-UX system header files may use function level versioning 4259for some system calls. 4260 4261@smallexample 4262extern int foo () __attribute__((version_id ("20040821"))); 4263@end smallexample 4264 4265@noindent 4266Calls to @code{foo} are mapped to calls to @code{foo@{20040821@}}. 4267@end table 4268 4269@node M32C Function Attributes 4270@subsection M32C Function Attributes 4271 4272These function attributes are supported by the M32C back end: 4273 4274@table @code 4275@item bank_switch 4276@cindex @code{bank_switch} function attribute, M32C 4277When added to an interrupt handler with the M32C port, causes the 4278prologue and epilogue to use bank switching to preserve the registers 4279rather than saving them on the stack. 4280 4281@item fast_interrupt 4282@cindex @code{fast_interrupt} function attribute, M32C 4283Use this attribute on the M32C port to indicate that the specified 4284function is a fast interrupt handler. This is just like the 4285@code{interrupt} attribute, except that @code{freit} is used to return 4286instead of @code{reit}. 4287 4288@item function_vector 4289@cindex @code{function_vector} function attribute, M16C/M32C 4290On M16C/M32C targets, the @code{function_vector} attribute declares a 4291special page subroutine call function. Use of this attribute reduces 4292the code size by 2 bytes for each call generated to the 4293subroutine. The argument to the attribute is the vector number entry 4294from the special page vector table which contains the 16 low-order 4295bits of the subroutine's entry address. Each vector table has special 4296page number (18 to 255) that is used in @code{jsrs} instructions. 4297Jump addresses of the routines are generated by adding 0x0F0000 (in 4298case of M16C targets) or 0xFF0000 (in case of M32C targets), to the 42992-byte addresses set in the vector table. Therefore you need to ensure 4300that all the special page vector routines should get mapped within the 4301address range 0x0F0000 to 0x0FFFFF (for M16C) and 0xFF0000 to 0xFFFFFF 4302(for M32C). 4303 4304In the following example 2 bytes are saved for each call to 4305function @code{foo}. 4306 4307@smallexample 4308void foo (void) __attribute__((function_vector(0x18))); 4309void foo (void) 4310@{ 4311@} 4312 4313void bar (void) 4314@{ 4315 foo(); 4316@} 4317@end smallexample 4318 4319If functions are defined in one file and are called in another file, 4320then be sure to write this declaration in both files. 4321 4322This attribute is ignored for R8C target. 4323 4324@item interrupt 4325@cindex @code{interrupt} function attribute, M32C 4326Use this attribute to indicate 4327that the specified function is an interrupt handler. The compiler generates 4328function entry and exit sequences suitable for use in an interrupt handler 4329when this attribute is present. 4330@end table 4331 4332@node M32R/D Function Attributes 4333@subsection M32R/D Function Attributes 4334 4335These function attributes are supported by the M32R/D back end: 4336 4337@table @code 4338@item interrupt 4339@cindex @code{interrupt} function attribute, M32R/D 4340Use this attribute to indicate 4341that the specified function is an interrupt handler. The compiler generates 4342function entry and exit sequences suitable for use in an interrupt handler 4343when this attribute is present. 4344 4345@item model (@var{model-name}) 4346@cindex @code{model} function attribute, M32R/D 4347@cindex function addressability on the M32R/D 4348 4349On the M32R/D, use this attribute to set the addressability of an 4350object, and of the code generated for a function. The identifier 4351@var{model-name} is one of @code{small}, @code{medium}, or 4352@code{large}, representing each of the code models. 4353 4354Small model objects live in the lower 16MB of memory (so that their 4355addresses can be loaded with the @code{ld24} instruction), and are 4356callable with the @code{bl} instruction. 4357 4358Medium model objects may live anywhere in the 32-bit address space (the 4359compiler generates @code{seth/add3} instructions to load their addresses), 4360and are callable with the @code{bl} instruction. 4361 4362Large model objects may live anywhere in the 32-bit address space (the 4363compiler generates @code{seth/add3} instructions to load their addresses), 4364and may not be reachable with the @code{bl} instruction (the compiler 4365generates the much slower @code{seth/add3/jl} instruction sequence). 4366@end table 4367 4368@node m68k Function Attributes 4369@subsection m68k Function Attributes 4370 4371These function attributes are supported by the m68k back end: 4372 4373@table @code 4374@item interrupt 4375@itemx interrupt_handler 4376@cindex @code{interrupt} function attribute, m68k 4377@cindex @code{interrupt_handler} function attribute, m68k 4378Use this attribute to 4379indicate that the specified function is an interrupt handler. The compiler 4380generates function entry and exit sequences suitable for use in an 4381interrupt handler when this attribute is present. Either name may be used. 4382 4383@item interrupt_thread 4384@cindex @code{interrupt_thread} function attribute, fido 4385Use this attribute on fido, a subarchitecture of the m68k, to indicate 4386that the specified function is an interrupt handler that is designed 4387to run as a thread. The compiler omits generate prologue/epilogue 4388sequences and replaces the return instruction with a @code{sleep} 4389instruction. This attribute is available only on fido. 4390@end table 4391 4392@node MCORE Function Attributes 4393@subsection MCORE Function Attributes 4394 4395These function attributes are supported by the MCORE back end: 4396 4397@table @code 4398@item naked 4399@cindex @code{naked} function attribute, MCORE 4400This attribute allows the compiler to construct the 4401requisite function declaration, while allowing the body of the 4402function to be assembly code. The specified function will not have 4403prologue/epilogue sequences generated by the compiler. Only basic 4404@code{asm} statements can safely be included in naked functions 4405(@pxref{Basic Asm}). While using extended @code{asm} or a mixture of 4406basic @code{asm} and C code may appear to work, they cannot be 4407depended upon to work reliably and are not supported. 4408@end table 4409 4410@node MeP Function Attributes 4411@subsection MeP Function Attributes 4412 4413These function attributes are supported by the MeP back end: 4414 4415@table @code 4416@item disinterrupt 4417@cindex @code{disinterrupt} function attribute, MeP 4418On MeP targets, this attribute causes the compiler to emit 4419instructions to disable interrupts for the duration of the given 4420function. 4421 4422@item interrupt 4423@cindex @code{interrupt} function attribute, MeP 4424Use this attribute to indicate 4425that the specified function is an interrupt handler. The compiler generates 4426function entry and exit sequences suitable for use in an interrupt handler 4427when this attribute is present. 4428 4429@item near 4430@cindex @code{near} function attribute, MeP 4431This attribute causes the compiler to assume the called 4432function is close enough to use the normal calling convention, 4433overriding the @option{-mtf} command-line option. 4434 4435@item far 4436@cindex @code{far} function attribute, MeP 4437On MeP targets this causes the compiler to use a calling convention 4438that assumes the called function is too far away for the built-in 4439addressing modes. 4440 4441@item vliw 4442@cindex @code{vliw} function attribute, MeP 4443The @code{vliw} attribute tells the compiler to emit 4444instructions in VLIW mode instead of core mode. Note that this 4445attribute is not allowed unless a VLIW coprocessor has been configured 4446and enabled through command-line options. 4447@end table 4448 4449@node MicroBlaze Function Attributes 4450@subsection MicroBlaze Function Attributes 4451 4452These function attributes are supported on MicroBlaze targets: 4453 4454@table @code 4455@item save_volatiles 4456@cindex @code{save_volatiles} function attribute, MicroBlaze 4457Use this attribute to indicate that the function is 4458an interrupt handler. All volatile registers (in addition to non-volatile 4459registers) are saved in the function prologue. If the function is a leaf 4460function, only volatiles used by the function are saved. A normal function 4461return is generated instead of a return from interrupt. 4462 4463@item break_handler 4464@cindex @code{break_handler} function attribute, MicroBlaze 4465@cindex break handler functions 4466Use this attribute to indicate that 4467the specified function is a break handler. The compiler generates function 4468entry and exit sequences suitable for use in an break handler when this 4469attribute is present. The return from @code{break_handler} is done through 4470the @code{rtbd} instead of @code{rtsd}. 4471 4472@smallexample 4473void f () __attribute__ ((break_handler)); 4474@end smallexample 4475 4476@item interrupt_handler 4477@itemx fast_interrupt 4478@cindex @code{interrupt_handler} function attribute, MicroBlaze 4479@cindex @code{fast_interrupt} function attribute, MicroBlaze 4480These attributes indicate that the specified function is an interrupt 4481handler. Use the @code{fast_interrupt} attribute to indicate handlers 4482used in low-latency interrupt mode, and @code{interrupt_handler} for 4483interrupts that do not use low-latency handlers. In both cases, GCC 4484emits appropriate prologue code and generates a return from the handler 4485using @code{rtid} instead of @code{rtsd}. 4486@end table 4487 4488@node Microsoft Windows Function Attributes 4489@subsection Microsoft Windows Function Attributes 4490 4491The following attributes are available on Microsoft Windows and Symbian OS 4492targets. 4493 4494@table @code 4495@item dllexport 4496@cindex @code{dllexport} function attribute 4497@cindex @code{__declspec(dllexport)} 4498On Microsoft Windows targets and Symbian OS targets the 4499@code{dllexport} attribute causes the compiler to provide a global 4500pointer to a pointer in a DLL, so that it can be referenced with the 4501@code{dllimport} attribute. On Microsoft Windows targets, the pointer 4502name is formed by combining @code{_imp__} and the function or variable 4503name. 4504 4505You can use @code{__declspec(dllexport)} as a synonym for 4506@code{__attribute__ ((dllexport))} for compatibility with other 4507compilers. 4508 4509On systems that support the @code{visibility} attribute, this 4510attribute also implies ``default'' visibility. It is an error to 4511explicitly specify any other visibility. 4512 4513GCC's default behavior is to emit all inline functions with the 4514@code{dllexport} attribute. Since this can cause object file-size bloat, 4515you can use @option{-fno-keep-inline-dllexport}, which tells GCC to 4516ignore the attribute for inlined functions unless the 4517@option{-fkeep-inline-functions} flag is used instead. 4518 4519The attribute is ignored for undefined symbols. 4520 4521When applied to C++ classes, the attribute marks defined non-inlined 4522member functions and static data members as exports. Static consts 4523initialized in-class are not marked unless they are also defined 4524out-of-class. 4525 4526For Microsoft Windows targets there are alternative methods for 4527including the symbol in the DLL's export table such as using a 4528@file{.def} file with an @code{EXPORTS} section or, with GNU ld, using 4529the @option{--export-all} linker flag. 4530 4531@item dllimport 4532@cindex @code{dllimport} function attribute 4533@cindex @code{__declspec(dllimport)} 4534On Microsoft Windows and Symbian OS targets, the @code{dllimport} 4535attribute causes the compiler to reference a function or variable via 4536a global pointer to a pointer that is set up by the DLL exporting the 4537symbol. The attribute implies @code{extern}. On Microsoft Windows 4538targets, the pointer name is formed by combining @code{_imp__} and the 4539function or variable name. 4540 4541You can use @code{__declspec(dllimport)} as a synonym for 4542@code{__attribute__ ((dllimport))} for compatibility with other 4543compilers. 4544 4545On systems that support the @code{visibility} attribute, this 4546attribute also implies ``default'' visibility. It is an error to 4547explicitly specify any other visibility. 4548 4549Currently, the attribute is ignored for inlined functions. If the 4550attribute is applied to a symbol @emph{definition}, an error is reported. 4551If a symbol previously declared @code{dllimport} is later defined, the 4552attribute is ignored in subsequent references, and a warning is emitted. 4553The attribute is also overridden by a subsequent declaration as 4554@code{dllexport}. 4555 4556When applied to C++ classes, the attribute marks non-inlined 4557member functions and static data members as imports. However, the 4558attribute is ignored for virtual methods to allow creation of vtables 4559using thunks. 4560 4561On the SH Symbian OS target the @code{dllimport} attribute also has 4562another affect---it can cause the vtable and run-time type information 4563for a class to be exported. This happens when the class has a 4564dllimported constructor or a non-inline, non-pure virtual function 4565and, for either of those two conditions, the class also has an inline 4566constructor or destructor and has a key function that is defined in 4567the current translation unit. 4568 4569For Microsoft Windows targets the use of the @code{dllimport} 4570attribute on functions is not necessary, but provides a small 4571performance benefit by eliminating a thunk in the DLL@. The use of the 4572@code{dllimport} attribute on imported variables can be avoided by passing the 4573@option{--enable-auto-import} switch to the GNU linker. As with 4574functions, using the attribute for a variable eliminates a thunk in 4575the DLL@. 4576 4577One drawback to using this attribute is that a pointer to a 4578@emph{variable} marked as @code{dllimport} cannot be used as a constant 4579address. However, a pointer to a @emph{function} with the 4580@code{dllimport} attribute can be used as a constant initializer; in 4581this case, the address of a stub function in the import lib is 4582referenced. On Microsoft Windows targets, the attribute can be disabled 4583for functions by setting the @option{-mnop-fun-dllimport} flag. 4584@end table 4585 4586@node MIPS Function Attributes 4587@subsection MIPS Function Attributes 4588 4589These function attributes are supported by the MIPS back end: 4590 4591@table @code 4592@item interrupt 4593@cindex @code{interrupt} function attribute, MIPS 4594Use this attribute to indicate that the specified function is an interrupt 4595handler. The compiler generates function entry and exit sequences suitable 4596for use in an interrupt handler when this attribute is present. 4597An optional argument is supported for the interrupt attribute which allows 4598the interrupt mode to be described. By default GCC assumes the external 4599interrupt controller (EIC) mode is in use, this can be explicitly set using 4600@code{eic}. When interrupts are non-masked then the requested Interrupt 4601Priority Level (IPL) is copied to the current IPL which has the effect of only 4602enabling higher priority interrupts. To use vectored interrupt mode use 4603the argument @code{vector=[sw0|sw1|hw0|hw1|hw2|hw3|hw4|hw5]}, this will change 4604the behavior of the non-masked interrupt support and GCC will arrange to mask 4605all interrupts from sw0 up to and including the specified interrupt vector. 4606 4607You can use the following attributes to modify the behavior 4608of an interrupt handler: 4609@table @code 4610@item use_shadow_register_set 4611@cindex @code{use_shadow_register_set} function attribute, MIPS 4612Assume that the handler uses a shadow register set, instead of 4613the main general-purpose registers. An optional argument @code{intstack} is 4614supported to indicate that the shadow register set contains a valid stack 4615pointer. 4616 4617@item keep_interrupts_masked 4618@cindex @code{keep_interrupts_masked} function attribute, MIPS 4619Keep interrupts masked for the whole function. Without this attribute, 4620GCC tries to reenable interrupts for as much of the function as it can. 4621 4622@item use_debug_exception_return 4623@cindex @code{use_debug_exception_return} function attribute, MIPS 4624Return using the @code{deret} instruction. Interrupt handlers that don't 4625have this attribute return using @code{eret} instead. 4626@end table 4627 4628You can use any combination of these attributes, as shown below: 4629@smallexample 4630void __attribute__ ((interrupt)) v0 (); 4631void __attribute__ ((interrupt, use_shadow_register_set)) v1 (); 4632void __attribute__ ((interrupt, keep_interrupts_masked)) v2 (); 4633void __attribute__ ((interrupt, use_debug_exception_return)) v3 (); 4634void __attribute__ ((interrupt, use_shadow_register_set, 4635 keep_interrupts_masked)) v4 (); 4636void __attribute__ ((interrupt, use_shadow_register_set, 4637 use_debug_exception_return)) v5 (); 4638void __attribute__ ((interrupt, keep_interrupts_masked, 4639 use_debug_exception_return)) v6 (); 4640void __attribute__ ((interrupt, use_shadow_register_set, 4641 keep_interrupts_masked, 4642 use_debug_exception_return)) v7 (); 4643void __attribute__ ((interrupt("eic"))) v8 (); 4644void __attribute__ ((interrupt("vector=hw3"))) v9 (); 4645@end smallexample 4646 4647@item long_call 4648@itemx short_call 4649@itemx near 4650@itemx far 4651@cindex indirect calls, MIPS 4652@cindex @code{long_call} function attribute, MIPS 4653@cindex @code{short_call} function attribute, MIPS 4654@cindex @code{near} function attribute, MIPS 4655@cindex @code{far} function attribute, MIPS 4656These attributes specify how a particular function is called on MIPS@. 4657The attributes override the @option{-mlong-calls} (@pxref{MIPS Options}) 4658command-line switch. The @code{long_call} and @code{far} attributes are 4659synonyms, and cause the compiler to always call 4660the function by first loading its address into a register, and then using 4661the contents of that register. The @code{short_call} and @code{near} 4662attributes are synonyms, and have the opposite 4663effect; they specify that non-PIC calls should be made using the more 4664efficient @code{jal} instruction. 4665 4666@item mips16 4667@itemx nomips16 4668@cindex @code{mips16} function attribute, MIPS 4669@cindex @code{nomips16} function attribute, MIPS 4670 4671On MIPS targets, you can use the @code{mips16} and @code{nomips16} 4672function attributes to locally select or turn off MIPS16 code generation. 4673A function with the @code{mips16} attribute is emitted as MIPS16 code, 4674while MIPS16 code generation is disabled for functions with the 4675@code{nomips16} attribute. These attributes override the 4676@option{-mips16} and @option{-mno-mips16} options on the command line 4677(@pxref{MIPS Options}). 4678 4679When compiling files containing mixed MIPS16 and non-MIPS16 code, the 4680preprocessor symbol @code{__mips16} reflects the setting on the command line, 4681not that within individual functions. Mixed MIPS16 and non-MIPS16 code 4682may interact badly with some GCC extensions such as @code{__builtin_apply} 4683(@pxref{Constructing Calls}). 4684 4685@item micromips, MIPS 4686@itemx nomicromips, MIPS 4687@cindex @code{micromips} function attribute 4688@cindex @code{nomicromips} function attribute 4689 4690On MIPS targets, you can use the @code{micromips} and @code{nomicromips} 4691function attributes to locally select or turn off microMIPS code generation. 4692A function with the @code{micromips} attribute is emitted as microMIPS code, 4693while microMIPS code generation is disabled for functions with the 4694@code{nomicromips} attribute. These attributes override the 4695@option{-mmicromips} and @option{-mno-micromips} options on the command line 4696(@pxref{MIPS Options}). 4697 4698When compiling files containing mixed microMIPS and non-microMIPS code, the 4699preprocessor symbol @code{__mips_micromips} reflects the setting on the 4700command line, 4701not that within individual functions. Mixed microMIPS and non-microMIPS code 4702may interact badly with some GCC extensions such as @code{__builtin_apply} 4703(@pxref{Constructing Calls}). 4704 4705@item nocompression 4706@cindex @code{nocompression} function attribute, MIPS 4707On MIPS targets, you can use the @code{nocompression} function attribute 4708to locally turn off MIPS16 and microMIPS code generation. This attribute 4709overrides the @option{-mips16} and @option{-mmicromips} options on the 4710command line (@pxref{MIPS Options}). 4711@end table 4712 4713@node MSP430 Function Attributes 4714@subsection MSP430 Function Attributes 4715 4716These function attributes are supported by the MSP430 back end: 4717 4718@table @code 4719@item critical 4720@cindex @code{critical} function attribute, MSP430 4721Critical functions disable interrupts upon entry and restore the 4722previous interrupt state upon exit. Critical functions cannot also 4723have the @code{naked} or @code{reentrant} attributes. They can have 4724the @code{interrupt} attribute. 4725 4726@item interrupt 4727@cindex @code{interrupt} function attribute, MSP430 4728Use this attribute to indicate 4729that the specified function is an interrupt handler. The compiler generates 4730function entry and exit sequences suitable for use in an interrupt handler 4731when this attribute is present. 4732 4733You can provide an argument to the interrupt 4734attribute which specifies a name or number. If the argument is a 4735number it indicates the slot in the interrupt vector table (0 - 31) to 4736which this handler should be assigned. If the argument is a name it 4737is treated as a symbolic name for the vector slot. These names should 4738match up with appropriate entries in the linker script. By default 4739the names @code{watchdog} for vector 26, @code{nmi} for vector 30 and 4740@code{reset} for vector 31 are recognized. 4741 4742@item naked 4743@cindex @code{naked} function attribute, MSP430 4744This attribute allows the compiler to construct the 4745requisite function declaration, while allowing the body of the 4746function to be assembly code. The specified function will not have 4747prologue/epilogue sequences generated by the compiler. Only basic 4748@code{asm} statements can safely be included in naked functions 4749(@pxref{Basic Asm}). While using extended @code{asm} or a mixture of 4750basic @code{asm} and C code may appear to work, they cannot be 4751depended upon to work reliably and are not supported. 4752 4753@item reentrant 4754@cindex @code{reentrant} function attribute, MSP430 4755Reentrant functions disable interrupts upon entry and enable them 4756upon exit. Reentrant functions cannot also have the @code{naked} 4757or @code{critical} attributes. They can have the @code{interrupt} 4758attribute. 4759 4760@item wakeup 4761@cindex @code{wakeup} function attribute, MSP430 4762This attribute only applies to interrupt functions. It is silently 4763ignored if applied to a non-interrupt function. A wakeup interrupt 4764function will rouse the processor from any low-power state that it 4765might be in when the function exits. 4766 4767@item lower 4768@itemx upper 4769@itemx either 4770@cindex @code{lower} function attribute, MSP430 4771@cindex @code{upper} function attribute, MSP430 4772@cindex @code{either} function attribute, MSP430 4773On the MSP430 target these attributes can be used to specify whether 4774the function or variable should be placed into low memory, high 4775memory, or the placement should be left to the linker to decide. The 4776attributes are only significant if compiling for the MSP430X 4777architecture. 4778 4779The attributes work in conjunction with a linker script that has been 4780augmented to specify where to place sections with a @code{.lower} and 4781a @code{.upper} prefix. So, for example, as well as placing the 4782@code{.data} section, the script also specifies the placement of a 4783@code{.lower.data} and a @code{.upper.data} section. The intention 4784is that @code{lower} sections are placed into a small but easier to 4785access memory region and the upper sections are placed into a larger, but 4786slower to access, region. 4787 4788The @code{either} attribute is special. It tells the linker to place 4789the object into the corresponding @code{lower} section if there is 4790room for it. If there is insufficient room then the object is placed 4791into the corresponding @code{upper} section instead. Note that the 4792placement algorithm is not very sophisticated. It does not attempt to 4793find an optimal packing of the @code{lower} sections. It just makes 4794one pass over the objects and does the best that it can. Using the 4795@option{-ffunction-sections} and @option{-fdata-sections} command-line 4796options can help the packing, however, since they produce smaller, 4797easier to pack regions. 4798@end table 4799 4800@node NDS32 Function Attributes 4801@subsection NDS32 Function Attributes 4802 4803These function attributes are supported by the NDS32 back end: 4804 4805@table @code 4806@item exception 4807@cindex @code{exception} function attribute 4808@cindex exception handler functions, NDS32 4809Use this attribute on the NDS32 target to indicate that the specified function 4810is an exception handler. The compiler will generate corresponding sections 4811for use in an exception handler. 4812 4813@item interrupt 4814@cindex @code{interrupt} function attribute, NDS32 4815On NDS32 target, this attribute indicates that the specified function 4816is an interrupt handler. The compiler generates corresponding sections 4817for use in an interrupt handler. You can use the following attributes 4818to modify the behavior: 4819@table @code 4820@item nested 4821@cindex @code{nested} function attribute, NDS32 4822This interrupt service routine is interruptible. 4823@item not_nested 4824@cindex @code{not_nested} function attribute, NDS32 4825This interrupt service routine is not interruptible. 4826@item nested_ready 4827@cindex @code{nested_ready} function attribute, NDS32 4828This interrupt service routine is interruptible after @code{PSW.GIE} 4829(global interrupt enable) is set. This allows interrupt service routine to 4830finish some short critical code before enabling interrupts. 4831@item save_all 4832@cindex @code{save_all} function attribute, NDS32 4833The system will help save all registers into stack before entering 4834interrupt handler. 4835@item partial_save 4836@cindex @code{partial_save} function attribute, NDS32 4837The system will help save caller registers into stack before entering 4838interrupt handler. 4839@end table 4840 4841@item naked 4842@cindex @code{naked} function attribute, NDS32 4843This attribute allows the compiler to construct the 4844requisite function declaration, while allowing the body of the 4845function to be assembly code. The specified function will not have 4846prologue/epilogue sequences generated by the compiler. Only basic 4847@code{asm} statements can safely be included in naked functions 4848(@pxref{Basic Asm}). While using extended @code{asm} or a mixture of 4849basic @code{asm} and C code may appear to work, they cannot be 4850depended upon to work reliably and are not supported. 4851 4852@item reset 4853@cindex @code{reset} function attribute, NDS32 4854@cindex reset handler functions 4855Use this attribute on the NDS32 target to indicate that the specified function 4856is a reset handler. The compiler will generate corresponding sections 4857for use in a reset handler. You can use the following attributes 4858to provide extra exception handling: 4859@table @code 4860@item nmi 4861@cindex @code{nmi} function attribute, NDS32 4862Provide a user-defined function to handle NMI exception. 4863@item warm 4864@cindex @code{warm} function attribute, NDS32 4865Provide a user-defined function to handle warm reset exception. 4866@end table 4867@end table 4868 4869@node Nios II Function Attributes 4870@subsection Nios II Function Attributes 4871 4872These function attributes are supported by the Nios II back end: 4873 4874@table @code 4875@item target (@var{options}) 4876@cindex @code{target} function attribute 4877As discussed in @ref{Common Function Attributes}, this attribute 4878allows specification of target-specific compilation options. 4879 4880When compiling for Nios II, the following options are allowed: 4881 4882@table @samp 4883@item custom-@var{insn}=@var{N} 4884@itemx no-custom-@var{insn} 4885@cindex @code{target("custom-@var{insn}=@var{N}")} function attribute, Nios II 4886@cindex @code{target("no-custom-@var{insn}")} function attribute, Nios II 4887Each @samp{custom-@var{insn}=@var{N}} attribute locally enables use of a 4888custom instruction with encoding @var{N} when generating code that uses 4889@var{insn}. Similarly, @samp{no-custom-@var{insn}} locally inhibits use of 4890the custom instruction @var{insn}. 4891These target attributes correspond to the 4892@option{-mcustom-@var{insn}=@var{N}} and @option{-mno-custom-@var{insn}} 4893command-line options, and support the same set of @var{insn} keywords. 4894@xref{Nios II Options}, for more information. 4895 4896@item custom-fpu-cfg=@var{name} 4897@cindex @code{target("custom-fpu-cfg=@var{name}")} function attribute, Nios II 4898This attribute corresponds to the @option{-mcustom-fpu-cfg=@var{name}} 4899command-line option, to select a predefined set of custom instructions 4900named @var{name}. 4901@xref{Nios II Options}, for more information. 4902@end table 4903@end table 4904 4905@node Nvidia PTX Function Attributes 4906@subsection Nvidia PTX Function Attributes 4907 4908These function attributes are supported by the Nvidia PTX back end: 4909 4910@table @code 4911@item kernel 4912@cindex @code{kernel} attribute, Nvidia PTX 4913This attribute indicates that the corresponding function should be compiled 4914as a kernel function, which can be invoked from the host via the CUDA RT 4915library. 4916By default functions are only callable only from other PTX functions. 4917 4918Kernel functions must have @code{void} return type. 4919@end table 4920 4921@node PowerPC Function Attributes 4922@subsection PowerPC Function Attributes 4923 4924These function attributes are supported by the PowerPC back end: 4925 4926@table @code 4927@item longcall 4928@itemx shortcall 4929@cindex indirect calls, PowerPC 4930@cindex @code{longcall} function attribute, PowerPC 4931@cindex @code{shortcall} function attribute, PowerPC 4932The @code{longcall} attribute 4933indicates that the function might be far away from the call site and 4934require a different (more expensive) calling sequence. The 4935@code{shortcall} attribute indicates that the function is always close 4936enough for the shorter calling sequence to be used. These attributes 4937override both the @option{-mlongcall} switch and 4938the @code{#pragma longcall} setting. 4939 4940@xref{RS/6000 and PowerPC Options}, for more information on whether long 4941calls are necessary. 4942 4943@item target (@var{options}) 4944@cindex @code{target} function attribute 4945As discussed in @ref{Common Function Attributes}, this attribute 4946allows specification of target-specific compilation options. 4947 4948On the PowerPC, the following options are allowed: 4949 4950@table @samp 4951@item altivec 4952@itemx no-altivec 4953@cindex @code{target("altivec")} function attribute, PowerPC 4954Generate code that uses (does not use) AltiVec instructions. In 495532-bit code, you cannot enable AltiVec instructions unless 4956@option{-mabi=altivec} is used on the command line. 4957 4958@item cmpb 4959@itemx no-cmpb 4960@cindex @code{target("cmpb")} function attribute, PowerPC 4961Generate code that uses (does not use) the compare bytes instruction 4962implemented on the POWER6 processor and other processors that support 4963the PowerPC V2.05 architecture. 4964 4965@item dlmzb 4966@itemx no-dlmzb 4967@cindex @code{target("dlmzb")} function attribute, PowerPC 4968Generate code that uses (does not use) the string-search @samp{dlmzb} 4969instruction on the IBM 405, 440, 464 and 476 processors. This instruction is 4970generated by default when targeting those processors. 4971 4972@item fprnd 4973@itemx no-fprnd 4974@cindex @code{target("fprnd")} function attribute, PowerPC 4975Generate code that uses (does not use) the FP round to integer 4976instructions implemented on the POWER5+ processor and other processors 4977that support the PowerPC V2.03 architecture. 4978 4979@item hard-dfp 4980@itemx no-hard-dfp 4981@cindex @code{target("hard-dfp")} function attribute, PowerPC 4982Generate code that uses (does not use) the decimal floating-point 4983instructions implemented on some POWER processors. 4984 4985@item isel 4986@itemx no-isel 4987@cindex @code{target("isel")} function attribute, PowerPC 4988Generate code that uses (does not use) ISEL instruction. 4989 4990@item mfcrf 4991@itemx no-mfcrf 4992@cindex @code{target("mfcrf")} function attribute, PowerPC 4993Generate code that uses (does not use) the move from condition 4994register field instruction implemented on the POWER4 processor and 4995other processors that support the PowerPC V2.01 architecture. 4996 4997@item mfpgpr 4998@itemx no-mfpgpr 4999@cindex @code{target("mfpgpr")} function attribute, PowerPC 5000Generate code that uses (does not use) the FP move to/from general 5001purpose register instructions implemented on the POWER6X processor and 5002other processors that support the extended PowerPC V2.05 architecture. 5003 5004@item mulhw 5005@itemx no-mulhw 5006@cindex @code{target("mulhw")} function attribute, PowerPC 5007Generate code that uses (does not use) the half-word multiply and 5008multiply-accumulate instructions on the IBM 405, 440, 464 and 476 processors. 5009These instructions are generated by default when targeting those 5010processors. 5011 5012@item multiple 5013@itemx no-multiple 5014@cindex @code{target("multiple")} function attribute, PowerPC 5015Generate code that uses (does not use) the load multiple word 5016instructions and the store multiple word instructions. 5017 5018@item update 5019@itemx no-update 5020@cindex @code{target("update")} function attribute, PowerPC 5021Generate code that uses (does not use) the load or store instructions 5022that update the base register to the address of the calculated memory 5023location. 5024 5025@item popcntb 5026@itemx no-popcntb 5027@cindex @code{target("popcntb")} function attribute, PowerPC 5028Generate code that uses (does not use) the popcount and double-precision 5029FP reciprocal estimate instruction implemented on the POWER5 5030processor and other processors that support the PowerPC V2.02 5031architecture. 5032 5033@item popcntd 5034@itemx no-popcntd 5035@cindex @code{target("popcntd")} function attribute, PowerPC 5036Generate code that uses (does not use) the popcount instruction 5037implemented on the POWER7 processor and other processors that support 5038the PowerPC V2.06 architecture. 5039 5040@item powerpc-gfxopt 5041@itemx no-powerpc-gfxopt 5042@cindex @code{target("powerpc-gfxopt")} function attribute, PowerPC 5043Generate code that uses (does not use) the optional PowerPC 5044architecture instructions in the Graphics group, including 5045floating-point select. 5046 5047@item powerpc-gpopt 5048@itemx no-powerpc-gpopt 5049@cindex @code{target("powerpc-gpopt")} function attribute, PowerPC 5050Generate code that uses (does not use) the optional PowerPC 5051architecture instructions in the General Purpose group, including 5052floating-point square root. 5053 5054@item recip-precision 5055@itemx no-recip-precision 5056@cindex @code{target("recip-precision")} function attribute, PowerPC 5057Assume (do not assume) that the reciprocal estimate instructions 5058provide higher-precision estimates than is mandated by the PowerPC 5059ABI. 5060 5061@item string 5062@itemx no-string 5063@cindex @code{target("string")} function attribute, PowerPC 5064Generate code that uses (does not use) the load string instructions 5065and the store string word instructions to save multiple registers and 5066do small block moves. 5067 5068@item vsx 5069@itemx no-vsx 5070@cindex @code{target("vsx")} function attribute, PowerPC 5071Generate code that uses (does not use) vector/scalar (VSX) 5072instructions, and also enable the use of built-in functions that allow 5073more direct access to the VSX instruction set. In 32-bit code, you 5074cannot enable VSX or AltiVec instructions unless 5075@option{-mabi=altivec} is used on the command line. 5076 5077@item friz 5078@itemx no-friz 5079@cindex @code{target("friz")} function attribute, PowerPC 5080Generate (do not generate) the @code{friz} instruction when the 5081@option{-funsafe-math-optimizations} option is used to optimize 5082rounding a floating-point value to 64-bit integer and back to floating 5083point. The @code{friz} instruction does not return the same value if 5084the floating-point number is too large to fit in an integer. 5085 5086@item avoid-indexed-addresses 5087@itemx no-avoid-indexed-addresses 5088@cindex @code{target("avoid-indexed-addresses")} function attribute, PowerPC 5089Generate code that tries to avoid (not avoid) the use of indexed load 5090or store instructions. 5091 5092@item paired 5093@itemx no-paired 5094@cindex @code{target("paired")} function attribute, PowerPC 5095Generate code that uses (does not use) the generation of PAIRED simd 5096instructions. 5097 5098@item longcall 5099@itemx no-longcall 5100@cindex @code{target("longcall")} function attribute, PowerPC 5101Generate code that assumes (does not assume) that all calls are far 5102away so that a longer more expensive calling sequence is required. 5103 5104@item cpu=@var{CPU} 5105@cindex @code{target("cpu=@var{CPU}")} function attribute, PowerPC 5106Specify the architecture to generate code for when compiling the 5107function. If you select the @code{target("cpu=power7")} attribute when 5108generating 32-bit code, VSX and AltiVec instructions are not generated 5109unless you use the @option{-mabi=altivec} option on the command line. 5110 5111@item tune=@var{TUNE} 5112@cindex @code{target("tune=@var{TUNE}")} function attribute, PowerPC 5113Specify the architecture to tune for when compiling the function. If 5114you do not specify the @code{target("tune=@var{TUNE}")} attribute and 5115you do specify the @code{target("cpu=@var{CPU}")} attribute, 5116compilation tunes for the @var{CPU} architecture, and not the 5117default tuning specified on the command line. 5118@end table 5119 5120On the PowerPC, the inliner does not inline a 5121function that has different target options than the caller, unless the 5122callee has a subset of the target options of the caller. 5123@end table 5124 5125@node RISC-V Function Attributes 5126@subsection RISC-V Function Attributes 5127 5128These function attributes are supported by the RISC-V back end: 5129 5130@table @code 5131@item naked 5132@cindex @code{naked} function attribute, RISC-V 5133This attribute allows the compiler to construct the 5134requisite function declaration, while allowing the body of the 5135function to be assembly code. The specified function will not have 5136prologue/epilogue sequences generated by the compiler. Only basic 5137@code{asm} statements can safely be included in naked functions 5138(@pxref{Basic Asm}). While using extended @code{asm} or a mixture of 5139basic @code{asm} and C code may appear to work, they cannot be 5140depended upon to work reliably and are not supported. 5141@end table 5142 5143@node RL78 Function Attributes 5144@subsection RL78 Function Attributes 5145 5146These function attributes are supported by the RL78 back end: 5147 5148@table @code 5149@item interrupt 5150@itemx brk_interrupt 5151@cindex @code{interrupt} function attribute, RL78 5152@cindex @code{brk_interrupt} function attribute, RL78 5153These attributes indicate 5154that the specified function is an interrupt handler. The compiler generates 5155function entry and exit sequences suitable for use in an interrupt handler 5156when this attribute is present. 5157 5158Use @code{brk_interrupt} instead of @code{interrupt} for 5159handlers intended to be used with the @code{BRK} opcode (i.e.@: those 5160that must end with @code{RETB} instead of @code{RETI}). 5161 5162@item naked 5163@cindex @code{naked} function attribute, RL78 5164This attribute allows the compiler to construct the 5165requisite function declaration, while allowing the body of the 5166function to be assembly code. The specified function will not have 5167prologue/epilogue sequences generated by the compiler. Only basic 5168@code{asm} statements can safely be included in naked functions 5169(@pxref{Basic Asm}). While using extended @code{asm} or a mixture of 5170basic @code{asm} and C code may appear to work, they cannot be 5171depended upon to work reliably and are not supported. 5172@end table 5173 5174@node RX Function Attributes 5175@subsection RX Function Attributes 5176 5177These function attributes are supported by the RX back end: 5178 5179@table @code 5180@item fast_interrupt 5181@cindex @code{fast_interrupt} function attribute, RX 5182Use this attribute on the RX port to indicate that the specified 5183function is a fast interrupt handler. This is just like the 5184@code{interrupt} attribute, except that @code{freit} is used to return 5185instead of @code{reit}. 5186 5187@item interrupt 5188@cindex @code{interrupt} function attribute, RX 5189Use this attribute to indicate 5190that the specified function is an interrupt handler. The compiler generates 5191function entry and exit sequences suitable for use in an interrupt handler 5192when this attribute is present. 5193 5194On RX and RL78 targets, you may specify one or more vector numbers as arguments 5195to the attribute, as well as naming an alternate table name. 5196Parameters are handled sequentially, so one handler can be assigned to 5197multiple entries in multiple tables. One may also pass the magic 5198string @code{"$default"} which causes the function to be used for any 5199unfilled slots in the current table. 5200 5201This example shows a simple assignment of a function to one vector in 5202the default table (note that preprocessor macros may be used for 5203chip-specific symbolic vector names): 5204@smallexample 5205void __attribute__ ((interrupt (5))) txd1_handler (); 5206@end smallexample 5207 5208This example assigns a function to two slots in the default table 5209(using preprocessor macros defined elsewhere) and makes it the default 5210for the @code{dct} table: 5211@smallexample 5212void __attribute__ ((interrupt (RXD1_VECT,RXD2_VECT,"dct","$default"))) 5213 txd1_handler (); 5214@end smallexample 5215 5216@item naked 5217@cindex @code{naked} function attribute, RX 5218This attribute allows the compiler to construct the 5219requisite function declaration, while allowing the body of the 5220function to be assembly code. The specified function will not have 5221prologue/epilogue sequences generated by the compiler. Only basic 5222@code{asm} statements can safely be included in naked functions 5223(@pxref{Basic Asm}). While using extended @code{asm} or a mixture of 5224basic @code{asm} and C code may appear to work, they cannot be 5225depended upon to work reliably and are not supported. 5226 5227@item vector 5228@cindex @code{vector} function attribute, RX 5229This RX attribute is similar to the @code{interrupt} attribute, including its 5230parameters, but does not make the function an interrupt-handler type 5231function (i.e. it retains the normal C function calling ABI). See the 5232@code{interrupt} attribute for a description of its arguments. 5233@end table 5234 5235@node S/390 Function Attributes 5236@subsection S/390 Function Attributes 5237 5238These function attributes are supported on the S/390: 5239 5240@table @code 5241@item hotpatch (@var{halfwords-before-function-label},@var{halfwords-after-function-label}) 5242@cindex @code{hotpatch} function attribute, S/390 5243 5244On S/390 System z targets, you can use this function attribute to 5245make GCC generate a ``hot-patching'' function prologue. If the 5246@option{-mhotpatch=} command-line option is used at the same time, 5247the @code{hotpatch} attribute takes precedence. The first of the 5248two arguments specifies the number of halfwords to be added before 5249the function label. A second argument can be used to specify the 5250number of halfwords to be added after the function label. For 5251both arguments the maximum allowed value is 1000000. 5252 5253If both arguments are zero, hotpatching is disabled. 5254 5255@item target (@var{options}) 5256@cindex @code{target} function attribute 5257As discussed in @ref{Common Function Attributes}, this attribute 5258allows specification of target-specific compilation options. 5259 5260On S/390, the following options are supported: 5261 5262@table @samp 5263@item arch= 5264@item tune= 5265@item stack-guard= 5266@item stack-size= 5267@item branch-cost= 5268@item warn-framesize= 5269@item backchain 5270@itemx no-backchain 5271@item hard-dfp 5272@itemx no-hard-dfp 5273@item hard-float 5274@itemx soft-float 5275@item htm 5276@itemx no-htm 5277@item vx 5278@itemx no-vx 5279@item packed-stack 5280@itemx no-packed-stack 5281@item small-exec 5282@itemx no-small-exec 5283@item mvcle 5284@itemx no-mvcle 5285@item warn-dynamicstack 5286@itemx no-warn-dynamicstack 5287@end table 5288 5289The options work exactly like the S/390 specific command line 5290options (without the prefix @option{-m}) except that they do not 5291change any feature macros. For example, 5292 5293@smallexample 5294@code{target("no-vx")} 5295@end smallexample 5296 5297does not undefine the @code{__VEC__} macro. 5298@end table 5299 5300@node SH Function Attributes 5301@subsection SH Function Attributes 5302 5303These function attributes are supported on the SH family of processors: 5304 5305@table @code 5306@item function_vector 5307@cindex @code{function_vector} function attribute, SH 5308@cindex calling functions through the function vector on SH2A 5309On SH2A targets, this attribute declares a function to be called using the 5310TBR relative addressing mode. The argument to this attribute is the entry 5311number of the same function in a vector table containing all the TBR 5312relative addressable functions. For correct operation the TBR must be setup 5313accordingly to point to the start of the vector table before any functions with 5314this attribute are invoked. Usually a good place to do the initialization is 5315the startup routine. The TBR relative vector table can have at max 256 function 5316entries. The jumps to these functions are generated using a SH2A specific, 5317non delayed branch instruction JSR/N @@(disp8,TBR). You must use GAS and GLD 5318from GNU binutils version 2.7 or later for this attribute to work correctly. 5319 5320In an application, for a function being called once, this attribute 5321saves at least 8 bytes of code; and if other successive calls are being 5322made to the same function, it saves 2 bytes of code per each of these 5323calls. 5324 5325@item interrupt_handler 5326@cindex @code{interrupt_handler} function attribute, SH 5327Use this attribute to 5328indicate that the specified function is an interrupt handler. The compiler 5329generates function entry and exit sequences suitable for use in an 5330interrupt handler when this attribute is present. 5331 5332@item nosave_low_regs 5333@cindex @code{nosave_low_regs} function attribute, SH 5334Use this attribute on SH targets to indicate that an @code{interrupt_handler} 5335function should not save and restore registers R0..R7. This can be used on SH3* 5336and SH4* targets that have a second R0..R7 register bank for non-reentrant 5337interrupt handlers. 5338 5339@item renesas 5340@cindex @code{renesas} function attribute, SH 5341On SH targets this attribute specifies that the function or struct follows the 5342Renesas ABI. 5343 5344@item resbank 5345@cindex @code{resbank} function attribute, SH 5346On the SH2A target, this attribute enables the high-speed register 5347saving and restoration using a register bank for @code{interrupt_handler} 5348routines. Saving to the bank is performed automatically after the CPU 5349accepts an interrupt that uses a register bank. 5350 5351The nineteen 32-bit registers comprising general register R0 to R14, 5352control register GBR, and system registers MACH, MACL, and PR and the 5353vector table address offset are saved into a register bank. Register 5354banks are stacked in first-in last-out (FILO) sequence. Restoration 5355from the bank is executed by issuing a RESBANK instruction. 5356 5357@item sp_switch 5358@cindex @code{sp_switch} function attribute, SH 5359Use this attribute on the SH to indicate an @code{interrupt_handler} 5360function should switch to an alternate stack. It expects a string 5361argument that names a global variable holding the address of the 5362alternate stack. 5363 5364@smallexample 5365void *alt_stack; 5366void f () __attribute__ ((interrupt_handler, 5367 sp_switch ("alt_stack"))); 5368@end smallexample 5369 5370@item trap_exit 5371@cindex @code{trap_exit} function attribute, SH 5372Use this attribute on the SH for an @code{interrupt_handler} to return using 5373@code{trapa} instead of @code{rte}. This attribute expects an integer 5374argument specifying the trap number to be used. 5375 5376@item trapa_handler 5377@cindex @code{trapa_handler} function attribute, SH 5378On SH targets this function attribute is similar to @code{interrupt_handler} 5379but it does not save and restore all registers. 5380@end table 5381 5382@node SPU Function Attributes 5383@subsection SPU Function Attributes 5384 5385These function attributes are supported by the SPU back end: 5386 5387@table @code 5388@item naked 5389@cindex @code{naked} function attribute, SPU 5390This attribute allows the compiler to construct the 5391requisite function declaration, while allowing the body of the 5392function to be assembly code. The specified function will not have 5393prologue/epilogue sequences generated by the compiler. Only basic 5394@code{asm} statements can safely be included in naked functions 5395(@pxref{Basic Asm}). While using extended @code{asm} or a mixture of 5396basic @code{asm} and C code may appear to work, they cannot be 5397depended upon to work reliably and are not supported. 5398@end table 5399 5400@node Symbian OS Function Attributes 5401@subsection Symbian OS Function Attributes 5402 5403@xref{Microsoft Windows Function Attributes}, for discussion of the 5404@code{dllexport} and @code{dllimport} attributes. 5405 5406@node V850 Function Attributes 5407@subsection V850 Function Attributes 5408 5409The V850 back end supports these function attributes: 5410 5411@table @code 5412@item interrupt 5413@itemx interrupt_handler 5414@cindex @code{interrupt} function attribute, V850 5415@cindex @code{interrupt_handler} function attribute, V850 5416Use these attributes to indicate 5417that the specified function is an interrupt handler. The compiler generates 5418function entry and exit sequences suitable for use in an interrupt handler 5419when either attribute is present. 5420@end table 5421 5422@node Visium Function Attributes 5423@subsection Visium Function Attributes 5424 5425These function attributes are supported by the Visium back end: 5426 5427@table @code 5428@item interrupt 5429@cindex @code{interrupt} function attribute, Visium 5430Use this attribute to indicate 5431that the specified function is an interrupt handler. The compiler generates 5432function entry and exit sequences suitable for use in an interrupt handler 5433when this attribute is present. 5434@end table 5435 5436@node x86 Function Attributes 5437@subsection x86 Function Attributes 5438 5439These function attributes are supported by the x86 back end: 5440 5441@table @code 5442@item cdecl 5443@cindex @code{cdecl} function attribute, x86-32 5444@cindex functions that pop the argument stack on x86-32 5445@opindex mrtd 5446On the x86-32 targets, the @code{cdecl} attribute causes the compiler to 5447assume that the calling function pops off the stack space used to 5448pass arguments. This is 5449useful to override the effects of the @option{-mrtd} switch. 5450 5451@item fastcall 5452@cindex @code{fastcall} function attribute, x86-32 5453@cindex functions that pop the argument stack on x86-32 5454On x86-32 targets, the @code{fastcall} attribute causes the compiler to 5455pass the first argument (if of integral type) in the register ECX and 5456the second argument (if of integral type) in the register EDX@. Subsequent 5457and other typed arguments are passed on the stack. The called function 5458pops the arguments off the stack. If the number of arguments is variable all 5459arguments are pushed on the stack. 5460 5461@item thiscall 5462@cindex @code{thiscall} function attribute, x86-32 5463@cindex functions that pop the argument stack on x86-32 5464On x86-32 targets, the @code{thiscall} attribute causes the compiler to 5465pass the first argument (if of integral type) in the register ECX. 5466Subsequent and other typed arguments are passed on the stack. The called 5467function pops the arguments off the stack. 5468If the number of arguments is variable all arguments are pushed on the 5469stack. 5470The @code{thiscall} attribute is intended for C++ non-static member functions. 5471As a GCC extension, this calling convention can be used for C functions 5472and for static member methods. 5473 5474@item ms_abi 5475@itemx sysv_abi 5476@cindex @code{ms_abi} function attribute, x86 5477@cindex @code{sysv_abi} function attribute, x86 5478 5479On 32-bit and 64-bit x86 targets, you can use an ABI attribute 5480to indicate which calling convention should be used for a function. The 5481@code{ms_abi} attribute tells the compiler to use the Microsoft ABI, 5482while the @code{sysv_abi} attribute tells the compiler to use the ABI 5483used on GNU/Linux and other systems. The default is to use the Microsoft ABI 5484when targeting Windows. On all other systems, the default is the x86/AMD ABI. 5485 5486Note, the @code{ms_abi} attribute for Microsoft Windows 64-bit targets currently 5487requires the @option{-maccumulate-outgoing-args} option. 5488 5489@item callee_pop_aggregate_return (@var{number}) 5490@cindex @code{callee_pop_aggregate_return} function attribute, x86 5491 5492On x86-32 targets, you can use this attribute to control how 5493aggregates are returned in memory. If the caller is responsible for 5494popping the hidden pointer together with the rest of the arguments, specify 5495@var{number} equal to zero. If callee is responsible for popping the 5496hidden pointer, specify @var{number} equal to one. 5497 5498The default x86-32 ABI assumes that the callee pops the 5499stack for hidden pointer. However, on x86-32 Microsoft Windows targets, 5500the compiler assumes that the 5501caller pops the stack for hidden pointer. 5502 5503@item ms_hook_prologue 5504@cindex @code{ms_hook_prologue} function attribute, x86 5505 5506On 32-bit and 64-bit x86 targets, you can use 5507this function attribute to make GCC generate the ``hot-patching'' function 5508prologue used in Win32 API functions in Microsoft Windows XP Service Pack 2 5509and newer. 5510 5511@item naked 5512@cindex @code{naked} function attribute, x86 5513This attribute allows the compiler to construct the 5514requisite function declaration, while allowing the body of the 5515function to be assembly code. The specified function will not have 5516prologue/epilogue sequences generated by the compiler. Only basic 5517@code{asm} statements can safely be included in naked functions 5518(@pxref{Basic Asm}). While using extended @code{asm} or a mixture of 5519basic @code{asm} and C code may appear to work, they cannot be 5520depended upon to work reliably and are not supported. 5521 5522@item regparm (@var{number}) 5523@cindex @code{regparm} function attribute, x86 5524@cindex functions that are passed arguments in registers on x86-32 5525On x86-32 targets, the @code{regparm} attribute causes the compiler to 5526pass arguments number one to @var{number} if they are of integral type 5527in registers EAX, EDX, and ECX instead of on the stack. Functions that 5528take a variable number of arguments continue to be passed all of their 5529arguments on the stack. 5530 5531Beware that on some ELF systems this attribute is unsuitable for 5532global functions in shared libraries with lazy binding (which is the 5533default). Lazy binding sends the first call via resolving code in 5534the loader, which might assume EAX, EDX and ECX can be clobbered, as 5535per the standard calling conventions. Solaris 8 is affected by this. 5536Systems with the GNU C Library version 2.1 or higher 5537and FreeBSD are believed to be 5538safe since the loaders there save EAX, EDX and ECX. (Lazy binding can be 5539disabled with the linker or the loader if desired, to avoid the 5540problem.) 5541 5542@item sseregparm 5543@cindex @code{sseregparm} function attribute, x86 5544On x86-32 targets with SSE support, the @code{sseregparm} attribute 5545causes the compiler to pass up to 3 floating-point arguments in 5546SSE registers instead of on the stack. Functions that take a 5547variable number of arguments continue to pass all of their 5548floating-point arguments on the stack. 5549 5550@item force_align_arg_pointer 5551@cindex @code{force_align_arg_pointer} function attribute, x86 5552On x86 targets, the @code{force_align_arg_pointer} attribute may be 5553applied to individual function definitions, generating an alternate 5554prologue and epilogue that realigns the run-time stack if necessary. 5555This supports mixing legacy codes that run with a 4-byte aligned stack 5556with modern codes that keep a 16-byte stack for SSE compatibility. 5557 5558@item stdcall 5559@cindex @code{stdcall} function attribute, x86-32 5560@cindex functions that pop the argument stack on x86-32 5561On x86-32 targets, the @code{stdcall} attribute causes the compiler to 5562assume that the called function pops off the stack space used to 5563pass arguments, unless it takes a variable number of arguments. 5564 5565@item no_caller_saved_registers 5566@cindex @code{no_caller_saved_registers} function attribute, x86 5567Use this attribute to indicate that the specified function has no 5568caller-saved registers. That is, all registers are callee-saved. For 5569example, this attribute can be used for a function called from an 5570interrupt handler. The compiler generates proper function entry and 5571exit sequences to save and restore any modified registers, except for 5572the EFLAGS register. Since GCC doesn't preserve MPX, SSE, MMX nor x87 5573states, the GCC option @option{-mgeneral-regs-only} should be used to 5574compile functions with @code{no_caller_saved_registers} attribute. 5575 5576@item interrupt 5577@cindex @code{interrupt} function attribute, x86 5578Use this attribute to indicate that the specified function is an 5579interrupt handler or an exception handler (depending on parameters passed 5580to the function, explained further). The compiler generates function 5581entry and exit sequences suitable for use in an interrupt handler when 5582this attribute is present. The @code{IRET} instruction, instead of the 5583@code{RET} instruction, is used to return from interrupt handlers. All 5584registers, except for the EFLAGS register which is restored by the 5585@code{IRET} instruction, are preserved by the compiler. Since GCC 5586doesn't preserve MPX, SSE, MMX nor x87 states, the GCC option 5587@option{-mgeneral-regs-only} should be used to compile interrupt and 5588exception handlers. 5589 5590Any interruptible-without-stack-switch code must be compiled with 5591@option{-mno-red-zone} since interrupt handlers can and will, because 5592of the hardware design, touch the red zone. 5593 5594An interrupt handler must be declared with a mandatory pointer 5595argument: 5596 5597@smallexample 5598struct interrupt_frame; 5599 5600__attribute__ ((interrupt)) 5601void 5602f (struct interrupt_frame *frame) 5603@{ 5604@} 5605@end smallexample 5606 5607@noindent 5608and you must define @code{struct interrupt_frame} as described in the 5609processor's manual. 5610 5611Exception handlers differ from interrupt handlers because the system 5612pushes an error code on the stack. An exception handler declaration is 5613similar to that for an interrupt handler, but with a different mandatory 5614function signature. The compiler arranges to pop the error code off the 5615stack before the @code{IRET} instruction. 5616 5617@smallexample 5618#ifdef __x86_64__ 5619typedef unsigned long long int uword_t; 5620#else 5621typedef unsigned int uword_t; 5622#endif 5623 5624struct interrupt_frame; 5625 5626__attribute__ ((interrupt)) 5627void 5628f (struct interrupt_frame *frame, uword_t error_code) 5629@{ 5630 ... 5631@} 5632@end smallexample 5633 5634Exception handlers should only be used for exceptions that push an error 5635code; you should use an interrupt handler in other cases. The system 5636will crash if the wrong kind of handler is used. 5637 5638@item target (@var{options}) 5639@cindex @code{target} function attribute 5640As discussed in @ref{Common Function Attributes}, this attribute 5641allows specification of target-specific compilation options. 5642 5643On the x86, the following options are allowed: 5644@table @samp 5645@item 3dnow 5646@itemx no-3dnow 5647@cindex @code{target("3dnow")} function attribute, x86 5648Enable/disable the generation of the 3DNow!@: instructions. 5649 5650@item 3dnowa 5651@itemx no-3dnowa 5652@cindex @code{target("3dnowa")} function attribute, x86 5653Enable/disable the generation of the enhanced 3DNow!@: instructions. 5654 5655@item abm 5656@itemx no-abm 5657@cindex @code{target("abm")} function attribute, x86 5658Enable/disable the generation of the advanced bit instructions. 5659 5660@item adx 5661@itemx no-adx 5662@cindex @code{target("adx")} function attribute, x86 5663Enable/disable the generation of the ADX instructions. 5664 5665@item aes 5666@itemx no-aes 5667@cindex @code{target("aes")} function attribute, x86 5668Enable/disable the generation of the AES instructions. 5669 5670@item avx 5671@itemx no-avx 5672@cindex @code{target("avx")} function attribute, x86 5673Enable/disable the generation of the AVX instructions. 5674 5675@item avx2 5676@itemx no-avx2 5677@cindex @code{target("avx2")} function attribute, x86 5678Enable/disable the generation of the AVX2 instructions. 5679 5680@item avx5124fmaps 5681@itemx no-avx5124fmaps 5682@cindex @code{target("avx5124fmaps")} function attribute, x86 5683Enable/disable the generation of the AVX5124FMAPS instructions. 5684 5685@item avx5124vnniw 5686@itemx no-avx5124vnniw 5687@cindex @code{target("avx5124vnniw")} function attribute, x86 5688Enable/disable the generation of the AVX5124VNNIW instructions. 5689 5690@item avx512bitalg 5691@itemx no-avx512bitalg 5692@cindex @code{target("avx512bitalg")} function attribute, x86 5693Enable/disable the generation of the AVX512BITALG instructions. 5694 5695@item avx512bw 5696@itemx no-avx512bw 5697@cindex @code{target("avx512bw")} function attribute, x86 5698Enable/disable the generation of the AVX512BW instructions. 5699 5700@item avx512cd 5701@itemx no-avx512cd 5702@cindex @code{target("avx512cd")} function attribute, x86 5703Enable/disable the generation of the AVX512CD instructions. 5704 5705@item avx512dq 5706@itemx no-avx512dq 5707@cindex @code{target("avx512dq")} function attribute, x86 5708Enable/disable the generation of the AVX512DQ instructions. 5709 5710@item avx512er 5711@itemx no-avx512er 5712@cindex @code{target("avx512er")} function attribute, x86 5713Enable/disable the generation of the AVX512ER instructions. 5714 5715@item avx512f 5716@itemx no-avx512f 5717@cindex @code{target("avx512f")} function attribute, x86 5718Enable/disable the generation of the AVX512F instructions. 5719 5720@item avx512ifma 5721@itemx no-avx512ifma 5722@cindex @code{target("avx512ifma")} function attribute, x86 5723Enable/disable the generation of the AVX512IFMA instructions. 5724 5725@item avx512pf 5726@itemx no-avx512pf 5727@cindex @code{target("avx512pf")} function attribute, x86 5728Enable/disable the generation of the AVX512PF instructions. 5729 5730@item avx512vbmi 5731@itemx no-avx512vbmi 5732@cindex @code{target("avx512vbmi")} function attribute, x86 5733Enable/disable the generation of the AVX512VBMI instructions. 5734 5735@item avx512vbmi2 5736@itemx no-avx512vbmi2 5737@cindex @code{target("avx512vbmi2")} function attribute, x86 5738Enable/disable the generation of the AVX512VBMI2 instructions. 5739 5740@item avx512vl 5741@itemx no-avx512vl 5742@cindex @code{target("avx512vl")} function attribute, x86 5743Enable/disable the generation of the AVX512VL instructions. 5744 5745@item avx512vnni 5746@itemx no-avx512vnni 5747@cindex @code{target("avx512vnni")} function attribute, x86 5748Enable/disable the generation of the AVX512VNNI instructions. 5749 5750@item avx512vpopcntdq 5751@itemx no-avx512vpopcntdq 5752@cindex @code{target("avx512vpopcntdq")} function attribute, x86 5753Enable/disable the generation of the AVX512VPOPCNTDQ instructions. 5754 5755@item bmi 5756@itemx no-bmi 5757@cindex @code{target("bmi")} function attribute, x86 5758Enable/disable the generation of the BMI instructions. 5759 5760@item bmi2 5761@itemx no-bmi2 5762@cindex @code{target("bmi2")} function attribute, x86 5763Enable/disable the generation of the BMI2 instructions. 5764 5765@item clflushopt 5766@itemx no-clflushopt 5767@cindex @code{target("clflushopt")} function attribute, x86 5768Enable/disable the generation of the CLFLUSHOPT instructions. 5769 5770@item clwb 5771@itemx no-clwb 5772@cindex @code{target("clwb")} function attribute, x86 5773Enable/disable the generation of the CLWB instructions. 5774 5775@item clzero 5776@itemx no-clzero 5777@cindex @code{target("clzero")} function attribute, x86 5778Enable/disable the generation of the CLZERO instructions. 5779 5780@item crc32 5781@itemx no-crc32 5782@cindex @code{target("crc32")} function attribute, x86 5783Enable/disable the generation of the CRC32 instructions. 5784 5785@item cx16 5786@itemx no-cx16 5787@cindex @code{target("cx16")} function attribute, x86 5788Enable/disable the generation of the CMPXCHG16B instructions. 5789 5790@item default 5791@cindex @code{target("default")} function attribute, x86 5792@xref{Function Multiversioning}, where it is used to specify the 5793default function version. 5794 5795@item f16c 5796@itemx no-f16c 5797@cindex @code{target("f16c")} function attribute, x86 5798Enable/disable the generation of the F16C instructions. 5799 5800@item fma 5801@itemx no-fma 5802@cindex @code{target("fma")} function attribute, x86 5803Enable/disable the generation of the FMA instructions. 5804 5805@item fma4 5806@itemx no-fma4 5807@cindex @code{target("fma4")} function attribute, x86 5808Enable/disable the generation of the FMA4 instructions. 5809 5810@item fsgsbase 5811@itemx no-fsgsbase 5812@cindex @code{target("fsgsbase")} function attribute, x86 5813Enable/disable the generation of the FSGSBASE instructions. 5814 5815@item fxsr 5816@itemx no-fxsr 5817@cindex @code{target("fxsr")} function attribute, x86 5818Enable/disable the generation of the FXSR instructions. 5819 5820@item gfni 5821@itemx no-gfni 5822@cindex @code{target("gfni")} function attribute, x86 5823Enable/disable the generation of the GFNI instructions. 5824 5825@item hle 5826@itemx no-hle 5827@cindex @code{target("hle")} function attribute, x86 5828Enable/disable the generation of the HLE instruction prefixes. 5829 5830@item lwp 5831@itemx no-lwp 5832@cindex @code{target("lwp")} function attribute, x86 5833Enable/disable the generation of the LWP instructions. 5834 5835@item lzcnt 5836@itemx no-lzcnt 5837@cindex @code{target("lzcnt")} function attribute, x86 5838Enable/disable the generation of the LZCNT instructions. 5839 5840@item mmx 5841@itemx no-mmx 5842@cindex @code{target("mmx")} function attribute, x86 5843Enable/disable the generation of the MMX instructions. 5844 5845@item movbe 5846@itemx no-movbe 5847@cindex @code{target("movbe")} function attribute, x86 5848Enable/disable the generation of the MOVBE instructions. 5849 5850@item movdir64b 5851@itemx no-movdir64b 5852@cindex @code{target("movdir64b")} function attribute, x86 5853Enable/disable the generation of the MOVDIR64B instructions. 5854 5855@item movdiri 5856@itemx no-movdiri 5857@cindex @code{target("movdiri")} function attribute, x86 5858Enable/disable the generation of the MOVDIRI instructions. 5859 5860@item mwaitx 5861@itemx no-mwaitx 5862@cindex @code{target("mwaitx")} function attribute, x86 5863Enable/disable the generation of the MWAITX instructions. 5864 5865@item pclmul 5866@itemx no-pclmul 5867@cindex @code{target("pclmul")} function attribute, x86 5868Enable/disable the generation of the PCLMUL instructions. 5869 5870@item pconfig 5871@itemx no-pconfig 5872@cindex @code{target("pconfig")} function attribute, x86 5873Enable/disable the generation of the PCONFIG instructions. 5874 5875@item pku 5876@itemx no-pku 5877@cindex @code{target("pku")} function attribute, x86 5878Enable/disable the generation of the PKU instructions. 5879 5880@item popcnt 5881@itemx no-popcnt 5882@cindex @code{target("popcnt")} function attribute, x86 5883Enable/disable the generation of the POPCNT instruction. 5884 5885@item prefetchwt1 5886@itemx no-prefetchwt1 5887@cindex @code{target("prefetchwt1")} function attribute, x86 5888Enable/disable the generation of the PREFETCHWT1 instructions. 5889 5890@item prfchw 5891@itemx no-prfchw 5892@cindex @code{target("prfchw")} function attribute, x86 5893Enable/disable the generation of the PREFETCHW instruction. 5894 5895@item rdpid 5896@itemx no-rdpid 5897@cindex @code{target("rdpid")} function attribute, x86 5898Enable/disable the generation of the RDPID instructions. 5899 5900@item rdrnd 5901@itemx no-rdrnd 5902@cindex @code{target("rdrnd")} function attribute, x86 5903Enable/disable the generation of the RDRND instructions. 5904 5905@item rdseed 5906@itemx no-rdseed 5907@cindex @code{target("rdseed")} function attribute, x86 5908Enable/disable the generation of the RDSEED instructions. 5909 5910@item rtm 5911@itemx no-rtm 5912@cindex @code{target("rtm")} function attribute, x86 5913Enable/disable the generation of the RTM instructions. 5914 5915@item sahf 5916@itemx no-sahf 5917@cindex @code{target("sahf")} function attribute, x86 5918Enable/disable the generation of the SAHF instructions. 5919 5920@item sgx 5921@itemx no-sgx 5922@cindex @code{target("sgx")} function attribute, x86 5923Enable/disable the generation of the SGX instructions. 5924 5925@item sha 5926@itemx no-sha 5927@cindex @code{target("sha")} function attribute, x86 5928Enable/disable the generation of the SHA instructions. 5929 5930@item shstk 5931@itemx no-shstk 5932@cindex @code{target("shstk")} function attribute, x86 5933Enable/disable the shadow stack built-in functions from CET. 5934 5935@item sse 5936@itemx no-sse 5937@cindex @code{target("sse")} function attribute, x86 5938Enable/disable the generation of the SSE instructions. 5939 5940@item sse2 5941@itemx no-sse2 5942@cindex @code{target("sse2")} function attribute, x86 5943Enable/disable the generation of the SSE2 instructions. 5944 5945@item sse3 5946@itemx no-sse3 5947@cindex @code{target("sse3")} function attribute, x86 5948Enable/disable the generation of the SSE3 instructions. 5949 5950@item sse4 5951@itemx no-sse4 5952@cindex @code{target("sse4")} function attribute, x86 5953Enable/disable the generation of the SSE4 instructions (both SSE4.1 5954and SSE4.2). 5955 5956@item sse4.1 5957@itemx no-sse4.1 5958@cindex @code{target("sse4.1")} function attribute, x86 5959Enable/disable the generation of the sse4.1 instructions. 5960 5961@item sse4.2 5962@itemx no-sse4.2 5963@cindex @code{target("sse4.2")} function attribute, x86 5964Enable/disable the generation of the sse4.2 instructions. 5965 5966@item sse4a 5967@itemx no-sse4a 5968@cindex @code{target("sse4a")} function attribute, x86 5969Enable/disable the generation of the SSE4A instructions. 5970 5971@item ssse3 5972@itemx no-ssse3 5973@cindex @code{target("ssse3")} function attribute, x86 5974Enable/disable the generation of the SSSE3 instructions. 5975 5976@item tbm 5977@itemx no-tbm 5978@cindex @code{target("tbm")} function attribute, x86 5979Enable/disable the generation of the TBM instructions. 5980 5981@item vaes 5982@itemx no-vaes 5983@cindex @code{target("vaes")} function attribute, x86 5984Enable/disable the generation of the VAES instructions. 5985 5986@item vpclmulqdq 5987@itemx no-vpclmulqdq 5988@cindex @code{target("vpclmulqdq")} function attribute, x86 5989Enable/disable the generation of the VPCLMULQDQ instructions. 5990 5991@item wbnoinvd 5992@itemx no-wbnoinvd 5993@cindex @code{target("wbnoinvd")} function attribute, x86 5994Enable/disable the generation of the WBNOINVD instructions. 5995 5996@item xop 5997@itemx no-xop 5998@cindex @code{target("xop")} function attribute, x86 5999Enable/disable the generation of the XOP instructions. 6000 6001@item xsave 6002@itemx no-xsave 6003@cindex @code{target("xsave")} function attribute, x86 6004Enable/disable the generation of the XSAVE instructions. 6005 6006@item xsavec 6007@itemx no-xsavec 6008@cindex @code{target("xsavec")} function attribute, x86 6009Enable/disable the generation of the XSAVEC instructions. 6010 6011@item xsaveopt 6012@itemx no-xsaveopt 6013@cindex @code{target("xsaveopt")} function attribute, x86 6014Enable/disable the generation of the XSAVEOPT instructions. 6015 6016@item xsaves 6017@itemx no-xsaves 6018@cindex @code{target("xsaves")} function attribute, x86 6019Enable/disable the generation of the XSAVES instructions. 6020 6021@item cld 6022@itemx no-cld 6023@cindex @code{target("cld")} function attribute, x86 6024Enable/disable the generation of the CLD before string moves. 6025 6026@item fancy-math-387 6027@itemx no-fancy-math-387 6028@cindex @code{target("fancy-math-387")} function attribute, x86 6029Enable/disable the generation of the @code{sin}, @code{cos}, and 6030@code{sqrt} instructions on the 387 floating-point unit. 6031 6032@item ieee-fp 6033@itemx no-ieee-fp 6034@cindex @code{target("ieee-fp")} function attribute, x86 6035Enable/disable the generation of floating point that depends on IEEE arithmetic. 6036 6037@item inline-all-stringops 6038@itemx no-inline-all-stringops 6039@cindex @code{target("inline-all-stringops")} function attribute, x86 6040Enable/disable inlining of string operations. 6041 6042@item inline-stringops-dynamically 6043@itemx no-inline-stringops-dynamically 6044@cindex @code{target("inline-stringops-dynamically")} function attribute, x86 6045Enable/disable the generation of the inline code to do small string 6046operations and calling the library routines for large operations. 6047 6048@item align-stringops 6049@itemx no-align-stringops 6050@cindex @code{target("align-stringops")} function attribute, x86 6051Do/do not align destination of inlined string operations. 6052 6053@item recip 6054@itemx no-recip 6055@cindex @code{target("recip")} function attribute, x86 6056Enable/disable the generation of RCPSS, RCPPS, RSQRTSS and RSQRTPS 6057instructions followed an additional Newton-Raphson step instead of 6058doing a floating-point division. 6059 6060@item arch=@var{ARCH} 6061@cindex @code{target("arch=@var{ARCH}")} function attribute, x86 6062Specify the architecture to generate code for in compiling the function. 6063 6064@item tune=@var{TUNE} 6065@cindex @code{target("tune=@var{TUNE}")} function attribute, x86 6066Specify the architecture to tune for in compiling the function. 6067 6068@item fpmath=@var{FPMATH} 6069@cindex @code{target("fpmath=@var{FPMATH}")} function attribute, x86 6070Specify which floating-point unit to use. You must specify the 6071@code{target("fpmath=sse,387")} option as 6072@code{target("fpmath=sse+387")} because the comma would separate 6073different options. 6074 6075@item indirect_branch("@var{choice}") 6076@cindex @code{indirect_branch} function attribute, x86 6077On x86 targets, the @code{indirect_branch} attribute causes the compiler 6078to convert indirect call and jump with @var{choice}. @samp{keep} 6079keeps indirect call and jump unmodified. @samp{thunk} converts indirect 6080call and jump to call and return thunk. @samp{thunk-inline} converts 6081indirect call and jump to inlined call and return thunk. 6082@samp{thunk-extern} converts indirect call and jump to external call 6083and return thunk provided in a separate object file. 6084 6085@item function_return("@var{choice}") 6086@cindex @code{function_return} function attribute, x86 6087On x86 targets, the @code{function_return} attribute causes the compiler 6088to convert function return with @var{choice}. @samp{keep} keeps function 6089return unmodified. @samp{thunk} converts function return to call and 6090return thunk. @samp{thunk-inline} converts function return to inlined 6091call and return thunk. @samp{thunk-extern} converts function return to 6092external call and return thunk provided in a separate object file. 6093 6094@item nocf_check 6095@cindex @code{nocf_check} function attribute 6096The @code{nocf_check} attribute on a function is used to inform the 6097compiler that the function's prologue should not be instrumented when 6098compiled with the @option{-fcf-protection=branch} option. The 6099compiler assumes that the function's address is a valid target for a 6100control-flow transfer. 6101 6102The @code{nocf_check} attribute on a type of pointer to function is 6103used to inform the compiler that a call through the pointer should 6104not be instrumented when compiled with the 6105@option{-fcf-protection=branch} option. The compiler assumes 6106that the function's address from the pointer is a valid target for 6107a control-flow transfer. A direct function call through a function 6108name is assumed to be a safe call thus direct calls are not 6109instrumented by the compiler. 6110 6111The @code{nocf_check} attribute is applied to an object's type. 6112In case of assignment of a function address or a function pointer to 6113another pointer, the attribute is not carried over from the right-hand 6114object's type; the type of left-hand object stays unchanged. The 6115compiler checks for @code{nocf_check} attribute mismatch and reports 6116a warning in case of mismatch. 6117 6118@smallexample 6119@{ 6120int foo (void) __attribute__(nocf_check); 6121void (*foo1)(void) __attribute__(nocf_check); 6122void (*foo2)(void); 6123 6124/* foo's address is assumed to be valid. */ 6125int 6126foo (void) 6127 6128 /* This call site is not checked for control-flow 6129 validity. */ 6130 (*foo1)(); 6131 6132 /* A warning is issued about attribute mismatch. */ 6133 foo1 = foo2; 6134 6135 /* This call site is still not checked. */ 6136 (*foo1)(); 6137 6138 /* This call site is checked. */ 6139 (*foo2)(); 6140 6141 /* A warning is issued about attribute mismatch. */ 6142 foo2 = foo1; 6143 6144 /* This call site is still checked. */ 6145 (*foo2)(); 6146 6147 return 0; 6148@} 6149@end smallexample 6150 6151@end table 6152 6153On the x86, the inliner does not inline a 6154function that has different target options than the caller, unless the 6155callee has a subset of the target options of the caller. For example 6156a function declared with @code{target("sse3")} can inline a function 6157with @code{target("sse2")}, since @code{-msse3} implies @code{-msse2}. 6158@end table 6159 6160@node Xstormy16 Function Attributes 6161@subsection Xstormy16 Function Attributes 6162 6163These function attributes are supported by the Xstormy16 back end: 6164 6165@table @code 6166@item interrupt 6167@cindex @code{interrupt} function attribute, Xstormy16 6168Use this attribute to indicate 6169that the specified function is an interrupt handler. The compiler generates 6170function entry and exit sequences suitable for use in an interrupt handler 6171when this attribute is present. 6172@end table 6173 6174@node Variable Attributes 6175@section Specifying Attributes of Variables 6176@cindex attribute of variables 6177@cindex variable attributes 6178 6179The keyword @code{__attribute__} allows you to specify special 6180attributes of variables or structure fields. This keyword is followed 6181by an attribute specification inside double parentheses. Some 6182attributes are currently defined generically for variables. 6183Other attributes are defined for variables on particular target 6184systems. Other attributes are available for functions 6185(@pxref{Function Attributes}), labels (@pxref{Label Attributes}), 6186enumerators (@pxref{Enumerator Attributes}), statements 6187(@pxref{Statement Attributes}), and for types (@pxref{Type Attributes}). 6188Other front ends might define more attributes 6189(@pxref{C++ Extensions,,Extensions to the C++ Language}). 6190 6191@xref{Attribute Syntax}, for details of the exact syntax for using 6192attributes. 6193 6194@menu 6195* Common Variable Attributes:: 6196* ARC Variable Attributes:: 6197* AVR Variable Attributes:: 6198* Blackfin Variable Attributes:: 6199* H8/300 Variable Attributes:: 6200* IA-64 Variable Attributes:: 6201* M32R/D Variable Attributes:: 6202* MeP Variable Attributes:: 6203* Microsoft Windows Variable Attributes:: 6204* MSP430 Variable Attributes:: 6205* Nvidia PTX Variable Attributes:: 6206* PowerPC Variable Attributes:: 6207* RL78 Variable Attributes:: 6208* SPU Variable Attributes:: 6209* V850 Variable Attributes:: 6210* x86 Variable Attributes:: 6211* Xstormy16 Variable Attributes:: 6212@end menu 6213 6214@node Common Variable Attributes 6215@subsection Common Variable Attributes 6216 6217The following attributes are supported on most targets. 6218 6219@table @code 6220@cindex @code{aligned} variable attribute 6221@item aligned (@var{alignment}) 6222This attribute specifies a minimum alignment for the variable or 6223structure field, measured in bytes. For example, the declaration: 6224 6225@smallexample 6226int x __attribute__ ((aligned (16))) = 0; 6227@end smallexample 6228 6229@noindent 6230causes the compiler to allocate the global variable @code{x} on a 623116-byte boundary. On a 68040, this could be used in conjunction with 6232an @code{asm} expression to access the @code{move16} instruction which 6233requires 16-byte aligned operands. 6234 6235You can also specify the alignment of structure fields. For example, to 6236create a double-word aligned @code{int} pair, you could write: 6237 6238@smallexample 6239struct foo @{ int x[2] __attribute__ ((aligned (8))); @}; 6240@end smallexample 6241 6242@noindent 6243This is an alternative to creating a union with a @code{double} member, 6244which forces the union to be double-word aligned. 6245 6246As in the preceding examples, you can explicitly specify the alignment 6247(in bytes) that you wish the compiler to use for a given variable or 6248structure field. Alternatively, you can leave out the alignment factor 6249and just ask the compiler to align a variable or field to the 6250default alignment for the target architecture you are compiling for. 6251The default alignment is sufficient for all scalar types, but may not be 6252enough for all vector types on a target that supports vector operations. 6253The default alignment is fixed for a particular target ABI. 6254 6255GCC also provides a target specific macro @code{__BIGGEST_ALIGNMENT__}, 6256which is the largest alignment ever used for any data type on the 6257target machine you are compiling for. For example, you could write: 6258 6259@smallexample 6260short array[3] __attribute__ ((aligned (__BIGGEST_ALIGNMENT__))); 6261@end smallexample 6262 6263The compiler automatically sets the alignment for the declared 6264variable or field to @code{__BIGGEST_ALIGNMENT__}. Doing this can 6265often make copy operations more efficient, because the compiler can 6266use whatever instructions copy the biggest chunks of memory when 6267performing copies to or from the variables or fields that you have 6268aligned this way. Note that the value of @code{__BIGGEST_ALIGNMENT__} 6269may change depending on command-line options. 6270 6271When used on a struct, or struct member, the @code{aligned} attribute can 6272only increase the alignment; in order to decrease it, the @code{packed} 6273attribute must be specified as well. When used as part of a typedef, the 6274@code{aligned} attribute can both increase and decrease alignment, and 6275specifying the @code{packed} attribute generates a warning. 6276 6277Note that the effectiveness of @code{aligned} attributes may be limited 6278by inherent limitations in your linker. On many systems, the linker is 6279only able to arrange for variables to be aligned up to a certain maximum 6280alignment. (For some linkers, the maximum supported alignment may 6281be very very small.) If your linker is only able to align variables 6282up to a maximum of 8-byte alignment, then specifying @code{aligned(16)} 6283in an @code{__attribute__} still only provides you with 8-byte 6284alignment. See your linker documentation for further information. 6285 6286The @code{aligned} attribute can also be used for functions 6287(@pxref{Common Function Attributes}.) 6288 6289@cindex @code{warn_if_not_aligned} variable attribute 6290@item warn_if_not_aligned (@var{alignment}) 6291This attribute specifies a threshold for the structure field, measured 6292in bytes. If the structure field is aligned below the threshold, a 6293warning will be issued. For example, the declaration: 6294 6295@smallexample 6296struct foo 6297@{ 6298 int i1; 6299 int i2; 6300 unsigned long long x __attribute__((warn_if_not_aligned(16))); 6301@}; 6302@end smallexample 6303 6304@noindent 6305causes the compiler to issue an warning on @code{struct foo}, like 6306@samp{warning: alignment 8 of 'struct foo' is less than 16}. 6307The compiler also issues a warning, like @samp{warning: 'x' offset 63088 in 'struct foo' isn't aligned to 16}, when the structure field has 6309the misaligned offset: 6310 6311@smallexample 6312struct foo 6313@{ 6314 int i1; 6315 int i2; 6316 unsigned long long x __attribute__((warn_if_not_aligned(16))); 6317@} __attribute__((aligned(16))); 6318@end smallexample 6319 6320This warning can be disabled by @option{-Wno-if-not-aligned}. 6321The @code{warn_if_not_aligned} attribute can also be used for types 6322(@pxref{Common Type Attributes}.) 6323 6324@item cleanup (@var{cleanup_function}) 6325@cindex @code{cleanup} variable attribute 6326The @code{cleanup} attribute runs a function when the variable goes 6327out of scope. This attribute can only be applied to auto function 6328scope variables; it may not be applied to parameters or variables 6329with static storage duration. The function must take one parameter, 6330a pointer to a type compatible with the variable. The return value 6331of the function (if any) is ignored. 6332 6333If @option{-fexceptions} is enabled, then @var{cleanup_function} 6334is run during the stack unwinding that happens during the 6335processing of the exception. Note that the @code{cleanup} attribute 6336does not allow the exception to be caught, only to perform an action. 6337It is undefined what happens if @var{cleanup_function} does not 6338return normally. 6339 6340@item common 6341@itemx nocommon 6342@cindex @code{common} variable attribute 6343@cindex @code{nocommon} variable attribute 6344@opindex fcommon 6345@opindex fno-common 6346The @code{common} attribute requests GCC to place a variable in 6347``common'' storage. The @code{nocommon} attribute requests the 6348opposite---to allocate space for it directly. 6349 6350These attributes override the default chosen by the 6351@option{-fno-common} and @option{-fcommon} flags respectively. 6352 6353@item deprecated 6354@itemx deprecated (@var{msg}) 6355@cindex @code{deprecated} variable attribute 6356The @code{deprecated} attribute results in a warning if the variable 6357is used anywhere in the source file. This is useful when identifying 6358variables that are expected to be removed in a future version of a 6359program. The warning also includes the location of the declaration 6360of the deprecated variable, to enable users to easily find further 6361information about why the variable is deprecated, or what they should 6362do instead. Note that the warning only occurs for uses: 6363 6364@smallexample 6365extern int old_var __attribute__ ((deprecated)); 6366extern int old_var; 6367int new_fn () @{ return old_var; @} 6368@end smallexample 6369 6370@noindent 6371results in a warning on line 3 but not line 2. The optional @var{msg} 6372argument, which must be a string, is printed in the warning if 6373present. 6374 6375The @code{deprecated} attribute can also be used for functions and 6376types (@pxref{Common Function Attributes}, 6377@pxref{Common Type Attributes}). 6378 6379@item nonstring 6380@cindex @code{nonstring} variable attribute 6381The @code{nonstring} variable attribute specifies that an object or member 6382declaration with type array of @code{char}, @code{signed char}, or 6383@code{unsigned char}, or pointer to such a type is intended to store 6384character arrays that do not necessarily contain a terminating @code{NUL}. 6385This is useful in detecting uses of such arrays or pointers with functions 6386that expect @code{NUL}-terminated strings, and to avoid warnings when such 6387an array or pointer is used as an argument to a bounded string manipulation 6388function such as @code{strncpy}. For example, without the attribute, GCC 6389will issue a warning for the @code{strncpy} call below because it may 6390truncate the copy without appending the terminating @code{NUL} character. 6391Using the attribute makes it possible to suppress the warning. However, 6392when the array is declared with the attribute the call to @code{strlen} is 6393diagnosed because when the array doesn't contain a @code{NUL}-terminated 6394string the call is undefined. To copy, compare, of search non-string 6395character arrays use the @code{memcpy}, @code{memcmp}, @code{memchr}, 6396and other functions that operate on arrays of bytes. In addition, 6397calling @code{strnlen} and @code{strndup} with such arrays is safe 6398provided a suitable bound is specified, and not diagnosed. 6399 6400@smallexample 6401struct Data 6402@{ 6403 char name [32] __attribute__ ((nonstring)); 6404@}; 6405 6406int f (struct Data *pd, const char *s) 6407@{ 6408 strncpy (pd->name, s, sizeof pd->name); 6409 @dots{} 6410 return strlen (pd->name); // unsafe, gets a warning 6411@} 6412@end smallexample 6413 6414@item mode (@var{mode}) 6415@cindex @code{mode} variable attribute 6416This attribute specifies the data type for the declaration---whichever 6417type corresponds to the mode @var{mode}. This in effect lets you 6418request an integer or floating-point type according to its width. 6419 6420@xref{Machine Modes,,, gccint, GNU Compiler Collection (GCC) Internals}, 6421for a list of the possible keywords for @var{mode}. 6422You may also specify a mode of @code{byte} or @code{__byte__} to 6423indicate the mode corresponding to a one-byte integer, @code{word} or 6424@code{__word__} for the mode of a one-word integer, and @code{pointer} 6425or @code{__pointer__} for the mode used to represent pointers. 6426 6427@item packed 6428@cindex @code{packed} variable attribute 6429The @code{packed} attribute specifies that a variable or structure field 6430should have the smallest possible alignment---one byte for a variable, 6431and one bit for a field, unless you specify a larger value with the 6432@code{aligned} attribute. 6433 6434Here is a structure in which the field @code{x} is packed, so that it 6435immediately follows @code{a}: 6436 6437@smallexample 6438struct foo 6439@{ 6440 char a; 6441 int x[2] __attribute__ ((packed)); 6442@}; 6443@end smallexample 6444 6445@emph{Note:} The 4.1, 4.2 and 4.3 series of GCC ignore the 6446@code{packed} attribute on bit-fields of type @code{char}. This has 6447been fixed in GCC 4.4 but the change can lead to differences in the 6448structure layout. See the documentation of 6449@option{-Wpacked-bitfield-compat} for more information. 6450 6451@item section ("@var{section-name}") 6452@cindex @code{section} variable attribute 6453Normally, the compiler places the objects it generates in sections like 6454@code{data} and @code{bss}. Sometimes, however, you need additional sections, 6455or you need certain particular variables to appear in special sections, 6456for example to map to special hardware. The @code{section} 6457attribute specifies that a variable (or function) lives in a particular 6458section. For example, this small program uses several specific section names: 6459 6460@smallexample 6461struct duart a __attribute__ ((section ("DUART_A"))) = @{ 0 @}; 6462struct duart b __attribute__ ((section ("DUART_B"))) = @{ 0 @}; 6463char stack[10000] __attribute__ ((section ("STACK"))) = @{ 0 @}; 6464int init_data __attribute__ ((section ("INITDATA"))); 6465 6466main() 6467@{ 6468 /* @r{Initialize stack pointer} */ 6469 init_sp (stack + sizeof (stack)); 6470 6471 /* @r{Initialize initialized data} */ 6472 memcpy (&init_data, &data, &edata - &data); 6473 6474 /* @r{Turn on the serial ports} */ 6475 init_duart (&a); 6476 init_duart (&b); 6477@} 6478@end smallexample 6479 6480@noindent 6481Use the @code{section} attribute with 6482@emph{global} variables and not @emph{local} variables, 6483as shown in the example. 6484 6485You may use the @code{section} attribute with initialized or 6486uninitialized global variables but the linker requires 6487each object be defined once, with the exception that uninitialized 6488variables tentatively go in the @code{common} (or @code{bss}) section 6489and can be multiply ``defined''. Using the @code{section} attribute 6490changes what section the variable goes into and may cause the 6491linker to issue an error if an uninitialized variable has multiple 6492definitions. You can force a variable to be initialized with the 6493@option{-fno-common} flag or the @code{nocommon} attribute. 6494 6495Some file formats do not support arbitrary sections so the @code{section} 6496attribute is not available on all platforms. 6497If you need to map the entire contents of a module to a particular 6498section, consider using the facilities of the linker instead. 6499 6500@item tls_model ("@var{tls_model}") 6501@cindex @code{tls_model} variable attribute 6502The @code{tls_model} attribute sets thread-local storage model 6503(@pxref{Thread-Local}) of a particular @code{__thread} variable, 6504overriding @option{-ftls-model=} command-line switch on a per-variable 6505basis. 6506The @var{tls_model} argument should be one of @code{global-dynamic}, 6507@code{local-dynamic}, @code{initial-exec} or @code{local-exec}. 6508 6509Not all targets support this attribute. 6510 6511@item unused 6512@cindex @code{unused} variable attribute 6513This attribute, attached to a variable, means that the variable is meant 6514to be possibly unused. GCC does not produce a warning for this 6515variable. 6516 6517@item used 6518@cindex @code{used} variable attribute 6519This attribute, attached to a variable with static storage, means that 6520the variable must be emitted even if it appears that the variable is not 6521referenced. 6522 6523When applied to a static data member of a C++ class template, the 6524attribute also means that the member is instantiated if the 6525class itself is instantiated. 6526 6527@item vector_size (@var{bytes}) 6528@cindex @code{vector_size} variable attribute 6529This attribute specifies the vector size for the variable, measured in 6530bytes. For example, the declaration: 6531 6532@smallexample 6533int foo __attribute__ ((vector_size (16))); 6534@end smallexample 6535 6536@noindent 6537causes the compiler to set the mode for @code{foo}, to be 16 bytes, 6538divided into @code{int} sized units. Assuming a 32-bit int (a vector of 65394 units of 4 bytes), the corresponding mode of @code{foo} is V4SI@. 6540 6541This attribute is only applicable to integral and float scalars, 6542although arrays, pointers, and function return values are allowed in 6543conjunction with this construct. 6544 6545Aggregates with this attribute are invalid, even if they are of the same 6546size as a corresponding scalar. For example, the declaration: 6547 6548@smallexample 6549struct S @{ int a; @}; 6550struct S __attribute__ ((vector_size (16))) foo; 6551@end smallexample 6552 6553@noindent 6554is invalid even if the size of the structure is the same as the size of 6555the @code{int}. 6556 6557@item visibility ("@var{visibility_type}") 6558@cindex @code{visibility} variable attribute 6559This attribute affects the linkage of the declaration to which it is attached. 6560The @code{visibility} attribute is described in 6561@ref{Common Function Attributes}. 6562 6563@item weak 6564@cindex @code{weak} variable attribute 6565The @code{weak} attribute is described in 6566@ref{Common Function Attributes}. 6567 6568@end table 6569 6570@node ARC Variable Attributes 6571@subsection ARC Variable Attributes 6572 6573@table @code 6574@item aux 6575@cindex @code{aux} variable attribute, ARC 6576The @code{aux} attribute is used to directly access the ARC's 6577auxiliary register space from C. The auxilirary register number is 6578given via attribute argument. 6579 6580@end table 6581 6582@node AVR Variable Attributes 6583@subsection AVR Variable Attributes 6584 6585@table @code 6586@item progmem 6587@cindex @code{progmem} variable attribute, AVR 6588The @code{progmem} attribute is used on the AVR to place read-only 6589data in the non-volatile program memory (flash). The @code{progmem} 6590attribute accomplishes this by putting respective variables into a 6591section whose name starts with @code{.progmem}. 6592 6593This attribute works similar to the @code{section} attribute 6594but adds additional checking. 6595 6596@table @asis 6597@item @bullet{}@tie{} Ordinary AVR cores with 32 general purpose registers: 6598@code{progmem} affects the location 6599of the data but not how this data is accessed. 6600In order to read data located with the @code{progmem} attribute 6601(inline) assembler must be used. 6602@smallexample 6603/* Use custom macros from @w{@uref{http://nongnu.org/avr-libc/user-manual/,AVR-LibC}} */ 6604#include <avr/pgmspace.h> 6605 6606/* Locate var in flash memory */ 6607const int var[2] PROGMEM = @{ 1, 2 @}; 6608 6609int read_var (int i) 6610@{ 6611 /* Access var[] by accessor macro from avr/pgmspace.h */ 6612 return (int) pgm_read_word (& var[i]); 6613@} 6614@end smallexample 6615 6616AVR is a Harvard architecture processor and data and read-only data 6617normally resides in the data memory (RAM). 6618 6619See also the @ref{AVR Named Address Spaces} section for 6620an alternate way to locate and access data in flash memory. 6621 6622@item @bullet{}@tie{} AVR cores with flash memory visible in the RAM address range: 6623On such devices, there is no need for attribute @code{progmem} or 6624@ref{AVR Named Address Spaces,,@code{__flash}} qualifier at all. 6625Just use standard C / C++. The compiler will generate @code{LD*} 6626instructions. As flash memory is visible in the RAM address range, 6627and the default linker script does @emph{not} locate @code{.rodata} in 6628RAM, no special features are needed in order not to waste RAM for 6629read-only data or to read from flash. You might even get slightly better 6630performance by 6631avoiding @code{progmem} and @code{__flash}. This applies to devices from 6632families @code{avrtiny} and @code{avrxmega3}, see @ref{AVR Options} for 6633an overview. 6634 6635@item @bullet{}@tie{}Reduced AVR Tiny cores like ATtiny40: 6636The compiler adds @code{0x4000} 6637to the addresses of objects and declarations in @code{progmem} and locates 6638the objects in flash memory, namely in section @code{.progmem.data}. 6639The offset is needed because the flash memory is visible in the RAM 6640address space starting at address @code{0x4000}. 6641 6642Data in @code{progmem} can be accessed by means of ordinary C@tie{}code, 6643no special functions or macros are needed. 6644 6645@smallexample 6646/* var is located in flash memory */ 6647extern const int var[2] __attribute__((progmem)); 6648 6649int read_var (int i) 6650@{ 6651 return var[i]; 6652@} 6653@end smallexample 6654 6655Please notice that on these devices, there is no need for @code{progmem} 6656at all. 6657 6658@end table 6659 6660@item io 6661@itemx io (@var{addr}) 6662@cindex @code{io} variable attribute, AVR 6663Variables with the @code{io} attribute are used to address 6664memory-mapped peripherals in the io address range. 6665If an address is specified, the variable 6666is assigned that address, and the value is interpreted as an 6667address in the data address space. 6668Example: 6669 6670@smallexample 6671volatile int porta __attribute__((io (0x22))); 6672@end smallexample 6673 6674The address specified in the address in the data address range. 6675 6676Otherwise, the variable it is not assigned an address, but the 6677compiler will still use in/out instructions where applicable, 6678assuming some other module assigns an address in the io address range. 6679Example: 6680 6681@smallexample 6682extern volatile int porta __attribute__((io)); 6683@end smallexample 6684 6685@item io_low 6686@itemx io_low (@var{addr}) 6687@cindex @code{io_low} variable attribute, AVR 6688This is like the @code{io} attribute, but additionally it informs the 6689compiler that the object lies in the lower half of the I/O area, 6690allowing the use of @code{cbi}, @code{sbi}, @code{sbic} and @code{sbis} 6691instructions. 6692 6693@item address 6694@itemx address (@var{addr}) 6695@cindex @code{address} variable attribute, AVR 6696Variables with the @code{address} attribute are used to address 6697memory-mapped peripherals that may lie outside the io address range. 6698 6699@smallexample 6700volatile int porta __attribute__((address (0x600))); 6701@end smallexample 6702 6703@item absdata 6704@cindex @code{absdata} variable attribute, AVR 6705Variables in static storage and with the @code{absdata} attribute can 6706be accessed by the @code{LDS} and @code{STS} instructions which take 6707absolute addresses. 6708 6709@itemize @bullet 6710@item 6711This attribute is only supported for the reduced AVR Tiny core 6712like ATtiny40. 6713 6714@item 6715You must make sure that respective data is located in the 6716address range @code{0x40}@dots{}@code{0xbf} accessible by 6717@code{LDS} and @code{STS}. One way to achieve this as an 6718appropriate linker description file. 6719 6720@item 6721If the location does not fit the address range of @code{LDS} 6722and @code{STS}, there is currently (Binutils 2.26) just an unspecific 6723warning like 6724@quotation 6725@code{module.c:(.text+0x1c): warning: internal error: out of range error} 6726@end quotation 6727 6728@end itemize 6729 6730See also the @option{-mabsdata} @ref{AVR Options,command-line option}. 6731 6732@end table 6733 6734@node Blackfin Variable Attributes 6735@subsection Blackfin Variable Attributes 6736 6737Three attributes are currently defined for the Blackfin. 6738 6739@table @code 6740@item l1_data 6741@itemx l1_data_A 6742@itemx l1_data_B 6743@cindex @code{l1_data} variable attribute, Blackfin 6744@cindex @code{l1_data_A} variable attribute, Blackfin 6745@cindex @code{l1_data_B} variable attribute, Blackfin 6746Use these attributes on the Blackfin to place the variable into L1 Data SRAM. 6747Variables with @code{l1_data} attribute are put into the specific section 6748named @code{.l1.data}. Those with @code{l1_data_A} attribute are put into 6749the specific section named @code{.l1.data.A}. Those with @code{l1_data_B} 6750attribute are put into the specific section named @code{.l1.data.B}. 6751 6752@item l2 6753@cindex @code{l2} variable attribute, Blackfin 6754Use this attribute on the Blackfin to place the variable into L2 SRAM. 6755Variables with @code{l2} attribute are put into the specific section 6756named @code{.l2.data}. 6757@end table 6758 6759@node H8/300 Variable Attributes 6760@subsection H8/300 Variable Attributes 6761 6762These variable attributes are available for H8/300 targets: 6763 6764@table @code 6765@item eightbit_data 6766@cindex @code{eightbit_data} variable attribute, H8/300 6767@cindex eight-bit data on the H8/300, H8/300H, and H8S 6768Use this attribute on the H8/300, H8/300H, and H8S to indicate that the specified 6769variable should be placed into the eight-bit data section. 6770The compiler generates more efficient code for certain operations 6771on data in the eight-bit data area. Note the eight-bit data area is limited to 6772256 bytes of data. 6773 6774You must use GAS and GLD from GNU binutils version 2.7 or later for 6775this attribute to work correctly. 6776 6777@item tiny_data 6778@cindex @code{tiny_data} variable attribute, H8/300 6779@cindex tiny data section on the H8/300H and H8S 6780Use this attribute on the H8/300H and H8S to indicate that the specified 6781variable should be placed into the tiny data section. 6782The compiler generates more efficient code for loads and stores 6783on data in the tiny data section. Note the tiny data area is limited to 6784slightly under 32KB of data. 6785 6786@end table 6787 6788@node IA-64 Variable Attributes 6789@subsection IA-64 Variable Attributes 6790 6791The IA-64 back end supports the following variable attribute: 6792 6793@table @code 6794@item model (@var{model-name}) 6795@cindex @code{model} variable attribute, IA-64 6796 6797On IA-64, use this attribute to set the addressability of an object. 6798At present, the only supported identifier for @var{model-name} is 6799@code{small}, indicating addressability via ``small'' (22-bit) 6800addresses (so that their addresses can be loaded with the @code{addl} 6801instruction). Caveat: such addressing is by definition not position 6802independent and hence this attribute must not be used for objects 6803defined by shared libraries. 6804 6805@end table 6806 6807@node M32R/D Variable Attributes 6808@subsection M32R/D Variable Attributes 6809 6810One attribute is currently defined for the M32R/D@. 6811 6812@table @code 6813@item model (@var{model-name}) 6814@cindex @code{model-name} variable attribute, M32R/D 6815@cindex variable addressability on the M32R/D 6816Use this attribute on the M32R/D to set the addressability of an object. 6817The identifier @var{model-name} is one of @code{small}, @code{medium}, 6818or @code{large}, representing each of the code models. 6819 6820Small model objects live in the lower 16MB of memory (so that their 6821addresses can be loaded with the @code{ld24} instruction). 6822 6823Medium and large model objects may live anywhere in the 32-bit address space 6824(the compiler generates @code{seth/add3} instructions to load their 6825addresses). 6826@end table 6827 6828@node MeP Variable Attributes 6829@subsection MeP Variable Attributes 6830 6831The MeP target has a number of addressing modes and busses. The 6832@code{near} space spans the standard memory space's first 16 megabytes 6833(24 bits). The @code{far} space spans the entire 32-bit memory space. 6834The @code{based} space is a 128-byte region in the memory space that 6835is addressed relative to the @code{$tp} register. The @code{tiny} 6836space is a 65536-byte region relative to the @code{$gp} register. In 6837addition to these memory regions, the MeP target has a separate 16-bit 6838control bus which is specified with @code{cb} attributes. 6839 6840@table @code 6841 6842@item based 6843@cindex @code{based} variable attribute, MeP 6844Any variable with the @code{based} attribute is assigned to the 6845@code{.based} section, and is accessed with relative to the 6846@code{$tp} register. 6847 6848@item tiny 6849@cindex @code{tiny} variable attribute, MeP 6850Likewise, the @code{tiny} attribute assigned variables to the 6851@code{.tiny} section, relative to the @code{$gp} register. 6852 6853@item near 6854@cindex @code{near} variable attribute, MeP 6855Variables with the @code{near} attribute are assumed to have addresses 6856that fit in a 24-bit addressing mode. This is the default for large 6857variables (@code{-mtiny=4} is the default) but this attribute can 6858override @code{-mtiny=} for small variables, or override @code{-ml}. 6859 6860@item far 6861@cindex @code{far} variable attribute, MeP 6862Variables with the @code{far} attribute are addressed using a full 686332-bit address. Since this covers the entire memory space, this 6864allows modules to make no assumptions about where variables might be 6865stored. 6866 6867@item io 6868@cindex @code{io} variable attribute, MeP 6869@itemx io (@var{addr}) 6870Variables with the @code{io} attribute are used to address 6871memory-mapped peripherals. If an address is specified, the variable 6872is assigned that address, else it is not assigned an address (it is 6873assumed some other module assigns an address). Example: 6874 6875@smallexample 6876int timer_count __attribute__((io(0x123))); 6877@end smallexample 6878 6879@item cb 6880@itemx cb (@var{addr}) 6881@cindex @code{cb} variable attribute, MeP 6882Variables with the @code{cb} attribute are used to access the control 6883bus, using special instructions. @code{addr} indicates the control bus 6884address. Example: 6885 6886@smallexample 6887int cpu_clock __attribute__((cb(0x123))); 6888@end smallexample 6889 6890@end table 6891 6892@node Microsoft Windows Variable Attributes 6893@subsection Microsoft Windows Variable Attributes 6894 6895You can use these attributes on Microsoft Windows targets. 6896@ref{x86 Variable Attributes} for additional Windows compatibility 6897attributes available on all x86 targets. 6898 6899@table @code 6900@item dllimport 6901@itemx dllexport 6902@cindex @code{dllimport} variable attribute 6903@cindex @code{dllexport} variable attribute 6904The @code{dllimport} and @code{dllexport} attributes are described in 6905@ref{Microsoft Windows Function Attributes}. 6906 6907@item selectany 6908@cindex @code{selectany} variable attribute 6909The @code{selectany} attribute causes an initialized global variable to 6910have link-once semantics. When multiple definitions of the variable are 6911encountered by the linker, the first is selected and the remainder are 6912discarded. Following usage by the Microsoft compiler, the linker is told 6913@emph{not} to warn about size or content differences of the multiple 6914definitions. 6915 6916Although the primary usage of this attribute is for POD types, the 6917attribute can also be applied to global C++ objects that are initialized 6918by a constructor. In this case, the static initialization and destruction 6919code for the object is emitted in each translation defining the object, 6920but the calls to the constructor and destructor are protected by a 6921link-once guard variable. 6922 6923The @code{selectany} attribute is only available on Microsoft Windows 6924targets. You can use @code{__declspec (selectany)} as a synonym for 6925@code{__attribute__ ((selectany))} for compatibility with other 6926compilers. 6927 6928@item shared 6929@cindex @code{shared} variable attribute 6930On Microsoft Windows, in addition to putting variable definitions in a named 6931section, the section can also be shared among all running copies of an 6932executable or DLL@. For example, this small program defines shared data 6933by putting it in a named section @code{shared} and marking the section 6934shareable: 6935 6936@smallexample 6937int foo __attribute__((section ("shared"), shared)) = 0; 6938 6939int 6940main() 6941@{ 6942 /* @r{Read and write foo. All running 6943 copies see the same value.} */ 6944 return 0; 6945@} 6946@end smallexample 6947 6948@noindent 6949You may only use the @code{shared} attribute along with @code{section} 6950attribute with a fully-initialized global definition because of the way 6951linkers work. See @code{section} attribute for more information. 6952 6953The @code{shared} attribute is only available on Microsoft Windows@. 6954 6955@end table 6956 6957@node MSP430 Variable Attributes 6958@subsection MSP430 Variable Attributes 6959 6960@table @code 6961@item noinit 6962@cindex @code{noinit} variable attribute, MSP430 6963Any data with the @code{noinit} attribute will not be initialised by 6964the C runtime startup code, or the program loader. Not initialising 6965data in this way can reduce program startup times. 6966 6967@item persistent 6968@cindex @code{persistent} variable attribute, MSP430 6969Any variable with the @code{persistent} attribute will not be 6970initialised by the C runtime startup code. Instead its value will be 6971set once, when the application is loaded, and then never initialised 6972again, even if the processor is reset or the program restarts. 6973Persistent data is intended to be placed into FLASH RAM, where its 6974value will be retained across resets. The linker script being used to 6975create the application should ensure that persistent data is correctly 6976placed. 6977 6978@item lower 6979@itemx upper 6980@itemx either 6981@cindex @code{lower} variable attribute, MSP430 6982@cindex @code{upper} variable attribute, MSP430 6983@cindex @code{either} variable attribute, MSP430 6984These attributes are the same as the MSP430 function attributes of the 6985same name (@pxref{MSP430 Function Attributes}). 6986These attributes can be applied to both functions and variables. 6987@end table 6988 6989@node Nvidia PTX Variable Attributes 6990@subsection Nvidia PTX Variable Attributes 6991 6992These variable attributes are supported by the Nvidia PTX back end: 6993 6994@table @code 6995@item shared 6996@cindex @code{shared} attribute, Nvidia PTX 6997Use this attribute to place a variable in the @code{.shared} memory space. 6998This memory space is private to each cooperative thread array; only threads 6999within one thread block refer to the same instance of the variable. 7000The runtime does not initialize variables in this memory space. 7001@end table 7002 7003@node PowerPC Variable Attributes 7004@subsection PowerPC Variable Attributes 7005 7006Three attributes currently are defined for PowerPC configurations: 7007@code{altivec}, @code{ms_struct} and @code{gcc_struct}. 7008 7009@cindex @code{ms_struct} variable attribute, PowerPC 7010@cindex @code{gcc_struct} variable attribute, PowerPC 7011For full documentation of the struct attributes please see the 7012documentation in @ref{x86 Variable Attributes}. 7013 7014@cindex @code{altivec} variable attribute, PowerPC 7015For documentation of @code{altivec} attribute please see the 7016documentation in @ref{PowerPC Type Attributes}. 7017 7018@node RL78 Variable Attributes 7019@subsection RL78 Variable Attributes 7020 7021@cindex @code{saddr} variable attribute, RL78 7022The RL78 back end supports the @code{saddr} variable attribute. This 7023specifies placement of the corresponding variable in the SADDR area, 7024which can be accessed more efficiently than the default memory region. 7025 7026@node SPU Variable Attributes 7027@subsection SPU Variable Attributes 7028 7029@cindex @code{spu_vector} variable attribute, SPU 7030The SPU supports the @code{spu_vector} attribute for variables. For 7031documentation of this attribute please see the documentation in 7032@ref{SPU Type Attributes}. 7033 7034@node V850 Variable Attributes 7035@subsection V850 Variable Attributes 7036 7037These variable attributes are supported by the V850 back end: 7038 7039@table @code 7040 7041@item sda 7042@cindex @code{sda} variable attribute, V850 7043Use this attribute to explicitly place a variable in the small data area, 7044which can hold up to 64 kilobytes. 7045 7046@item tda 7047@cindex @code{tda} variable attribute, V850 7048Use this attribute to explicitly place a variable in the tiny data area, 7049which can hold up to 256 bytes in total. 7050 7051@item zda 7052@cindex @code{zda} variable attribute, V850 7053Use this attribute to explicitly place a variable in the first 32 kilobytes 7054of memory. 7055@end table 7056 7057@node x86 Variable Attributes 7058@subsection x86 Variable Attributes 7059 7060Two attributes are currently defined for x86 configurations: 7061@code{ms_struct} and @code{gcc_struct}. 7062 7063@table @code 7064@item ms_struct 7065@itemx gcc_struct 7066@cindex @code{ms_struct} variable attribute, x86 7067@cindex @code{gcc_struct} variable attribute, x86 7068 7069If @code{packed} is used on a structure, or if bit-fields are used, 7070it may be that the Microsoft ABI lays out the structure differently 7071than the way GCC normally does. Particularly when moving packed 7072data between functions compiled with GCC and the native Microsoft compiler 7073(either via function call or as data in a file), it may be necessary to access 7074either format. 7075 7076The @code{ms_struct} and @code{gcc_struct} attributes correspond 7077to the @option{-mms-bitfields} and @option{-mno-ms-bitfields} 7078command-line options, respectively; 7079see @ref{x86 Options}, for details of how structure layout is affected. 7080@xref{x86 Type Attributes}, for information about the corresponding 7081attributes on types. 7082 7083@end table 7084 7085@node Xstormy16 Variable Attributes 7086@subsection Xstormy16 Variable Attributes 7087 7088One attribute is currently defined for xstormy16 configurations: 7089@code{below100}. 7090 7091@table @code 7092@item below100 7093@cindex @code{below100} variable attribute, Xstormy16 7094 7095If a variable has the @code{below100} attribute (@code{BELOW100} is 7096allowed also), GCC places the variable in the first 0x100 bytes of 7097memory and use special opcodes to access it. Such variables are 7098placed in either the @code{.bss_below100} section or the 7099@code{.data_below100} section. 7100 7101@end table 7102 7103@node Type Attributes 7104@section Specifying Attributes of Types 7105@cindex attribute of types 7106@cindex type attributes 7107 7108The keyword @code{__attribute__} allows you to specify special 7109attributes of types. Some type attributes apply only to @code{struct} 7110and @code{union} types, while others can apply to any type defined 7111via a @code{typedef} declaration. Other attributes are defined for 7112functions (@pxref{Function Attributes}), labels (@pxref{Label 7113Attributes}), enumerators (@pxref{Enumerator Attributes}), 7114statements (@pxref{Statement Attributes}), and for 7115variables (@pxref{Variable Attributes}). 7116 7117The @code{__attribute__} keyword is followed by an attribute specification 7118inside double parentheses. 7119 7120You may specify type attributes in an enum, struct or union type 7121declaration or definition by placing them immediately after the 7122@code{struct}, @code{union} or @code{enum} keyword. A less preferred 7123syntax is to place them just past the closing curly brace of the 7124definition. 7125 7126You can also include type attributes in a @code{typedef} declaration. 7127@xref{Attribute Syntax}, for details of the exact syntax for using 7128attributes. 7129 7130@menu 7131* Common Type Attributes:: 7132* ARC Type Attributes:: 7133* ARM Type Attributes:: 7134* MeP Type Attributes:: 7135* PowerPC Type Attributes:: 7136* SPU Type Attributes:: 7137* x86 Type Attributes:: 7138@end menu 7139 7140@node Common Type Attributes 7141@subsection Common Type Attributes 7142 7143The following type attributes are supported on most targets. 7144 7145@table @code 7146@cindex @code{aligned} type attribute 7147@item aligned (@var{alignment}) 7148This attribute specifies a minimum alignment (in bytes) for variables 7149of the specified type. For example, the declarations: 7150 7151@smallexample 7152struct S @{ short f[3]; @} __attribute__ ((aligned (8))); 7153typedef int more_aligned_int __attribute__ ((aligned (8))); 7154@end smallexample 7155 7156@noindent 7157force the compiler to ensure (as far as it can) that each variable whose 7158type is @code{struct S} or @code{more_aligned_int} is allocated and 7159aligned @emph{at least} on a 8-byte boundary. On a SPARC, having all 7160variables of type @code{struct S} aligned to 8-byte boundaries allows 7161the compiler to use the @code{ldd} and @code{std} (doubleword load and 7162store) instructions when copying one variable of type @code{struct S} to 7163another, thus improving run-time efficiency. 7164 7165Note that the alignment of any given @code{struct} or @code{union} type 7166is required by the ISO C standard to be at least a perfect multiple of 7167the lowest common multiple of the alignments of all of the members of 7168the @code{struct} or @code{union} in question. This means that you @emph{can} 7169effectively adjust the alignment of a @code{struct} or @code{union} 7170type by attaching an @code{aligned} attribute to any one of the members 7171of such a type, but the notation illustrated in the example above is a 7172more obvious, intuitive, and readable way to request the compiler to 7173adjust the alignment of an entire @code{struct} or @code{union} type. 7174 7175As in the preceding example, you can explicitly specify the alignment 7176(in bytes) that you wish the compiler to use for a given @code{struct} 7177or @code{union} type. Alternatively, you can leave out the alignment factor 7178and just ask the compiler to align a type to the maximum 7179useful alignment for the target machine you are compiling for. For 7180example, you could write: 7181 7182@smallexample 7183struct S @{ short f[3]; @} __attribute__ ((aligned)); 7184@end smallexample 7185 7186Whenever you leave out the alignment factor in an @code{aligned} 7187attribute specification, the compiler automatically sets the alignment 7188for the type to the largest alignment that is ever used for any data 7189type on the target machine you are compiling for. Doing this can often 7190make copy operations more efficient, because the compiler can use 7191whatever instructions copy the biggest chunks of memory when performing 7192copies to or from the variables that have types that you have aligned 7193this way. 7194 7195In the example above, if the size of each @code{short} is 2 bytes, then 7196the size of the entire @code{struct S} type is 6 bytes. The smallest 7197power of two that is greater than or equal to that is 8, so the 7198compiler sets the alignment for the entire @code{struct S} type to 8 7199bytes. 7200 7201Note that although you can ask the compiler to select a time-efficient 7202alignment for a given type and then declare only individual stand-alone 7203objects of that type, the compiler's ability to select a time-efficient 7204alignment is primarily useful only when you plan to create arrays of 7205variables having the relevant (efficiently aligned) type. If you 7206declare or use arrays of variables of an efficiently-aligned type, then 7207it is likely that your program also does pointer arithmetic (or 7208subscripting, which amounts to the same thing) on pointers to the 7209relevant type, and the code that the compiler generates for these 7210pointer arithmetic operations is often more efficient for 7211efficiently-aligned types than for other types. 7212 7213Note that the effectiveness of @code{aligned} attributes may be limited 7214by inherent limitations in your linker. On many systems, the linker is 7215only able to arrange for variables to be aligned up to a certain maximum 7216alignment. (For some linkers, the maximum supported alignment may 7217be very very small.) If your linker is only able to align variables 7218up to a maximum of 8-byte alignment, then specifying @code{aligned(16)} 7219in an @code{__attribute__} still only provides you with 8-byte 7220alignment. See your linker documentation for further information. 7221 7222The @code{aligned} attribute can only increase alignment. Alignment 7223can be decreased by specifying the @code{packed} attribute. See below. 7224 7225@cindex @code{warn_if_not_aligned} type attribute 7226@item warn_if_not_aligned (@var{alignment}) 7227This attribute specifies a threshold for the structure field, measured 7228in bytes. If the structure field is aligned below the threshold, a 7229warning will be issued. For example, the declaration: 7230 7231@smallexample 7232typedef unsigned long long __u64 7233 __attribute__((aligned(4),warn_if_not_aligned(8))); 7234 7235struct foo 7236@{ 7237 int i1; 7238 int i2; 7239 __u64 x; 7240@}; 7241@end smallexample 7242 7243@noindent 7244causes the compiler to issue an warning on @code{struct foo}, like 7245@samp{warning: alignment 4 of 'struct foo' is less than 8}. 7246It is used to define @code{struct foo} in such a way that 7247@code{struct foo} has the same layout and the structure field @code{x} 7248has the same alignment when @code{__u64} is aligned at either 4 or 72498 bytes. Align @code{struct foo} to 8 bytes: 7250 7251@smallexample 7252struct foo 7253@{ 7254 int i1; 7255 int i2; 7256 __u64 x; 7257@} __attribute__((aligned(8))); 7258@end smallexample 7259 7260@noindent 7261silences the warning. The compiler also issues a warning, like 7262@samp{warning: 'x' offset 12 in 'struct foo' isn't aligned to 8}, 7263when the structure field has the misaligned offset: 7264 7265@smallexample 7266struct foo 7267@{ 7268 int i1; 7269 int i2; 7270 int i3; 7271 __u64 x; 7272@} __attribute__((aligned(8))); 7273@end smallexample 7274 7275This warning can be disabled by @option{-Wno-if-not-aligned}. 7276 7277@item bnd_variable_size 7278@cindex @code{bnd_variable_size} type attribute 7279@cindex Pointer Bounds Checker attributes 7280When applied to a structure field, this attribute tells Pointer 7281Bounds Checker that the size of this field should not be computed 7282using static type information. It may be used to mark variably-sized 7283static array fields placed at the end of a structure. 7284 7285@smallexample 7286struct S 7287@{ 7288 int size; 7289 char data[1]; 7290@} 7291S *p = (S *)malloc (sizeof(S) + 100); 7292p->data[10] = 0; //Bounds violation 7293@end smallexample 7294 7295@noindent 7296By using an attribute for the field we may avoid unwanted bound 7297violation checks: 7298 7299@smallexample 7300struct S 7301@{ 7302 int size; 7303 char data[1] __attribute__((bnd_variable_size)); 7304@} 7305S *p = (S *)malloc (sizeof(S) + 100); 7306p->data[10] = 0; //OK 7307@end smallexample 7308 7309@item deprecated 7310@itemx deprecated (@var{msg}) 7311@cindex @code{deprecated} type attribute 7312The @code{deprecated} attribute results in a warning if the type 7313is used anywhere in the source file. This is useful when identifying 7314types that are expected to be removed in a future version of a program. 7315If possible, the warning also includes the location of the declaration 7316of the deprecated type, to enable users to easily find further 7317information about why the type is deprecated, or what they should do 7318instead. Note that the warnings only occur for uses and then only 7319if the type is being applied to an identifier that itself is not being 7320declared as deprecated. 7321 7322@smallexample 7323typedef int T1 __attribute__ ((deprecated)); 7324T1 x; 7325typedef T1 T2; 7326T2 y; 7327typedef T1 T3 __attribute__ ((deprecated)); 7328T3 z __attribute__ ((deprecated)); 7329@end smallexample 7330 7331@noindent 7332results in a warning on line 2 and 3 but not lines 4, 5, or 6. No 7333warning is issued for line 4 because T2 is not explicitly 7334deprecated. Line 5 has no warning because T3 is explicitly 7335deprecated. Similarly for line 6. The optional @var{msg} 7336argument, which must be a string, is printed in the warning if 7337present. 7338 7339The @code{deprecated} attribute can also be used for functions and 7340variables (@pxref{Function Attributes}, @pxref{Variable Attributes}.) 7341 7342@item designated_init 7343@cindex @code{designated_init} type attribute 7344This attribute may only be applied to structure types. It indicates 7345that any initialization of an object of this type must use designated 7346initializers rather than positional initializers. The intent of this 7347attribute is to allow the programmer to indicate that a structure's 7348layout may change, and that therefore relying on positional 7349initialization will result in future breakage. 7350 7351GCC emits warnings based on this attribute by default; use 7352@option{-Wno-designated-init} to suppress them. 7353 7354@item may_alias 7355@cindex @code{may_alias} type attribute 7356Accesses through pointers to types with this attribute are not subject 7357to type-based alias analysis, but are instead assumed to be able to alias 7358any other type of objects. 7359In the context of section 6.5 paragraph 7 of the C99 standard, 7360an lvalue expression 7361dereferencing such a pointer is treated like having a character type. 7362See @option{-fstrict-aliasing} for more information on aliasing issues. 7363This extension exists to support some vector APIs, in which pointers to 7364one vector type are permitted to alias pointers to a different vector type. 7365 7366Note that an object of a type with this attribute does not have any 7367special semantics. 7368 7369Example of use: 7370 7371@smallexample 7372typedef short __attribute__((__may_alias__)) short_a; 7373 7374int 7375main (void) 7376@{ 7377 int a = 0x12345678; 7378 short_a *b = (short_a *) &a; 7379 7380 b[1] = 0; 7381 7382 if (a == 0x12345678) 7383 abort(); 7384 7385 exit(0); 7386@} 7387@end smallexample 7388 7389@noindent 7390If you replaced @code{short_a} with @code{short} in the variable 7391declaration, the above program would abort when compiled with 7392@option{-fstrict-aliasing}, which is on by default at @option{-O2} or 7393above. 7394 7395@item packed 7396@cindex @code{packed} type attribute 7397This attribute, attached to @code{struct} or @code{union} type 7398definition, specifies that each member (other than zero-width bit-fields) 7399of the structure or union is placed to minimize the memory required. When 7400attached to an @code{enum} definition, it indicates that the smallest 7401integral type should be used. 7402 7403@opindex fshort-enums 7404Specifying the @code{packed} attribute for @code{struct} and @code{union} 7405types is equivalent to specifying the @code{packed} attribute on each 7406of the structure or union members. Specifying the @option{-fshort-enums} 7407flag on the command line is equivalent to specifying the @code{packed} 7408attribute on all @code{enum} definitions. 7409 7410In the following example @code{struct my_packed_struct}'s members are 7411packed closely together, but the internal layout of its @code{s} member 7412is not packed---to do that, @code{struct my_unpacked_struct} needs to 7413be packed too. 7414 7415@smallexample 7416struct my_unpacked_struct 7417 @{ 7418 char c; 7419 int i; 7420 @}; 7421 7422struct __attribute__ ((__packed__)) my_packed_struct 7423 @{ 7424 char c; 7425 int i; 7426 struct my_unpacked_struct s; 7427 @}; 7428@end smallexample 7429 7430You may only specify the @code{packed} attribute attribute on the definition 7431of an @code{enum}, @code{struct} or @code{union}, not on a @code{typedef} 7432that does not also define the enumerated type, structure or union. 7433 7434@item scalar_storage_order ("@var{endianness}") 7435@cindex @code{scalar_storage_order} type attribute 7436When attached to a @code{union} or a @code{struct}, this attribute sets 7437the storage order, aka endianness, of the scalar fields of the type, as 7438well as the array fields whose component is scalar. The supported 7439endiannesses are @code{big-endian} and @code{little-endian}. The attribute 7440has no effects on fields which are themselves a @code{union}, a @code{struct} 7441or an array whose component is a @code{union} or a @code{struct}, and it is 7442possible for these fields to have a different scalar storage order than the 7443enclosing type. 7444 7445This attribute is supported only for targets that use a uniform default 7446scalar storage order (fortunately, most of them), i.e. targets that store 7447the scalars either all in big-endian or all in little-endian. 7448 7449Additional restrictions are enforced for types with the reverse scalar 7450storage order with regard to the scalar storage order of the target: 7451 7452@itemize 7453@item Taking the address of a scalar field of a @code{union} or a 7454@code{struct} with reverse scalar storage order is not permitted and yields 7455an error. 7456@item Taking the address of an array field, whose component is scalar, of 7457a @code{union} or a @code{struct} with reverse scalar storage order is 7458permitted but yields a warning, unless @option{-Wno-scalar-storage-order} 7459is specified. 7460@item Taking the address of a @code{union} or a @code{struct} with reverse 7461scalar storage order is permitted. 7462@end itemize 7463 7464These restrictions exist because the storage order attribute is lost when 7465the address of a scalar or the address of an array with scalar component is 7466taken, so storing indirectly through this address generally does not work. 7467The second case is nevertheless allowed to be able to perform a block copy 7468from or to the array. 7469 7470Moreover, the use of type punning or aliasing to toggle the storage order 7471is not supported; that is to say, a given scalar object cannot be accessed 7472through distinct types that assign a different storage order to it. 7473 7474@item transparent_union 7475@cindex @code{transparent_union} type attribute 7476 7477This attribute, attached to a @code{union} type definition, indicates 7478that any function parameter having that union type causes calls to that 7479function to be treated in a special way. 7480 7481First, the argument corresponding to a transparent union type can be of 7482any type in the union; no cast is required. Also, if the union contains 7483a pointer type, the corresponding argument can be a null pointer 7484constant or a void pointer expression; and if the union contains a void 7485pointer type, the corresponding argument can be any pointer expression. 7486If the union member type is a pointer, qualifiers like @code{const} on 7487the referenced type must be respected, just as with normal pointer 7488conversions. 7489 7490Second, the argument is passed to the function using the calling 7491conventions of the first member of the transparent union, not the calling 7492conventions of the union itself. All members of the union must have the 7493same machine representation; this is necessary for this argument passing 7494to work properly. 7495 7496Transparent unions are designed for library functions that have multiple 7497interfaces for compatibility reasons. For example, suppose the 7498@code{wait} function must accept either a value of type @code{int *} to 7499comply with POSIX, or a value of type @code{union wait *} to comply with 7500the 4.1BSD interface. If @code{wait}'s parameter were @code{void *}, 7501@code{wait} would accept both kinds of arguments, but it would also 7502accept any other pointer type and this would make argument type checking 7503less useful. Instead, @code{<sys/wait.h>} might define the interface 7504as follows: 7505 7506@smallexample 7507typedef union __attribute__ ((__transparent_union__)) 7508 @{ 7509 int *__ip; 7510 union wait *__up; 7511 @} wait_status_ptr_t; 7512 7513pid_t wait (wait_status_ptr_t); 7514@end smallexample 7515 7516@noindent 7517This interface allows either @code{int *} or @code{union wait *} 7518arguments to be passed, using the @code{int *} calling convention. 7519The program can call @code{wait} with arguments of either type: 7520 7521@smallexample 7522int w1 () @{ int w; return wait (&w); @} 7523int w2 () @{ union wait w; return wait (&w); @} 7524@end smallexample 7525 7526@noindent 7527With this interface, @code{wait}'s implementation might look like this: 7528 7529@smallexample 7530pid_t wait (wait_status_ptr_t p) 7531@{ 7532 return waitpid (-1, p.__ip, 0); 7533@} 7534@end smallexample 7535 7536@item unused 7537@cindex @code{unused} type attribute 7538When attached to a type (including a @code{union} or a @code{struct}), 7539this attribute means that variables of that type are meant to appear 7540possibly unused. GCC does not produce a warning for any variables of 7541that type, even if the variable appears to do nothing. This is often 7542the case with lock or thread classes, which are usually defined and then 7543not referenced, but contain constructors and destructors that have 7544nontrivial bookkeeping functions. 7545 7546@item visibility 7547@cindex @code{visibility} type attribute 7548In C++, attribute visibility (@pxref{Function Attributes}) can also be 7549applied to class, struct, union and enum types. Unlike other type 7550attributes, the attribute must appear between the initial keyword and 7551the name of the type; it cannot appear after the body of the type. 7552 7553Note that the type visibility is applied to vague linkage entities 7554associated with the class (vtable, typeinfo node, etc.). In 7555particular, if a class is thrown as an exception in one shared object 7556and caught in another, the class must have default visibility. 7557Otherwise the two shared objects are unable to use the same 7558typeinfo node and exception handling will break. 7559 7560@end table 7561 7562To specify multiple attributes, separate them by commas within the 7563double parentheses: for example, @samp{__attribute__ ((aligned (16), 7564packed))}. 7565 7566@node ARC Type Attributes 7567@subsection ARC Type Attributes 7568 7569@cindex @code{uncached} type attribute, ARC 7570Declaring objects with @code{uncached} allows you to exclude 7571data-cache participation in load and store operations on those objects 7572without involving the additional semantic implications of 7573@code{volatile}. The @code{.di} instruction suffix is used for all 7574loads and stores of data declared @code{uncached}. 7575 7576@node ARM Type Attributes 7577@subsection ARM Type Attributes 7578 7579@cindex @code{notshared} type attribute, ARM 7580On those ARM targets that support @code{dllimport} (such as Symbian 7581OS), you can use the @code{notshared} attribute to indicate that the 7582virtual table and other similar data for a class should not be 7583exported from a DLL@. For example: 7584 7585@smallexample 7586class __declspec(notshared) C @{ 7587public: 7588 __declspec(dllimport) C(); 7589 virtual void f(); 7590@} 7591 7592__declspec(dllexport) 7593C::C() @{@} 7594@end smallexample 7595 7596@noindent 7597In this code, @code{C::C} is exported from the current DLL, but the 7598virtual table for @code{C} is not exported. (You can use 7599@code{__attribute__} instead of @code{__declspec} if you prefer, but 7600most Symbian OS code uses @code{__declspec}.) 7601 7602@node MeP Type Attributes 7603@subsection MeP Type Attributes 7604 7605@cindex @code{based} type attribute, MeP 7606@cindex @code{tiny} type attribute, MeP 7607@cindex @code{near} type attribute, MeP 7608@cindex @code{far} type attribute, MeP 7609Many of the MeP variable attributes may be applied to types as well. 7610Specifically, the @code{based}, @code{tiny}, @code{near}, and 7611@code{far} attributes may be applied to either. The @code{io} and 7612@code{cb} attributes may not be applied to types. 7613 7614@node PowerPC Type Attributes 7615@subsection PowerPC Type Attributes 7616 7617Three attributes currently are defined for PowerPC configurations: 7618@code{altivec}, @code{ms_struct} and @code{gcc_struct}. 7619 7620@cindex @code{ms_struct} type attribute, PowerPC 7621@cindex @code{gcc_struct} type attribute, PowerPC 7622For full documentation of the @code{ms_struct} and @code{gcc_struct} 7623attributes please see the documentation in @ref{x86 Type Attributes}. 7624 7625@cindex @code{altivec} type attribute, PowerPC 7626The @code{altivec} attribute allows one to declare AltiVec vector data 7627types supported by the AltiVec Programming Interface Manual. The 7628attribute requires an argument to specify one of three vector types: 7629@code{vector__}, @code{pixel__} (always followed by unsigned short), 7630and @code{bool__} (always followed by unsigned). 7631 7632@smallexample 7633__attribute__((altivec(vector__))) 7634__attribute__((altivec(pixel__))) unsigned short 7635__attribute__((altivec(bool__))) unsigned 7636@end smallexample 7637 7638These attributes mainly are intended to support the @code{__vector}, 7639@code{__pixel}, and @code{__bool} AltiVec keywords. 7640 7641@node SPU Type Attributes 7642@subsection SPU Type Attributes 7643 7644@cindex @code{spu_vector} type attribute, SPU 7645The SPU supports the @code{spu_vector} attribute for types. This attribute 7646allows one to declare vector data types supported by the Sony/Toshiba/IBM SPU 7647Language Extensions Specification. It is intended to support the 7648@code{__vector} keyword. 7649 7650@node x86 Type Attributes 7651@subsection x86 Type Attributes 7652 7653Two attributes are currently defined for x86 configurations: 7654@code{ms_struct} and @code{gcc_struct}. 7655 7656@table @code 7657 7658@item ms_struct 7659@itemx gcc_struct 7660@cindex @code{ms_struct} type attribute, x86 7661@cindex @code{gcc_struct} type attribute, x86 7662 7663If @code{packed} is used on a structure, or if bit-fields are used 7664it may be that the Microsoft ABI packs them differently 7665than GCC normally packs them. Particularly when moving packed 7666data between functions compiled with GCC and the native Microsoft compiler 7667(either via function call or as data in a file), it may be necessary to access 7668either format. 7669 7670The @code{ms_struct} and @code{gcc_struct} attributes correspond 7671to the @option{-mms-bitfields} and @option{-mno-ms-bitfields} 7672command-line options, respectively; 7673see @ref{x86 Options}, for details of how structure layout is affected. 7674@xref{x86 Variable Attributes}, for information about the corresponding 7675attributes on variables. 7676 7677@end table 7678 7679@node Label Attributes 7680@section Label Attributes 7681@cindex Label Attributes 7682 7683GCC allows attributes to be set on C labels. @xref{Attribute Syntax}, for 7684details of the exact syntax for using attributes. Other attributes are 7685available for functions (@pxref{Function Attributes}), variables 7686(@pxref{Variable Attributes}), enumerators (@pxref{Enumerator Attributes}), 7687statements (@pxref{Statement Attributes}), and for types 7688(@pxref{Type Attributes}). 7689 7690This example uses the @code{cold} label attribute to indicate the 7691@code{ErrorHandling} branch is unlikely to be taken and that the 7692@code{ErrorHandling} label is unused: 7693 7694@smallexample 7695 7696 asm goto ("some asm" : : : : NoError); 7697 7698/* This branch (the fall-through from the asm) is less commonly used */ 7699ErrorHandling: 7700 __attribute__((cold, unused)); /* Semi-colon is required here */ 7701 printf("error\n"); 7702 return 0; 7703 7704NoError: 7705 printf("no error\n"); 7706 return 1; 7707@end smallexample 7708 7709@table @code 7710@item unused 7711@cindex @code{unused} label attribute 7712This feature is intended for program-generated code that may contain 7713unused labels, but which is compiled with @option{-Wall}. It is 7714not normally appropriate to use in it human-written code, though it 7715could be useful in cases where the code that jumps to the label is 7716contained within an @code{#ifdef} conditional. 7717 7718@item hot 7719@cindex @code{hot} label attribute 7720The @code{hot} attribute on a label is used to inform the compiler that 7721the path following the label is more likely than paths that are not so 7722annotated. This attribute is used in cases where @code{__builtin_expect} 7723cannot be used, for instance with computed goto or @code{asm goto}. 7724 7725@item cold 7726@cindex @code{cold} label attribute 7727The @code{cold} attribute on labels is used to inform the compiler that 7728the path following the label is unlikely to be executed. This attribute 7729is used in cases where @code{__builtin_expect} cannot be used, for instance 7730with computed goto or @code{asm goto}. 7731 7732@end table 7733 7734@node Enumerator Attributes 7735@section Enumerator Attributes 7736@cindex Enumerator Attributes 7737 7738GCC allows attributes to be set on enumerators. @xref{Attribute Syntax}, for 7739details of the exact syntax for using attributes. Other attributes are 7740available for functions (@pxref{Function Attributes}), variables 7741(@pxref{Variable Attributes}), labels (@pxref{Label Attributes}), statements 7742(@pxref{Statement Attributes}), and for types (@pxref{Type Attributes}). 7743 7744This example uses the @code{deprecated} enumerator attribute to indicate the 7745@code{oldval} enumerator is deprecated: 7746 7747@smallexample 7748enum E @{ 7749 oldval __attribute__((deprecated)), 7750 newval 7751@}; 7752 7753int 7754fn (void) 7755@{ 7756 return oldval; 7757@} 7758@end smallexample 7759 7760@table @code 7761@item deprecated 7762@cindex @code{deprecated} enumerator attribute 7763The @code{deprecated} attribute results in a warning if the enumerator 7764is used anywhere in the source file. This is useful when identifying 7765enumerators that are expected to be removed in a future version of a 7766program. The warning also includes the location of the declaration 7767of the deprecated enumerator, to enable users to easily find further 7768information about why the enumerator is deprecated, or what they should 7769do instead. Note that the warnings only occurs for uses. 7770 7771@end table 7772 7773@node Statement Attributes 7774@section Statement Attributes 7775@cindex Statement Attributes 7776 7777GCC allows attributes to be set on null statements. @xref{Attribute Syntax}, 7778for details of the exact syntax for using attributes. Other attributes are 7779available for functions (@pxref{Function Attributes}), variables 7780(@pxref{Variable Attributes}), labels (@pxref{Label Attributes}), enumerators 7781(@pxref{Enumerator Attributes}), and for types (@pxref{Type Attributes}). 7782 7783This example uses the @code{fallthrough} statement attribute to indicate that 7784the @option{-Wimplicit-fallthrough} warning should not be emitted: 7785 7786@smallexample 7787switch (cond) 7788 @{ 7789 case 1: 7790 bar (1); 7791 __attribute__((fallthrough)); 7792 case 2: 7793 @dots{} 7794 @} 7795@end smallexample 7796 7797@table @code 7798@item fallthrough 7799@cindex @code{fallthrough} statement attribute 7800The @code{fallthrough} attribute with a null statement serves as a 7801fallthrough statement. It hints to the compiler that a statement 7802that falls through to another case label, or user-defined label 7803in a switch statement is intentional and thus the 7804@option{-Wimplicit-fallthrough} warning must not trigger. The 7805fallthrough attribute may appear at most once in each attribute 7806list, and may not be mixed with other attributes. It can only 7807be used in a switch statement (the compiler will issue an error 7808otherwise), after a preceding statement and before a logically 7809succeeding case label, or user-defined label. 7810 7811@end table 7812 7813@node Attribute Syntax 7814@section Attribute Syntax 7815@cindex attribute syntax 7816 7817This section describes the syntax with which @code{__attribute__} may be 7818used, and the constructs to which attribute specifiers bind, for the C 7819language. Some details may vary for C++ and Objective-C@. Because of 7820infelicities in the grammar for attributes, some forms described here 7821may not be successfully parsed in all cases. 7822 7823There are some problems with the semantics of attributes in C++. For 7824example, there are no manglings for attributes, although they may affect 7825code generation, so problems may arise when attributed types are used in 7826conjunction with templates or overloading. Similarly, @code{typeid} 7827does not distinguish between types with different attributes. Support 7828for attributes in C++ may be restricted in future to attributes on 7829declarations only, but not on nested declarators. 7830 7831@xref{Function Attributes}, for details of the semantics of attributes 7832applying to functions. @xref{Variable Attributes}, for details of the 7833semantics of attributes applying to variables. @xref{Type Attributes}, 7834for details of the semantics of attributes applying to structure, union 7835and enumerated types. 7836@xref{Label Attributes}, for details of the semantics of attributes 7837applying to labels. 7838@xref{Enumerator Attributes}, for details of the semantics of attributes 7839applying to enumerators. 7840@xref{Statement Attributes}, for details of the semantics of attributes 7841applying to statements. 7842 7843An @dfn{attribute specifier} is of the form 7844@code{__attribute__ ((@var{attribute-list}))}. An @dfn{attribute list} 7845is a possibly empty comma-separated sequence of @dfn{attributes}, where 7846each attribute is one of the following: 7847 7848@itemize @bullet 7849@item 7850Empty. Empty attributes are ignored. 7851 7852@item 7853An attribute name 7854(which may be an identifier such as @code{unused}, or a reserved 7855word such as @code{const}). 7856 7857@item 7858An attribute name followed by a parenthesized list of 7859parameters for the attribute. 7860These parameters take one of the following forms: 7861 7862@itemize @bullet 7863@item 7864An identifier. For example, @code{mode} attributes use this form. 7865 7866@item 7867An identifier followed by a comma and a non-empty comma-separated list 7868of expressions. For example, @code{format} attributes use this form. 7869 7870@item 7871A possibly empty comma-separated list of expressions. For example, 7872@code{format_arg} attributes use this form with the list being a single 7873integer constant expression, and @code{alias} attributes use this form 7874with the list being a single string constant. 7875@end itemize 7876@end itemize 7877 7878An @dfn{attribute specifier list} is a sequence of one or more attribute 7879specifiers, not separated by any other tokens. 7880 7881You may optionally specify attribute names with @samp{__} 7882preceding and following the name. 7883This allows you to use them in header files without 7884being concerned about a possible macro of the same name. For example, 7885you may use the attribute name @code{__noreturn__} instead of @code{noreturn}. 7886 7887 7888@subsubheading Label Attributes 7889 7890In GNU C, an attribute specifier list may appear after the colon following a 7891label, other than a @code{case} or @code{default} label. GNU C++ only permits 7892attributes on labels if the attribute specifier is immediately 7893followed by a semicolon (i.e., the label applies to an empty 7894statement). If the semicolon is missing, C++ label attributes are 7895ambiguous, as it is permissible for a declaration, which could begin 7896with an attribute list, to be labelled in C++. Declarations cannot be 7897labelled in C90 or C99, so the ambiguity does not arise there. 7898 7899@subsubheading Enumerator Attributes 7900 7901In GNU C, an attribute specifier list may appear as part of an enumerator. 7902The attribute goes after the enumeration constant, before @code{=}, if 7903present. The optional attribute in the enumerator appertains to the 7904enumeration constant. It is not possible to place the attribute after 7905the constant expression, if present. 7906 7907@subsubheading Statement Attributes 7908In GNU C, an attribute specifier list may appear as part of a null 7909statement. The attribute goes before the semicolon. 7910 7911@subsubheading Type Attributes 7912 7913An attribute specifier list may appear as part of a @code{struct}, 7914@code{union} or @code{enum} specifier. It may go either immediately 7915after the @code{struct}, @code{union} or @code{enum} keyword, or after 7916the closing brace. The former syntax is preferred. 7917Where attribute specifiers follow the closing brace, they are considered 7918to relate to the structure, union or enumerated type defined, not to any 7919enclosing declaration the type specifier appears in, and the type 7920defined is not complete until after the attribute specifiers. 7921@c Otherwise, there would be the following problems: a shift/reduce 7922@c conflict between attributes binding the struct/union/enum and 7923@c binding to the list of specifiers/qualifiers; and "aligned" 7924@c attributes could use sizeof for the structure, but the size could be 7925@c changed later by "packed" attributes. 7926 7927 7928@subsubheading All other attributes 7929 7930Otherwise, an attribute specifier appears as part of a declaration, 7931counting declarations of unnamed parameters and type names, and relates 7932to that declaration (which may be nested in another declaration, for 7933example in the case of a parameter declaration), or to a particular declarator 7934within a declaration. Where an 7935attribute specifier is applied to a parameter declared as a function or 7936an array, it should apply to the function or array rather than the 7937pointer to which the parameter is implicitly converted, but this is not 7938yet correctly implemented. 7939 7940Any list of specifiers and qualifiers at the start of a declaration may 7941contain attribute specifiers, whether or not such a list may in that 7942context contain storage class specifiers. (Some attributes, however, 7943are essentially in the nature of storage class specifiers, and only make 7944sense where storage class specifiers may be used; for example, 7945@code{section}.) There is one necessary limitation to this syntax: the 7946first old-style parameter declaration in a function definition cannot 7947begin with an attribute specifier, because such an attribute applies to 7948the function instead by syntax described below (which, however, is not 7949yet implemented in this case). In some other cases, attribute 7950specifiers are permitted by this grammar but not yet supported by the 7951compiler. All attribute specifiers in this place relate to the 7952declaration as a whole. In the obsolescent usage where a type of 7953@code{int} is implied by the absence of type specifiers, such a list of 7954specifiers and qualifiers may be an attribute specifier list with no 7955other specifiers or qualifiers. 7956 7957At present, the first parameter in a function prototype must have some 7958type specifier that is not an attribute specifier; this resolves an 7959ambiguity in the interpretation of @code{void f(int 7960(__attribute__((foo)) x))}, but is subject to change. At present, if 7961the parentheses of a function declarator contain only attributes then 7962those attributes are ignored, rather than yielding an error or warning 7963or implying a single parameter of type int, but this is subject to 7964change. 7965 7966An attribute specifier list may appear immediately before a declarator 7967(other than the first) in a comma-separated list of declarators in a 7968declaration of more than one identifier using a single list of 7969specifiers and qualifiers. Such attribute specifiers apply 7970only to the identifier before whose declarator they appear. For 7971example, in 7972 7973@smallexample 7974__attribute__((noreturn)) void d0 (void), 7975 __attribute__((format(printf, 1, 2))) d1 (const char *, ...), 7976 d2 (void); 7977@end smallexample 7978 7979@noindent 7980the @code{noreturn} attribute applies to all the functions 7981declared; the @code{format} attribute only applies to @code{d1}. 7982 7983An attribute specifier list may appear immediately before the comma, 7984@code{=} or semicolon terminating the declaration of an identifier other 7985than a function definition. Such attribute specifiers apply 7986to the declared object or function. Where an 7987assembler name for an object or function is specified (@pxref{Asm 7988Labels}), the attribute must follow the @code{asm} 7989specification. 7990 7991An attribute specifier list may, in future, be permitted to appear after 7992the declarator in a function definition (before any old-style parameter 7993declarations or the function body). 7994 7995Attribute specifiers may be mixed with type qualifiers appearing inside 7996the @code{[]} of a parameter array declarator, in the C99 construct by 7997which such qualifiers are applied to the pointer to which the array is 7998implicitly converted. Such attribute specifiers apply to the pointer, 7999not to the array, but at present this is not implemented and they are 8000ignored. 8001 8002An attribute specifier list may appear at the start of a nested 8003declarator. At present, there are some limitations in this usage: the 8004attributes correctly apply to the declarator, but for most individual 8005attributes the semantics this implies are not implemented. 8006When attribute specifiers follow the @code{*} of a pointer 8007declarator, they may be mixed with any type qualifiers present. 8008The following describes the formal semantics of this syntax. It makes the 8009most sense if you are familiar with the formal specification of 8010declarators in the ISO C standard. 8011 8012Consider (as in C99 subclause 6.7.5 paragraph 4) a declaration @code{T 8013D1}, where @code{T} contains declaration specifiers that specify a type 8014@var{Type} (such as @code{int}) and @code{D1} is a declarator that 8015contains an identifier @var{ident}. The type specified for @var{ident} 8016for derived declarators whose type does not include an attribute 8017specifier is as in the ISO C standard. 8018 8019If @code{D1} has the form @code{( @var{attribute-specifier-list} D )}, 8020and the declaration @code{T D} specifies the type 8021``@var{derived-declarator-type-list} @var{Type}'' for @var{ident}, then 8022@code{T D1} specifies the type ``@var{derived-declarator-type-list} 8023@var{attribute-specifier-list} @var{Type}'' for @var{ident}. 8024 8025If @code{D1} has the form @code{* 8026@var{type-qualifier-and-attribute-specifier-list} D}, and the 8027declaration @code{T D} specifies the type 8028``@var{derived-declarator-type-list} @var{Type}'' for @var{ident}, then 8029@code{T D1} specifies the type ``@var{derived-declarator-type-list} 8030@var{type-qualifier-and-attribute-specifier-list} pointer to @var{Type}'' for 8031@var{ident}. 8032 8033For example, 8034 8035@smallexample 8036void (__attribute__((noreturn)) ****f) (void); 8037@end smallexample 8038 8039@noindent 8040specifies the type ``pointer to pointer to pointer to pointer to 8041non-returning function returning @code{void}''. As another example, 8042 8043@smallexample 8044char *__attribute__((aligned(8))) *f; 8045@end smallexample 8046 8047@noindent 8048specifies the type ``pointer to 8-byte-aligned pointer to @code{char}''. 8049Note again that this does not work with most attributes; for example, 8050the usage of @samp{aligned} and @samp{noreturn} attributes given above 8051is not yet supported. 8052 8053For compatibility with existing code written for compiler versions that 8054did not implement attributes on nested declarators, some laxity is 8055allowed in the placing of attributes. If an attribute that only applies 8056to types is applied to a declaration, it is treated as applying to 8057the type of that declaration. If an attribute that only applies to 8058declarations is applied to the type of a declaration, it is treated 8059as applying to that declaration; and, for compatibility with code 8060placing the attributes immediately before the identifier declared, such 8061an attribute applied to a function return type is treated as 8062applying to the function type, and such an attribute applied to an array 8063element type is treated as applying to the array type. If an 8064attribute that only applies to function types is applied to a 8065pointer-to-function type, it is treated as applying to the pointer 8066target type; if such an attribute is applied to a function return type 8067that is not a pointer-to-function type, it is treated as applying 8068to the function type. 8069 8070@node Function Prototypes 8071@section Prototypes and Old-Style Function Definitions 8072@cindex function prototype declarations 8073@cindex old-style function definitions 8074@cindex promotion of formal parameters 8075 8076GNU C extends ISO C to allow a function prototype to override a later 8077old-style non-prototype definition. Consider the following example: 8078 8079@smallexample 8080/* @r{Use prototypes unless the compiler is old-fashioned.} */ 8081#ifdef __STDC__ 8082#define P(x) x 8083#else 8084#define P(x) () 8085#endif 8086 8087/* @r{Prototype function declaration.} */ 8088int isroot P((uid_t)); 8089 8090/* @r{Old-style function definition.} */ 8091int 8092isroot (x) /* @r{??? lossage here ???} */ 8093 uid_t x; 8094@{ 8095 return x == 0; 8096@} 8097@end smallexample 8098 8099Suppose the type @code{uid_t} happens to be @code{short}. ISO C does 8100not allow this example, because subword arguments in old-style 8101non-prototype definitions are promoted. Therefore in this example the 8102function definition's argument is really an @code{int}, which does not 8103match the prototype argument type of @code{short}. 8104 8105This restriction of ISO C makes it hard to write code that is portable 8106to traditional C compilers, because the programmer does not know 8107whether the @code{uid_t} type is @code{short}, @code{int}, or 8108@code{long}. Therefore, in cases like these GNU C allows a prototype 8109to override a later old-style definition. More precisely, in GNU C, a 8110function prototype argument type overrides the argument type specified 8111by a later old-style definition if the former type is the same as the 8112latter type before promotion. Thus in GNU C the above example is 8113equivalent to the following: 8114 8115@smallexample 8116int isroot (uid_t); 8117 8118int 8119isroot (uid_t x) 8120@{ 8121 return x == 0; 8122@} 8123@end smallexample 8124 8125@noindent 8126GNU C++ does not support old-style function definitions, so this 8127extension is irrelevant. 8128 8129@node C++ Comments 8130@section C++ Style Comments 8131@cindex @code{//} 8132@cindex C++ comments 8133@cindex comments, C++ style 8134 8135In GNU C, you may use C++ style comments, which start with @samp{//} and 8136continue until the end of the line. Many other C implementations allow 8137such comments, and they are included in the 1999 C standard. However, 8138C++ style comments are not recognized if you specify an @option{-std} 8139option specifying a version of ISO C before C99, or @option{-ansi} 8140(equivalent to @option{-std=c90}). 8141 8142@node Dollar Signs 8143@section Dollar Signs in Identifier Names 8144@cindex $ 8145@cindex dollar signs in identifier names 8146@cindex identifier names, dollar signs in 8147 8148In GNU C, you may normally use dollar signs in identifier names. 8149This is because many traditional C implementations allow such identifiers. 8150However, dollar signs in identifiers are not supported on a few target 8151machines, typically because the target assembler does not allow them. 8152 8153@node Character Escapes 8154@section The Character @key{ESC} in Constants 8155 8156You can use the sequence @samp{\e} in a string or character constant to 8157stand for the ASCII character @key{ESC}. 8158 8159@node Alignment 8160@section Inquiring on Alignment of Types or Variables 8161@cindex alignment 8162@cindex type alignment 8163@cindex variable alignment 8164 8165The keyword @code{__alignof__} allows you to inquire about how an object 8166is aligned, or the minimum alignment usually required by a type. Its 8167syntax is just like @code{sizeof}. 8168 8169For example, if the target machine requires a @code{double} value to be 8170aligned on an 8-byte boundary, then @code{__alignof__ (double)} is 8. 8171This is true on many RISC machines. On more traditional machine 8172designs, @code{__alignof__ (double)} is 4 or even 2. 8173 8174Some machines never actually require alignment; they allow reference to any 8175data type even at an odd address. For these machines, @code{__alignof__} 8176reports the smallest alignment that GCC gives the data type, usually as 8177mandated by the target ABI. 8178 8179If the operand of @code{__alignof__} is an lvalue rather than a type, 8180its value is the required alignment for its type, taking into account 8181any minimum alignment specified with GCC's @code{__attribute__} 8182extension (@pxref{Variable Attributes}). For example, after this 8183declaration: 8184 8185@smallexample 8186struct foo @{ int x; char y; @} foo1; 8187@end smallexample 8188 8189@noindent 8190the value of @code{__alignof__ (foo1.y)} is 1, even though its actual 8191alignment is probably 2 or 4, the same as @code{__alignof__ (int)}. 8192 8193It is an error to ask for the alignment of an incomplete type. 8194 8195 8196@node Inline 8197@section An Inline Function is As Fast As a Macro 8198@cindex inline functions 8199@cindex integrating function code 8200@cindex open coding 8201@cindex macros, inline alternative 8202 8203By declaring a function inline, you can direct GCC to make 8204calls to that function faster. One way GCC can achieve this is to 8205integrate that function's code into the code for its callers. This 8206makes execution faster by eliminating the function-call overhead; in 8207addition, if any of the actual argument values are constant, their 8208known values may permit simplifications at compile time so that not 8209all of the inline function's code needs to be included. The effect on 8210code size is less predictable; object code may be larger or smaller 8211with function inlining, depending on the particular case. You can 8212also direct GCC to try to integrate all ``simple enough'' functions 8213into their callers with the option @option{-finline-functions}. 8214 8215GCC implements three different semantics of declaring a function 8216inline. One is available with @option{-std=gnu89} or 8217@option{-fgnu89-inline} or when @code{gnu_inline} attribute is present 8218on all inline declarations, another when 8219@option{-std=c99}, 8220@option{-std=gnu99} or an option for a later C version is used 8221(without @option{-fgnu89-inline}), and the third 8222is used when compiling C++. 8223 8224To declare a function inline, use the @code{inline} keyword in its 8225declaration, like this: 8226 8227@smallexample 8228static inline int 8229inc (int *a) 8230@{ 8231 return (*a)++; 8232@} 8233@end smallexample 8234 8235If you are writing a header file to be included in ISO C90 programs, write 8236@code{__inline__} instead of @code{inline}. @xref{Alternate Keywords}. 8237 8238The three types of inlining behave similarly in two important cases: 8239when the @code{inline} keyword is used on a @code{static} function, 8240like the example above, and when a function is first declared without 8241using the @code{inline} keyword and then is defined with 8242@code{inline}, like this: 8243 8244@smallexample 8245extern int inc (int *a); 8246inline int 8247inc (int *a) 8248@{ 8249 return (*a)++; 8250@} 8251@end smallexample 8252 8253In both of these common cases, the program behaves the same as if you 8254had not used the @code{inline} keyword, except for its speed. 8255 8256@cindex inline functions, omission of 8257@opindex fkeep-inline-functions 8258When a function is both inline and @code{static}, if all calls to the 8259function are integrated into the caller, and the function's address is 8260never used, then the function's own assembler code is never referenced. 8261In this case, GCC does not actually output assembler code for the 8262function, unless you specify the option @option{-fkeep-inline-functions}. 8263If there is a nonintegrated call, then the function is compiled to 8264assembler code as usual. The function must also be compiled as usual if 8265the program refers to its address, because that cannot be inlined. 8266 8267@opindex Winline 8268Note that certain usages in a function definition can make it unsuitable 8269for inline substitution. Among these usages are: variadic functions, 8270use of @code{alloca}, use of computed goto (@pxref{Labels as Values}), 8271use of nonlocal goto, use of nested functions, use of @code{setjmp}, use 8272of @code{__builtin_longjmp} and use of @code{__builtin_return} or 8273@code{__builtin_apply_args}. Using @option{-Winline} warns when a 8274function marked @code{inline} could not be substituted, and gives the 8275reason for the failure. 8276 8277@cindex automatic @code{inline} for C++ member fns 8278@cindex @code{inline} automatic for C++ member fns 8279@cindex member fns, automatically @code{inline} 8280@cindex C++ member fns, automatically @code{inline} 8281@opindex fno-default-inline 8282As required by ISO C++, GCC considers member functions defined within 8283the body of a class to be marked inline even if they are 8284not explicitly declared with the @code{inline} keyword. You can 8285override this with @option{-fno-default-inline}; @pxref{C++ Dialect 8286Options,,Options Controlling C++ Dialect}. 8287 8288GCC does not inline any functions when not optimizing unless you specify 8289the @samp{always_inline} attribute for the function, like this: 8290 8291@smallexample 8292/* @r{Prototype.} */ 8293inline void foo (const char) __attribute__((always_inline)); 8294@end smallexample 8295 8296The remainder of this section is specific to GNU C90 inlining. 8297 8298@cindex non-static inline function 8299When an inline function is not @code{static}, then the compiler must assume 8300that there may be calls from other source files; since a global symbol can 8301be defined only once in any program, the function must not be defined in 8302the other source files, so the calls therein cannot be integrated. 8303Therefore, a non-@code{static} inline function is always compiled on its 8304own in the usual fashion. 8305 8306If you specify both @code{inline} and @code{extern} in the function 8307definition, then the definition is used only for inlining. In no case 8308is the function compiled on its own, not even if you refer to its 8309address explicitly. Such an address becomes an external reference, as 8310if you had only declared the function, and had not defined it. 8311 8312This combination of @code{inline} and @code{extern} has almost the 8313effect of a macro. The way to use it is to put a function definition in 8314a header file with these keywords, and put another copy of the 8315definition (lacking @code{inline} and @code{extern}) in a library file. 8316The definition in the header file causes most calls to the function 8317to be inlined. If any uses of the function remain, they refer to 8318the single copy in the library. 8319 8320@node Volatiles 8321@section When is a Volatile Object Accessed? 8322@cindex accessing volatiles 8323@cindex volatile read 8324@cindex volatile write 8325@cindex volatile access 8326 8327C has the concept of volatile objects. These are normally accessed by 8328pointers and used for accessing hardware or inter-thread 8329communication. The standard encourages compilers to refrain from 8330optimizations concerning accesses to volatile objects, but leaves it 8331implementation defined as to what constitutes a volatile access. The 8332minimum requirement is that at a sequence point all previous accesses 8333to volatile objects have stabilized and no subsequent accesses have 8334occurred. Thus an implementation is free to reorder and combine 8335volatile accesses that occur between sequence points, but cannot do 8336so for accesses across a sequence point. The use of volatile does 8337not allow you to violate the restriction on updating objects multiple 8338times between two sequence points. 8339 8340Accesses to non-volatile objects are not ordered with respect to 8341volatile accesses. You cannot use a volatile object as a memory 8342barrier to order a sequence of writes to non-volatile memory. For 8343instance: 8344 8345@smallexample 8346int *ptr = @var{something}; 8347volatile int vobj; 8348*ptr = @var{something}; 8349vobj = 1; 8350@end smallexample 8351 8352@noindent 8353Unless @var{*ptr} and @var{vobj} can be aliased, it is not guaranteed 8354that the write to @var{*ptr} occurs by the time the update 8355of @var{vobj} happens. If you need this guarantee, you must use 8356a stronger memory barrier such as: 8357 8358@smallexample 8359int *ptr = @var{something}; 8360volatile int vobj; 8361*ptr = @var{something}; 8362asm volatile ("" : : : "memory"); 8363vobj = 1; 8364@end smallexample 8365 8366A scalar volatile object is read when it is accessed in a void context: 8367 8368@smallexample 8369volatile int *src = @var{somevalue}; 8370*src; 8371@end smallexample 8372 8373Such expressions are rvalues, and GCC implements this as a 8374read of the volatile object being pointed to. 8375 8376Assignments are also expressions and have an rvalue. However when 8377assigning to a scalar volatile, the volatile object is not reread, 8378regardless of whether the assignment expression's rvalue is used or 8379not. If the assignment's rvalue is used, the value is that assigned 8380to the volatile object. For instance, there is no read of @var{vobj} 8381in all the following cases: 8382 8383@smallexample 8384int obj; 8385volatile int vobj; 8386vobj = @var{something}; 8387obj = vobj = @var{something}; 8388obj ? vobj = @var{onething} : vobj = @var{anotherthing}; 8389obj = (@var{something}, vobj = @var{anotherthing}); 8390@end smallexample 8391 8392If you need to read the volatile object after an assignment has 8393occurred, you must use a separate expression with an intervening 8394sequence point. 8395 8396As bit-fields are not individually addressable, volatile bit-fields may 8397be implicitly read when written to, or when adjacent bit-fields are 8398accessed. Bit-field operations may be optimized such that adjacent 8399bit-fields are only partially accessed, if they straddle a storage unit 8400boundary. For these reasons it is unwise to use volatile bit-fields to 8401access hardware. 8402 8403@node Using Assembly Language with C 8404@section How to Use Inline Assembly Language in C Code 8405@cindex @code{asm} keyword 8406@cindex assembly language in C 8407@cindex inline assembly language 8408@cindex mixing assembly language and C 8409 8410The @code{asm} keyword allows you to embed assembler instructions 8411within C code. GCC provides two forms of inline @code{asm} 8412statements. A @dfn{basic @code{asm}} statement is one with no 8413operands (@pxref{Basic Asm}), while an @dfn{extended @code{asm}} 8414statement (@pxref{Extended Asm}) includes one or more operands. 8415The extended form is preferred for mixing C and assembly language 8416within a function, but to include assembly language at 8417top level you must use basic @code{asm}. 8418 8419You can also use the @code{asm} keyword to override the assembler name 8420for a C symbol, or to place a C variable in a specific register. 8421 8422@menu 8423* Basic Asm:: Inline assembler without operands. 8424* Extended Asm:: Inline assembler with operands. 8425* Constraints:: Constraints for @code{asm} operands 8426* Asm Labels:: Specifying the assembler name to use for a C symbol. 8427* Explicit Register Variables:: Defining variables residing in specified 8428 registers. 8429* Size of an asm:: How GCC calculates the size of an @code{asm} block. 8430@end menu 8431 8432@node Basic Asm 8433@subsection Basic Asm --- Assembler Instructions Without Operands 8434@cindex basic @code{asm} 8435@cindex assembly language in C, basic 8436 8437A basic @code{asm} statement has the following syntax: 8438 8439@example 8440asm @var{asm-qualifiers} ( @var{AssemblerInstructions} ) 8441@end example 8442 8443The @code{asm} keyword is a GNU extension. 8444When writing code that can be compiled with @option{-ansi} and the 8445various @option{-std} options, use @code{__asm__} instead of 8446@code{asm} (@pxref{Alternate Keywords}). 8447 8448@subsubheading Qualifiers 8449@table @code 8450@item volatile 8451The optional @code{volatile} qualifier has no effect. 8452All basic @code{asm} blocks are implicitly volatile. 8453 8454@item inline 8455If you use the @code{inline} qualifier, then for inlining purposes the size 8456of the asm is taken as the smallest size possible (@pxref{Size of an asm}). 8457@end table 8458 8459@subsubheading Parameters 8460@table @var 8461 8462@item AssemblerInstructions 8463This is a literal string that specifies the assembler code. The string can 8464contain any instructions recognized by the assembler, including directives. 8465GCC does not parse the assembler instructions themselves and 8466does not know what they mean or even whether they are valid assembler input. 8467 8468You may place multiple assembler instructions together in a single @code{asm} 8469string, separated by the characters normally used in assembly code for the 8470system. A combination that works in most places is a newline to break the 8471line, plus a tab character (written as @samp{\n\t}). 8472Some assemblers allow semicolons as a line separator. However, 8473note that some assembler dialects use semicolons to start a comment. 8474@end table 8475 8476@subsubheading Remarks 8477Using extended @code{asm} (@pxref{Extended Asm}) typically produces 8478smaller, safer, and more efficient code, and in most cases it is a 8479better solution than basic @code{asm}. However, there are two 8480situations where only basic @code{asm} can be used: 8481 8482@itemize @bullet 8483@item 8484Extended @code{asm} statements have to be inside a C 8485function, so to write inline assembly language at file scope (``top-level''), 8486outside of C functions, you must use basic @code{asm}. 8487You can use this technique to emit assembler directives, 8488define assembly language macros that can be invoked elsewhere in the file, 8489or write entire functions in assembly language. 8490 8491@item 8492Functions declared 8493with the @code{naked} attribute also require basic @code{asm} 8494(@pxref{Function Attributes}). 8495@end itemize 8496 8497Safely accessing C data and calling functions from basic @code{asm} is more 8498complex than it may appear. To access C data, it is better to use extended 8499@code{asm}. 8500 8501Do not expect a sequence of @code{asm} statements to remain perfectly 8502consecutive after compilation. If certain instructions need to remain 8503consecutive in the output, put them in a single multi-instruction @code{asm} 8504statement. Note that GCC's optimizers can move @code{asm} statements 8505relative to other code, including across jumps. 8506 8507@code{asm} statements may not perform jumps into other @code{asm} statements. 8508GCC does not know about these jumps, and therefore cannot take 8509account of them when deciding how to optimize. Jumps from @code{asm} to C 8510labels are only supported in extended @code{asm}. 8511 8512Under certain circumstances, GCC may duplicate (or remove duplicates of) your 8513assembly code when optimizing. This can lead to unexpected duplicate 8514symbol errors during compilation if your assembly code defines symbols or 8515labels. 8516 8517@strong{Warning:} The C standards do not specify semantics for @code{asm}, 8518making it a potential source of incompatibilities between compilers. These 8519incompatibilities may not produce compiler warnings/errors. 8520 8521GCC does not parse basic @code{asm}'s @var{AssemblerInstructions}, which 8522means there is no way to communicate to the compiler what is happening 8523inside them. GCC has no visibility of symbols in the @code{asm} and may 8524discard them as unreferenced. It also does not know about side effects of 8525the assembler code, such as modifications to memory or registers. Unlike 8526some compilers, GCC assumes that no changes to general purpose registers 8527occur. This assumption may change in a future release. 8528 8529To avoid complications from future changes to the semantics and the 8530compatibility issues between compilers, consider replacing basic @code{asm} 8531with extended @code{asm}. See 8532@uref{https://gcc.gnu.org/wiki/ConvertBasicAsmToExtended, How to convert 8533from basic asm to extended asm} for information about how to perform this 8534conversion. 8535 8536The compiler copies the assembler instructions in a basic @code{asm} 8537verbatim to the assembly language output file, without 8538processing dialects or any of the @samp{%} operators that are available with 8539extended @code{asm}. This results in minor differences between basic 8540@code{asm} strings and extended @code{asm} templates. For example, to refer to 8541registers you might use @samp{%eax} in basic @code{asm} and 8542@samp{%%eax} in extended @code{asm}. 8543 8544On targets such as x86 that support multiple assembler dialects, 8545all basic @code{asm} blocks use the assembler dialect specified by the 8546@option{-masm} command-line option (@pxref{x86 Options}). 8547Basic @code{asm} provides no 8548mechanism to provide different assembler strings for different dialects. 8549 8550For basic @code{asm} with non-empty assembler string GCC assumes 8551the assembler block does not change any general purpose registers, 8552but it may read or write any globally accessible variable. 8553 8554Here is an example of basic @code{asm} for i386: 8555 8556@example 8557/* Note that this code will not compile with -masm=intel */ 8558#define DebugBreak() asm("int $3") 8559@end example 8560 8561@node Extended Asm 8562@subsection Extended Asm - Assembler Instructions with C Expression Operands 8563@cindex extended @code{asm} 8564@cindex assembly language in C, extended 8565 8566With extended @code{asm} you can read and write C variables from 8567assembler and perform jumps from assembler code to C labels. 8568Extended @code{asm} syntax uses colons (@samp{:}) to delimit 8569the operand parameters after the assembler template: 8570 8571@example 8572asm @var{asm-qualifiers} ( @var{AssemblerTemplate} 8573 : @var{OutputOperands} 8574 @r{[} : @var{InputOperands} 8575 @r{[} : @var{Clobbers} @r{]} @r{]}) 8576 8577asm @var{asm-qualifiers} ( @var{AssemblerTemplate} 8578 : 8579 : @var{InputOperands} 8580 : @var{Clobbers} 8581 : @var{GotoLabels}) 8582@end example 8583where in the last form, @var{asm-qualifiers} contains @code{goto} (and in the 8584first form, not). 8585 8586The @code{asm} keyword is a GNU extension. 8587When writing code that can be compiled with @option{-ansi} and the 8588various @option{-std} options, use @code{__asm__} instead of 8589@code{asm} (@pxref{Alternate Keywords}). 8590 8591@subsubheading Qualifiers 8592@table @code 8593 8594@item volatile 8595The typical use of extended @code{asm} statements is to manipulate input 8596values to produce output values. However, your @code{asm} statements may 8597also produce side effects. If so, you may need to use the @code{volatile} 8598qualifier to disable certain optimizations. @xref{Volatile}. 8599 8600@item inline 8601If you use the @code{inline} qualifier, then for inlining purposes the size 8602of the asm is taken as the smallest size possible (@pxref{Size of an asm}). 8603 8604@item goto 8605This qualifier informs the compiler that the @code{asm} statement may 8606perform a jump to one of the labels listed in the @var{GotoLabels}. 8607@xref{GotoLabels}. 8608@end table 8609 8610@subsubheading Parameters 8611@table @var 8612@item AssemblerTemplate 8613This is a literal string that is the template for the assembler code. It is a 8614combination of fixed text and tokens that refer to the input, output, 8615and goto parameters. @xref{AssemblerTemplate}. 8616 8617@item OutputOperands 8618A comma-separated list of the C variables modified by the instructions in the 8619@var{AssemblerTemplate}. An empty list is permitted. @xref{OutputOperands}. 8620 8621@item InputOperands 8622A comma-separated list of C expressions read by the instructions in the 8623@var{AssemblerTemplate}. An empty list is permitted. @xref{InputOperands}. 8624 8625@item Clobbers 8626A comma-separated list of registers or other values changed by the 8627@var{AssemblerTemplate}, beyond those listed as outputs. 8628An empty list is permitted. @xref{Clobbers and Scratch Registers}. 8629 8630@item GotoLabels 8631When you are using the @code{goto} form of @code{asm}, this section contains 8632the list of all C labels to which the code in the 8633@var{AssemblerTemplate} may jump. 8634@xref{GotoLabels}. 8635 8636@code{asm} statements may not perform jumps into other @code{asm} statements, 8637only to the listed @var{GotoLabels}. 8638GCC's optimizers do not know about other jumps; therefore they cannot take 8639account of them when deciding how to optimize. 8640@end table 8641 8642The total number of input + output + goto operands is limited to 30. 8643 8644@subsubheading Remarks 8645The @code{asm} statement allows you to include assembly instructions directly 8646within C code. This may help you to maximize performance in time-sensitive 8647code or to access assembly instructions that are not readily available to C 8648programs. 8649 8650Note that extended @code{asm} statements must be inside a function. Only 8651basic @code{asm} may be outside functions (@pxref{Basic Asm}). 8652Functions declared with the @code{naked} attribute also require basic 8653@code{asm} (@pxref{Function Attributes}). 8654 8655While the uses of @code{asm} are many and varied, it may help to think of an 8656@code{asm} statement as a series of low-level instructions that convert input 8657parameters to output parameters. So a simple (if not particularly useful) 8658example for i386 using @code{asm} might look like this: 8659 8660@example 8661int src = 1; 8662int dst; 8663 8664asm ("mov %1, %0\n\t" 8665 "add $1, %0" 8666 : "=r" (dst) 8667 : "r" (src)); 8668 8669printf("%d\n", dst); 8670@end example 8671 8672This code copies @code{src} to @code{dst} and add 1 to @code{dst}. 8673 8674@anchor{Volatile} 8675@subsubsection Volatile 8676@cindex volatile @code{asm} 8677@cindex @code{asm} volatile 8678 8679GCC's optimizers sometimes discard @code{asm} statements if they determine 8680there is no need for the output variables. Also, the optimizers may move 8681code out of loops if they believe that the code will always return the same 8682result (i.e. none of its input values change between calls). Using the 8683@code{volatile} qualifier disables these optimizations. @code{asm} statements 8684that have no output operands, including @code{asm goto} statements, 8685are implicitly volatile. 8686 8687This i386 code demonstrates a case that does not use (or require) the 8688@code{volatile} qualifier. If it is performing assertion checking, this code 8689uses @code{asm} to perform the validation. Otherwise, @code{dwRes} is 8690unreferenced by any code. As a result, the optimizers can discard the 8691@code{asm} statement, which in turn removes the need for the entire 8692@code{DoCheck} routine. By omitting the @code{volatile} qualifier when it 8693isn't needed you allow the optimizers to produce the most efficient code 8694possible. 8695 8696@example 8697void DoCheck(uint32_t dwSomeValue) 8698@{ 8699 uint32_t dwRes; 8700 8701 // Assumes dwSomeValue is not zero. 8702 asm ("bsfl %1,%0" 8703 : "=r" (dwRes) 8704 : "r" (dwSomeValue) 8705 : "cc"); 8706 8707 assert(dwRes > 3); 8708@} 8709@end example 8710 8711The next example shows a case where the optimizers can recognize that the input 8712(@code{dwSomeValue}) never changes during the execution of the function and can 8713therefore move the @code{asm} outside the loop to produce more efficient code. 8714Again, using @code{volatile} disables this type of optimization. 8715 8716@example 8717void do_print(uint32_t dwSomeValue) 8718@{ 8719 uint32_t dwRes; 8720 8721 for (uint32_t x=0; x < 5; x++) 8722 @{ 8723 // Assumes dwSomeValue is not zero. 8724 asm ("bsfl %1,%0" 8725 : "=r" (dwRes) 8726 : "r" (dwSomeValue) 8727 : "cc"); 8728 8729 printf("%u: %u %u\n", x, dwSomeValue, dwRes); 8730 @} 8731@} 8732@end example 8733 8734The following example demonstrates a case where you need to use the 8735@code{volatile} qualifier. 8736It uses the x86 @code{rdtsc} instruction, which reads 8737the computer's time-stamp counter. Without the @code{volatile} qualifier, 8738the optimizers might assume that the @code{asm} block will always return the 8739same value and therefore optimize away the second call. 8740 8741@example 8742uint64_t msr; 8743 8744asm volatile ( "rdtsc\n\t" // Returns the time in EDX:EAX. 8745 "shl $32, %%rdx\n\t" // Shift the upper bits left. 8746 "or %%rdx, %0" // 'Or' in the lower bits. 8747 : "=a" (msr) 8748 : 8749 : "rdx"); 8750 8751printf("msr: %llx\n", msr); 8752 8753// Do other work... 8754 8755// Reprint the timestamp 8756asm volatile ( "rdtsc\n\t" // Returns the time in EDX:EAX. 8757 "shl $32, %%rdx\n\t" // Shift the upper bits left. 8758 "or %%rdx, %0" // 'Or' in the lower bits. 8759 : "=a" (msr) 8760 : 8761 : "rdx"); 8762 8763printf("msr: %llx\n", msr); 8764@end example 8765 8766GCC's optimizers do not treat this code like the non-volatile code in the 8767earlier examples. They do not move it out of loops or omit it on the 8768assumption that the result from a previous call is still valid. 8769 8770Note that the compiler can move even volatile @code{asm} instructions relative 8771to other code, including across jump instructions. For example, on many 8772targets there is a system register that controls the rounding mode of 8773floating-point operations. Setting it with a volatile @code{asm}, as in the 8774following PowerPC example, does not work reliably. 8775 8776@example 8777asm volatile("mtfsf 255, %0" : : "f" (fpenv)); 8778sum = x + y; 8779@end example 8780 8781The compiler may move the addition back before the volatile @code{asm}. To 8782make it work as expected, add an artificial dependency to the @code{asm} by 8783referencing a variable in the subsequent code, for example: 8784 8785@example 8786asm volatile ("mtfsf 255,%1" : "=X" (sum) : "f" (fpenv)); 8787sum = x + y; 8788@end example 8789 8790Under certain circumstances, GCC may duplicate (or remove duplicates of) your 8791assembly code when optimizing. This can lead to unexpected duplicate symbol 8792errors during compilation if your asm code defines symbols or labels. 8793Using @samp{%=} 8794(@pxref{AssemblerTemplate}) may help resolve this problem. 8795 8796@anchor{AssemblerTemplate} 8797@subsubsection Assembler Template 8798@cindex @code{asm} assembler template 8799 8800An assembler template is a literal string containing assembler instructions. 8801The compiler replaces tokens in the template that refer 8802to inputs, outputs, and goto labels, 8803and then outputs the resulting string to the assembler. The 8804string can contain any instructions recognized by the assembler, including 8805directives. GCC does not parse the assembler instructions 8806themselves and does not know what they mean or even whether they are valid 8807assembler input. However, it does count the statements 8808(@pxref{Size of an asm}). 8809 8810You may place multiple assembler instructions together in a single @code{asm} 8811string, separated by the characters normally used in assembly code for the 8812system. A combination that works in most places is a newline to break the 8813line, plus a tab character to move to the instruction field (written as 8814@samp{\n\t}). 8815Some assemblers allow semicolons as a line separator. However, note 8816that some assembler dialects use semicolons to start a comment. 8817 8818Do not expect a sequence of @code{asm} statements to remain perfectly 8819consecutive after compilation, even when you are using the @code{volatile} 8820qualifier. If certain instructions need to remain consecutive in the output, 8821put them in a single multi-instruction asm statement. 8822 8823Accessing data from C programs without using input/output operands (such as 8824by using global symbols directly from the assembler template) may not work as 8825expected. Similarly, calling functions directly from an assembler template 8826requires a detailed understanding of the target assembler and ABI. 8827 8828Since GCC does not parse the assembler template, 8829it has no visibility of any 8830symbols it references. This may result in GCC discarding those symbols as 8831unreferenced unless they are also listed as input, output, or goto operands. 8832 8833@subsubheading Special format strings 8834 8835In addition to the tokens described by the input, output, and goto operands, 8836these tokens have special meanings in the assembler template: 8837 8838@table @samp 8839@item %% 8840Outputs a single @samp{%} into the assembler code. 8841 8842@item %= 8843Outputs a number that is unique to each instance of the @code{asm} 8844statement in the entire compilation. This option is useful when creating local 8845labels and referring to them multiple times in a single template that 8846generates multiple assembler instructions. 8847 8848@item %@{ 8849@itemx %| 8850@itemx %@} 8851Outputs @samp{@{}, @samp{|}, and @samp{@}} characters (respectively) 8852into the assembler code. When unescaped, these characters have special 8853meaning to indicate multiple assembler dialects, as described below. 8854@end table 8855 8856@subsubheading Multiple assembler dialects in @code{asm} templates 8857 8858On targets such as x86, GCC supports multiple assembler dialects. 8859The @option{-masm} option controls which dialect GCC uses as its 8860default for inline assembler. The target-specific documentation for the 8861@option{-masm} option contains the list of supported dialects, as well as the 8862default dialect if the option is not specified. This information may be 8863important to understand, since assembler code that works correctly when 8864compiled using one dialect will likely fail if compiled using another. 8865@xref{x86 Options}. 8866 8867If your code needs to support multiple assembler dialects (for example, if 8868you are writing public headers that need to support a variety of compilation 8869options), use constructs of this form: 8870 8871@example 8872@{ dialect0 | dialect1 | dialect2... @} 8873@end example 8874 8875This construct outputs @code{dialect0} 8876when using dialect #0 to compile the code, 8877@code{dialect1} for dialect #1, etc. If there are fewer alternatives within the 8878braces than the number of dialects the compiler supports, the construct 8879outputs nothing. 8880 8881For example, if an x86 compiler supports two dialects 8882(@samp{att}, @samp{intel}), an 8883assembler template such as this: 8884 8885@example 8886"bt@{l %[Offset],%[Base] | %[Base],%[Offset]@}; jc %l2" 8887@end example 8888 8889@noindent 8890is equivalent to one of 8891 8892@example 8893"btl %[Offset],%[Base] ; jc %l2" @r{/* att dialect */} 8894"bt %[Base],%[Offset]; jc %l2" @r{/* intel dialect */} 8895@end example 8896 8897Using that same compiler, this code: 8898 8899@example 8900"xchg@{l@}\t@{%%@}ebx, %1" 8901@end example 8902 8903@noindent 8904corresponds to either 8905 8906@example 8907"xchgl\t%%ebx, %1" @r{/* att dialect */} 8908"xchg\tebx, %1" @r{/* intel dialect */} 8909@end example 8910 8911There is no support for nesting dialect alternatives. 8912 8913@anchor{OutputOperands} 8914@subsubsection Output Operands 8915@cindex @code{asm} output operands 8916 8917An @code{asm} statement has zero or more output operands indicating the names 8918of C variables modified by the assembler code. 8919 8920In this i386 example, @code{old} (referred to in the template string as 8921@code{%0}) and @code{*Base} (as @code{%1}) are outputs and @code{Offset} 8922(@code{%2}) is an input: 8923 8924@example 8925bool old; 8926 8927__asm__ ("btsl %2,%1\n\t" // Turn on zero-based bit #Offset in Base. 8928 "sbb %0,%0" // Use the CF to calculate old. 8929 : "=r" (old), "+rm" (*Base) 8930 : "Ir" (Offset) 8931 : "cc"); 8932 8933return old; 8934@end example 8935 8936Operands are separated by commas. Each operand has this format: 8937 8938@example 8939@r{[} [@var{asmSymbolicName}] @r{]} @var{constraint} (@var{cvariablename}) 8940@end example 8941 8942@table @var 8943@item asmSymbolicName 8944Specifies a symbolic name for the operand. 8945Reference the name in the assembler template 8946by enclosing it in square brackets 8947(i.e. @samp{%[Value]}). The scope of the name is the @code{asm} statement 8948that contains the definition. Any valid C variable name is acceptable, 8949including names already defined in the surrounding code. No two operands 8950within the same @code{asm} statement can use the same symbolic name. 8951 8952When not using an @var{asmSymbolicName}, use the (zero-based) position 8953of the operand 8954in the list of operands in the assembler template. For example if there are 8955three output operands, use @samp{%0} in the template to refer to the first, 8956@samp{%1} for the second, and @samp{%2} for the third. 8957 8958@item constraint 8959A string constant specifying constraints on the placement of the operand; 8960@xref{Constraints}, for details. 8961 8962Output constraints must begin with either @samp{=} (a variable overwriting an 8963existing value) or @samp{+} (when reading and writing). When using 8964@samp{=}, do not assume the location contains the existing value 8965on entry to the @code{asm}, except 8966when the operand is tied to an input; @pxref{InputOperands,,Input Operands}. 8967 8968After the prefix, there must be one or more additional constraints 8969(@pxref{Constraints}) that describe where the value resides. Common 8970constraints include @samp{r} for register and @samp{m} for memory. 8971When you list more than one possible location (for example, @code{"=rm"}), 8972the compiler chooses the most efficient one based on the current context. 8973If you list as many alternates as the @code{asm} statement allows, you permit 8974the optimizers to produce the best possible code. 8975If you must use a specific register, but your Machine Constraints do not 8976provide sufficient control to select the specific register you want, 8977local register variables may provide a solution (@pxref{Local Register 8978Variables}). 8979 8980@item cvariablename 8981Specifies a C lvalue expression to hold the output, typically a variable name. 8982The enclosing parentheses are a required part of the syntax. 8983 8984@end table 8985 8986When the compiler selects the registers to use to 8987represent the output operands, it does not use any of the clobbered registers 8988(@pxref{Clobbers and Scratch Registers}). 8989 8990Output operand expressions must be lvalues. The compiler cannot check whether 8991the operands have data types that are reasonable for the instruction being 8992executed. For output expressions that are not directly addressable (for 8993example a bit-field), the constraint must allow a register. In that case, GCC 8994uses the register as the output of the @code{asm}, and then stores that 8995register into the output. 8996 8997Operands using the @samp{+} constraint modifier count as two operands 8998(that is, both as input and output) towards the total maximum of 30 operands 8999per @code{asm} statement. 9000 9001Use the @samp{&} constraint modifier (@pxref{Modifiers}) on all output 9002operands that must not overlap an input. Otherwise, 9003GCC may allocate the output operand in the same register as an unrelated 9004input operand, on the assumption that the assembler code consumes its 9005inputs before producing outputs. This assumption may be false if the assembler 9006code actually consists of more than one instruction. 9007 9008The same problem can occur if one output parameter (@var{a}) allows a register 9009constraint and another output parameter (@var{b}) allows a memory constraint. 9010The code generated by GCC to access the memory address in @var{b} can contain 9011registers which @emph{might} be shared by @var{a}, and GCC considers those 9012registers to be inputs to the asm. As above, GCC assumes that such input 9013registers are consumed before any outputs are written. This assumption may 9014result in incorrect behavior if the asm writes to @var{a} before using 9015@var{b}. Combining the @samp{&} modifier with the register constraint on @var{a} 9016ensures that modifying @var{a} does not affect the address referenced by 9017@var{b}. Otherwise, the location of @var{b} 9018is undefined if @var{a} is modified before using @var{b}. 9019 9020@code{asm} supports operand modifiers on operands (for example @samp{%k2} 9021instead of simply @samp{%2}). Typically these qualifiers are hardware 9022dependent. The list of supported modifiers for x86 is found at 9023@ref{x86Operandmodifiers,x86 Operand modifiers}. 9024 9025If the C code that follows the @code{asm} makes no use of any of the output 9026operands, use @code{volatile} for the @code{asm} statement to prevent the 9027optimizers from discarding the @code{asm} statement as unneeded 9028(see @ref{Volatile}). 9029 9030This code makes no use of the optional @var{asmSymbolicName}. Therefore it 9031references the first output operand as @code{%0} (were there a second, it 9032would be @code{%1}, etc). The number of the first input operand is one greater 9033than that of the last output operand. In this i386 example, that makes 9034@code{Mask} referenced as @code{%1}: 9035 9036@example 9037uint32_t Mask = 1234; 9038uint32_t Index; 9039 9040 asm ("bsfl %1, %0" 9041 : "=r" (Index) 9042 : "r" (Mask) 9043 : "cc"); 9044@end example 9045 9046That code overwrites the variable @code{Index} (@samp{=}), 9047placing the value in a register (@samp{r}). 9048Using the generic @samp{r} constraint instead of a constraint for a specific 9049register allows the compiler to pick the register to use, which can result 9050in more efficient code. This may not be possible if an assembler instruction 9051requires a specific register. 9052 9053The following i386 example uses the @var{asmSymbolicName} syntax. 9054It produces the 9055same result as the code above, but some may consider it more readable or more 9056maintainable since reordering index numbers is not necessary when adding or 9057removing operands. The names @code{aIndex} and @code{aMask} 9058are only used in this example to emphasize which 9059names get used where. 9060It is acceptable to reuse the names @code{Index} and @code{Mask}. 9061 9062@example 9063uint32_t Mask = 1234; 9064uint32_t Index; 9065 9066 asm ("bsfl %[aMask], %[aIndex]" 9067 : [aIndex] "=r" (Index) 9068 : [aMask] "r" (Mask) 9069 : "cc"); 9070@end example 9071 9072Here are some more examples of output operands. 9073 9074@example 9075uint32_t c = 1; 9076uint32_t d; 9077uint32_t *e = &c; 9078 9079asm ("mov %[e], %[d]" 9080 : [d] "=rm" (d) 9081 : [e] "rm" (*e)); 9082@end example 9083 9084Here, @code{d} may either be in a register or in memory. Since the compiler 9085might already have the current value of the @code{uint32_t} location 9086pointed to by @code{e} 9087in a register, you can enable it to choose the best location 9088for @code{d} by specifying both constraints. 9089 9090@anchor{FlagOutputOperands} 9091@subsubsection Flag Output Operands 9092@cindex @code{asm} flag output operands 9093 9094Some targets have a special register that holds the ``flags'' for the 9095result of an operation or comparison. Normally, the contents of that 9096register are either unmodifed by the asm, or the asm is considered to 9097clobber the contents. 9098 9099On some targets, a special form of output operand exists by which 9100conditions in the flags register may be outputs of the asm. The set of 9101conditions supported are target specific, but the general rule is that 9102the output variable must be a scalar integer, and the value is boolean. 9103When supported, the target defines the preprocessor symbol 9104@code{__GCC_ASM_FLAG_OUTPUTS__}. 9105 9106Because of the special nature of the flag output operands, the constraint 9107may not include alternatives. 9108 9109Most often, the target has only one flags register, and thus is an implied 9110operand of many instructions. In this case, the operand should not be 9111referenced within the assembler template via @code{%0} etc, as there's 9112no corresponding text in the assembly language. 9113 9114@table @asis 9115@item x86 family 9116The flag output constraints for the x86 family are of the form 9117@samp{=@@cc@var{cond}} where @var{cond} is one of the standard 9118conditions defined in the ISA manual for @code{j@var{cc}} or 9119@code{set@var{cc}}. 9120 9121@table @code 9122@item a 9123``above'' or unsigned greater than 9124@item ae 9125``above or equal'' or unsigned greater than or equal 9126@item b 9127``below'' or unsigned less than 9128@item be 9129``below or equal'' or unsigned less than or equal 9130@item c 9131carry flag set 9132@item e 9133@itemx z 9134``equal'' or zero flag set 9135@item g 9136signed greater than 9137@item ge 9138signed greater than or equal 9139@item l 9140signed less than 9141@item le 9142signed less than or equal 9143@item o 9144overflow flag set 9145@item p 9146parity flag set 9147@item s 9148sign flag set 9149@item na 9150@itemx nae 9151@itemx nb 9152@itemx nbe 9153@itemx nc 9154@itemx ne 9155@itemx ng 9156@itemx nge 9157@itemx nl 9158@itemx nle 9159@itemx no 9160@itemx np 9161@itemx ns 9162@itemx nz 9163``not'' @var{flag}, or inverted versions of those above 9164@end table 9165 9166@end table 9167 9168@anchor{InputOperands} 9169@subsubsection Input Operands 9170@cindex @code{asm} input operands 9171@cindex @code{asm} expressions 9172 9173Input operands make values from C variables and expressions available to the 9174assembly code. 9175 9176Operands are separated by commas. Each operand has this format: 9177 9178@example 9179@r{[} [@var{asmSymbolicName}] @r{]} @var{constraint} (@var{cexpression}) 9180@end example 9181 9182@table @var 9183@item asmSymbolicName 9184Specifies a symbolic name for the operand. 9185Reference the name in the assembler template 9186by enclosing it in square brackets 9187(i.e. @samp{%[Value]}). The scope of the name is the @code{asm} statement 9188that contains the definition. Any valid C variable name is acceptable, 9189including names already defined in the surrounding code. No two operands 9190within the same @code{asm} statement can use the same symbolic name. 9191 9192When not using an @var{asmSymbolicName}, use the (zero-based) position 9193of the operand 9194in the list of operands in the assembler template. For example if there are 9195two output operands and three inputs, 9196use @samp{%2} in the template to refer to the first input operand, 9197@samp{%3} for the second, and @samp{%4} for the third. 9198 9199@item constraint 9200A string constant specifying constraints on the placement of the operand; 9201@xref{Constraints}, for details. 9202 9203Input constraint strings may not begin with either @samp{=} or @samp{+}. 9204When you list more than one possible location (for example, @samp{"irm"}), 9205the compiler chooses the most efficient one based on the current context. 9206If you must use a specific register, but your Machine Constraints do not 9207provide sufficient control to select the specific register you want, 9208local register variables may provide a solution (@pxref{Local Register 9209Variables}). 9210 9211Input constraints can also be digits (for example, @code{"0"}). This indicates 9212that the specified input must be in the same place as the output constraint 9213at the (zero-based) index in the output constraint list. 9214When using @var{asmSymbolicName} syntax for the output operands, 9215you may use these names (enclosed in brackets @samp{[]}) instead of digits. 9216 9217@item cexpression 9218This is the C variable or expression being passed to the @code{asm} statement 9219as input. The enclosing parentheses are a required part of the syntax. 9220 9221@end table 9222 9223When the compiler selects the registers to use to represent the input 9224operands, it does not use any of the clobbered registers 9225(@pxref{Clobbers and Scratch Registers}). 9226 9227If there are no output operands but there are input operands, place two 9228consecutive colons where the output operands would go: 9229 9230@example 9231__asm__ ("some instructions" 9232 : /* No outputs. */ 9233 : "r" (Offset / 8)); 9234@end example 9235 9236@strong{Warning:} Do @emph{not} modify the contents of input-only operands 9237(except for inputs tied to outputs). The compiler assumes that on exit from 9238the @code{asm} statement these operands contain the same values as they 9239had before executing the statement. 9240It is @emph{not} possible to use clobbers 9241to inform the compiler that the values in these inputs are changing. One 9242common work-around is to tie the changing input variable to an output variable 9243that never gets used. Note, however, that if the code that follows the 9244@code{asm} statement makes no use of any of the output operands, the GCC 9245optimizers may discard the @code{asm} statement as unneeded 9246(see @ref{Volatile}). 9247 9248@code{asm} supports operand modifiers on operands (for example @samp{%k2} 9249instead of simply @samp{%2}). Typically these qualifiers are hardware 9250dependent. The list of supported modifiers for x86 is found at 9251@ref{x86Operandmodifiers,x86 Operand modifiers}. 9252 9253In this example using the fictitious @code{combine} instruction, the 9254constraint @code{"0"} for input operand 1 says that it must occupy the same 9255location as output operand 0. Only input operands may use numbers in 9256constraints, and they must each refer to an output operand. Only a number (or 9257the symbolic assembler name) in the constraint can guarantee that one operand 9258is in the same place as another. The mere fact that @code{foo} is the value of 9259both operands is not enough to guarantee that they are in the same place in 9260the generated assembler code. 9261 9262@example 9263asm ("combine %2, %0" 9264 : "=r" (foo) 9265 : "0" (foo), "g" (bar)); 9266@end example 9267 9268Here is an example using symbolic names. 9269 9270@example 9271asm ("cmoveq %1, %2, %[result]" 9272 : [result] "=r"(result) 9273 : "r" (test), "r" (new), "[result]" (old)); 9274@end example 9275 9276@anchor{Clobbers and Scratch Registers} 9277@subsubsection Clobbers and Scratch Registers 9278@cindex @code{asm} clobbers 9279@cindex @code{asm} scratch registers 9280 9281While the compiler is aware of changes to entries listed in the output 9282operands, the inline @code{asm} code may modify more than just the outputs. For 9283example, calculations may require additional registers, or the processor may 9284overwrite a register as a side effect of a particular assembler instruction. 9285In order to inform the compiler of these changes, list them in the clobber 9286list. Clobber list items are either register names or the special clobbers 9287(listed below). Each clobber list item is a string constant 9288enclosed in double quotes and separated by commas. 9289 9290Clobber descriptions may not in any way overlap with an input or output 9291operand. For example, you may not have an operand describing a register class 9292with one member when listing that register in the clobber list. Variables 9293declared to live in specific registers (@pxref{Explicit Register 9294Variables}) and used 9295as @code{asm} input or output operands must have no part mentioned in the 9296clobber description. In particular, there is no way to specify that input 9297operands get modified without also specifying them as output operands. 9298 9299When the compiler selects which registers to use to represent input and output 9300operands, it does not use any of the clobbered registers. As a result, 9301clobbered registers are available for any use in the assembler code. 9302 9303Here is a realistic example for the VAX showing the use of clobbered 9304registers: 9305 9306@example 9307asm volatile ("movc3 %0, %1, %2" 9308 : /* No outputs. */ 9309 : "g" (from), "g" (to), "g" (count) 9310 : "r0", "r1", "r2", "r3", "r4", "r5", "memory"); 9311@end example 9312 9313Also, there are two special clobber arguments: 9314 9315@table @code 9316@item "cc" 9317The @code{"cc"} clobber indicates that the assembler code modifies the flags 9318register. On some machines, GCC represents the condition codes as a specific 9319hardware register; @code{"cc"} serves to name this register. 9320On other machines, condition code handling is different, 9321and specifying @code{"cc"} has no effect. But 9322it is valid no matter what the target. 9323 9324@item "memory" 9325The @code{"memory"} clobber tells the compiler that the assembly code 9326performs memory 9327reads or writes to items other than those listed in the input and output 9328operands (for example, accessing the memory pointed to by one of the input 9329parameters). To ensure memory contains correct values, GCC may need to flush 9330specific register values to memory before executing the @code{asm}. Further, 9331the compiler does not assume that any values read from memory before an 9332@code{asm} remain unchanged after that @code{asm}; it reloads them as 9333needed. 9334Using the @code{"memory"} clobber effectively forms a read/write 9335memory barrier for the compiler. 9336 9337Note that this clobber does not prevent the @emph{processor} from doing 9338speculative reads past the @code{asm} statement. To prevent that, you need 9339processor-specific fence instructions. 9340 9341@end table 9342 9343Flushing registers to memory has performance implications and may be 9344an issue for time-sensitive code. You can provide better information 9345to GCC to avoid this, as shown in the following examples. At a 9346minimum, aliasing rules allow GCC to know what memory @emph{doesn't} 9347need to be flushed. 9348 9349Here is a fictitious sum of squares instruction, that takes two 9350pointers to floating point values in memory and produces a floating 9351point register output. 9352Notice that @code{x}, and @code{y} both appear twice in the @code{asm} 9353parameters, once to specify memory accessed, and once to specify a 9354base register used by the @code{asm}. You won't normally be wasting a 9355register by doing this as GCC can use the same register for both 9356purposes. However, it would be foolish to use both @code{%1} and 9357@code{%3} for @code{x} in this @code{asm} and expect them to be the 9358same. In fact, @code{%3} may well not be a register. It might be a 9359symbolic memory reference to the object pointed to by @code{x}. 9360 9361@smallexample 9362asm ("sumsq %0, %1, %2" 9363 : "+f" (result) 9364 : "r" (x), "r" (y), "m" (*x), "m" (*y)); 9365@end smallexample 9366 9367Here is a fictitious @code{*z++ = *x++ * *y++} instruction. 9368Notice that the @code{x}, @code{y} and @code{z} pointer registers 9369must be specified as input/output because the @code{asm} modifies 9370them. 9371 9372@smallexample 9373asm ("vecmul %0, %1, %2" 9374 : "+r" (z), "+r" (x), "+r" (y), "=m" (*z) 9375 : "m" (*x), "m" (*y)); 9376@end smallexample 9377 9378An x86 example where the string memory argument is of unknown length. 9379 9380@smallexample 9381asm("repne scasb" 9382 : "=c" (count), "+D" (p) 9383 : "m" (*(const char (*)[]) p), "0" (-1), "a" (0)); 9384@end smallexample 9385 9386If you know the above will only be reading a ten byte array then you 9387could instead use a memory input like: 9388@code{"m" (*(const char (*)[10]) p)}. 9389 9390Here is an example of a PowerPC vector scale implemented in assembly, 9391complete with vector and condition code clobbers, and some initialized 9392offset registers that are unchanged by the @code{asm}. 9393 9394@smallexample 9395void 9396dscal (size_t n, double *x, double alpha) 9397@{ 9398 asm ("/* lots of asm here */" 9399 : "+m" (*(double (*)[n]) x), "+&r" (n), "+b" (x) 9400 : "d" (alpha), "b" (32), "b" (48), "b" (64), 9401 "b" (80), "b" (96), "b" (112) 9402 : "cr0", 9403 "vs32","vs33","vs34","vs35","vs36","vs37","vs38","vs39", 9404 "vs40","vs41","vs42","vs43","vs44","vs45","vs46","vs47"); 9405@} 9406@end smallexample 9407 9408Rather than allocating fixed registers via clobbers to provide scratch 9409registers for an @code{asm} statement, an alternative is to define a 9410variable and make it an early-clobber output as with @code{a2} and 9411@code{a3} in the example below. This gives the compiler register 9412allocator more freedom. You can also define a variable and make it an 9413output tied to an input as with @code{a0} and @code{a1}, tied 9414respectively to @code{ap} and @code{lda}. Of course, with tied 9415outputs your @code{asm} can't use the input value after modifying the 9416output register since they are one and the same register. What's 9417more, if you omit the early-clobber on the output, it is possible that 9418GCC might allocate the same register to another of the inputs if GCC 9419could prove they had the same value on entry to the @code{asm}. This 9420is why @code{a1} has an early-clobber. Its tied input, @code{lda} 9421might conceivably be known to have the value 16 and without an 9422early-clobber share the same register as @code{%11}. On the other 9423hand, @code{ap} can't be the same as any of the other inputs, so an 9424early-clobber on @code{a0} is not needed. It is also not desirable in 9425this case. An early-clobber on @code{a0} would cause GCC to allocate 9426a separate register for the @code{"m" (*(const double (*)[]) ap)} 9427input. Note that tying an input to an output is the way to set up an 9428initialized temporary register modified by an @code{asm} statement. 9429An input not tied to an output is assumed by GCC to be unchanged, for 9430example @code{"b" (16)} below sets up @code{%11} to 16, and GCC might 9431use that register in following code if the value 16 happened to be 9432needed. You can even use a normal @code{asm} output for a scratch if 9433all inputs that might share the same register are consumed before the 9434scratch is used. The VSX registers clobbered by the @code{asm} 9435statement could have used this technique except for GCC's limit on the 9436number of @code{asm} parameters. 9437 9438@smallexample 9439static void 9440dgemv_kernel_4x4 (long n, const double *ap, long lda, 9441 const double *x, double *y, double alpha) 9442@{ 9443 double *a0; 9444 double *a1; 9445 double *a2; 9446 double *a3; 9447 9448 __asm__ 9449 ( 9450 /* lots of asm here */ 9451 "#n=%1 ap=%8=%12 lda=%13 x=%7=%10 y=%0=%2 alpha=%9 o16=%11\n" 9452 "#a0=%3 a1=%4 a2=%5 a3=%6" 9453 : 9454 "+m" (*(double (*)[n]) y), 9455 "+&r" (n), // 1 9456 "+b" (y), // 2 9457 "=b" (a0), // 3 9458 "=&b" (a1), // 4 9459 "=&b" (a2), // 5 9460 "=&b" (a3) // 6 9461 : 9462 "m" (*(const double (*)[n]) x), 9463 "m" (*(const double (*)[]) ap), 9464 "d" (alpha), // 9 9465 "r" (x), // 10 9466 "b" (16), // 11 9467 "3" (ap), // 12 9468 "4" (lda) // 13 9469 : 9470 "cr0", 9471 "vs32","vs33","vs34","vs35","vs36","vs37", 9472 "vs40","vs41","vs42","vs43","vs44","vs45","vs46","vs47" 9473 ); 9474@} 9475@end smallexample 9476 9477@anchor{GotoLabels} 9478@subsubsection Goto Labels 9479@cindex @code{asm} goto labels 9480 9481@code{asm goto} allows assembly code to jump to one or more C labels. The 9482@var{GotoLabels} section in an @code{asm goto} statement contains 9483a comma-separated 9484list of all C labels to which the assembler code may jump. GCC assumes that 9485@code{asm} execution falls through to the next statement (if this is not the 9486case, consider using the @code{__builtin_unreachable} intrinsic after the 9487@code{asm} statement). Optimization of @code{asm goto} may be improved by 9488using the @code{hot} and @code{cold} label attributes (@pxref{Label 9489Attributes}). 9490 9491An @code{asm goto} statement cannot have outputs. 9492This is due to an internal restriction of 9493the compiler: control transfer instructions cannot have outputs. 9494If the assembler code does modify anything, use the @code{"memory"} clobber 9495to force the 9496optimizers to flush all register values to memory and reload them if 9497necessary after the @code{asm} statement. 9498 9499Also note that an @code{asm goto} statement is always implicitly 9500considered volatile. 9501 9502To reference a label in the assembler template, 9503prefix it with @samp{%l} (lowercase @samp{L}) followed 9504by its (zero-based) position in @var{GotoLabels} plus the number of input 9505operands. For example, if the @code{asm} has three inputs and references two 9506labels, refer to the first label as @samp{%l3} and the second as @samp{%l4}). 9507 9508Alternately, you can reference labels using the actual C label name enclosed 9509in brackets. For example, to reference a label named @code{carry}, you can 9510use @samp{%l[carry]}. The label must still be listed in the @var{GotoLabels} 9511section when using this approach. 9512 9513Here is an example of @code{asm goto} for i386: 9514 9515@example 9516asm goto ( 9517 "btl %1, %0\n\t" 9518 "jc %l2" 9519 : /* No outputs. */ 9520 : "r" (p1), "r" (p2) 9521 : "cc" 9522 : carry); 9523 9524return 0; 9525 9526carry: 9527return 1; 9528@end example 9529 9530The following example shows an @code{asm goto} that uses a memory clobber. 9531 9532@example 9533int frob(int x) 9534@{ 9535 int y; 9536 asm goto ("frob %%r5, %1; jc %l[error]; mov (%2), %%r5" 9537 : /* No outputs. */ 9538 : "r"(x), "r"(&y) 9539 : "r5", "memory" 9540 : error); 9541 return y; 9542error: 9543 return -1; 9544@} 9545@end example 9546 9547@anchor{x86Operandmodifiers} 9548@subsubsection x86 Operand Modifiers 9549 9550References to input, output, and goto operands in the assembler template 9551of extended @code{asm} statements can use 9552modifiers to affect the way the operands are formatted in 9553the code output to the assembler. For example, the 9554following code uses the @samp{h} and @samp{b} modifiers for x86: 9555 9556@example 9557uint16_t num; 9558asm volatile ("xchg %h0, %b0" : "+a" (num) ); 9559@end example 9560 9561@noindent 9562These modifiers generate this assembler code: 9563 9564@example 9565xchg %ah, %al 9566@end example 9567 9568The rest of this discussion uses the following code for illustrative purposes. 9569 9570@example 9571int main() 9572@{ 9573 int iInt = 1; 9574 9575top: 9576 9577 asm volatile goto ("some assembler instructions here" 9578 : /* No outputs. */ 9579 : "q" (iInt), "X" (sizeof(unsigned char) + 1) 9580 : /* No clobbers. */ 9581 : top); 9582@} 9583@end example 9584 9585With no modifiers, this is what the output from the operands would be for the 9586@samp{att} and @samp{intel} dialects of assembler: 9587 9588@multitable {Operand} {$.L2} {OFFSET FLAT:.L2} 9589@headitem Operand @tab @samp{att} @tab @samp{intel} 9590@item @code{%0} 9591@tab @code{%eax} 9592@tab @code{eax} 9593@item @code{%1} 9594@tab @code{$2} 9595@tab @code{2} 9596@item @code{%2} 9597@tab @code{$.L2} 9598@tab @code{OFFSET FLAT:.L2} 9599@end multitable 9600 9601The table below shows the list of supported modifiers and their effects. 9602 9603@multitable {Modifier} {Print the opcode suffix for the size of th} {Operand} {@samp{att}} {@samp{intel}} 9604@headitem Modifier @tab Description @tab Operand @tab @samp{att} @tab @samp{intel} 9605@item @code{z} 9606@tab Print the opcode suffix for the size of the current integer operand (one of @code{b}/@code{w}/@code{l}/@code{q}). 9607@tab @code{%z0} 9608@tab @code{l} 9609@tab 9610@item @code{b} 9611@tab Print the QImode name of the register. 9612@tab @code{%b0} 9613@tab @code{%al} 9614@tab @code{al} 9615@item @code{h} 9616@tab Print the QImode name for a ``high'' register. 9617@tab @code{%h0} 9618@tab @code{%ah} 9619@tab @code{ah} 9620@item @code{w} 9621@tab Print the HImode name of the register. 9622@tab @code{%w0} 9623@tab @code{%ax} 9624@tab @code{ax} 9625@item @code{k} 9626@tab Print the SImode name of the register. 9627@tab @code{%k0} 9628@tab @code{%eax} 9629@tab @code{eax} 9630@item @code{q} 9631@tab Print the DImode name of the register. 9632@tab @code{%q0} 9633@tab @code{%rax} 9634@tab @code{rax} 9635@item @code{l} 9636@tab Print the label name with no punctuation. 9637@tab @code{%l2} 9638@tab @code{.L2} 9639@tab @code{.L2} 9640@item @code{c} 9641@tab Require a constant operand and print the constant expression with no punctuation. 9642@tab @code{%c1} 9643@tab @code{2} 9644@tab @code{2} 9645@end multitable 9646 9647@code{V} is a special modifier which prints the name of the full integer 9648register without @code{%}. 9649 9650@anchor{x86floatingpointasmoperands} 9651@subsubsection x86 Floating-Point @code{asm} Operands 9652 9653On x86 targets, there are several rules on the usage of stack-like registers 9654in the operands of an @code{asm}. These rules apply only to the operands 9655that are stack-like registers: 9656 9657@enumerate 9658@item 9659Given a set of input registers that die in an @code{asm}, it is 9660necessary to know which are implicitly popped by the @code{asm}, and 9661which must be explicitly popped by GCC@. 9662 9663An input register that is implicitly popped by the @code{asm} must be 9664explicitly clobbered, unless it is constrained to match an 9665output operand. 9666 9667@item 9668For any input register that is implicitly popped by an @code{asm}, it is 9669necessary to know how to adjust the stack to compensate for the pop. 9670If any non-popped input is closer to the top of the reg-stack than 9671the implicitly popped register, it would not be possible to know what the 9672stack looked like---it's not clear how the rest of the stack ``slides 9673up''. 9674 9675All implicitly popped input registers must be closer to the top of 9676the reg-stack than any input that is not implicitly popped. 9677 9678It is possible that if an input dies in an @code{asm}, the compiler might 9679use the input register for an output reload. Consider this example: 9680 9681@smallexample 9682asm ("foo" : "=t" (a) : "f" (b)); 9683@end smallexample 9684 9685@noindent 9686This code says that input @code{b} is not popped by the @code{asm}, and that 9687the @code{asm} pushes a result onto the reg-stack, i.e., the stack is one 9688deeper after the @code{asm} than it was before. But, it is possible that 9689reload may think that it can use the same register for both the input and 9690the output. 9691 9692To prevent this from happening, 9693if any input operand uses the @samp{f} constraint, all output register 9694constraints must use the @samp{&} early-clobber modifier. 9695 9696The example above is correctly written as: 9697 9698@smallexample 9699asm ("foo" : "=&t" (a) : "f" (b)); 9700@end smallexample 9701 9702@item 9703Some operands need to be in particular places on the stack. All 9704output operands fall in this category---GCC has no other way to 9705know which registers the outputs appear in unless you indicate 9706this in the constraints. 9707 9708Output operands must specifically indicate which register an output 9709appears in after an @code{asm}. @samp{=f} is not allowed: the operand 9710constraints must select a class with a single register. 9711 9712@item 9713Output operands may not be ``inserted'' between existing stack registers. 9714Since no 387 opcode uses a read/write operand, all output operands 9715are dead before the @code{asm}, and are pushed by the @code{asm}. 9716It makes no sense to push anywhere but the top of the reg-stack. 9717 9718Output operands must start at the top of the reg-stack: output 9719operands may not ``skip'' a register. 9720 9721@item 9722Some @code{asm} statements may need extra stack space for internal 9723calculations. This can be guaranteed by clobbering stack registers 9724unrelated to the inputs and outputs. 9725 9726@end enumerate 9727 9728This @code{asm} 9729takes one input, which is internally popped, and produces two outputs. 9730 9731@smallexample 9732asm ("fsincos" : "=t" (cos), "=u" (sin) : "0" (inp)); 9733@end smallexample 9734 9735@noindent 9736This @code{asm} takes two inputs, which are popped by the @code{fyl2xp1} opcode, 9737and replaces them with one output. The @code{st(1)} clobber is necessary 9738for the compiler to know that @code{fyl2xp1} pops both inputs. 9739 9740@smallexample 9741asm ("fyl2xp1" : "=t" (result) : "0" (x), "u" (y) : "st(1)"); 9742@end smallexample 9743 9744@lowersections 9745@include md.texi 9746@raisesections 9747 9748@node Asm Labels 9749@subsection Controlling Names Used in Assembler Code 9750@cindex assembler names for identifiers 9751@cindex names used in assembler code 9752@cindex identifiers, names in assembler code 9753 9754You can specify the name to be used in the assembler code for a C 9755function or variable by writing the @code{asm} (or @code{__asm__}) 9756keyword after the declarator. 9757It is up to you to make sure that the assembler names you choose do not 9758conflict with any other assembler symbols, or reference registers. 9759 9760@subsubheading Assembler names for data: 9761 9762This sample shows how to specify the assembler name for data: 9763 9764@smallexample 9765int foo asm ("myfoo") = 2; 9766@end smallexample 9767 9768@noindent 9769This specifies that the name to be used for the variable @code{foo} in 9770the assembler code should be @samp{myfoo} rather than the usual 9771@samp{_foo}. 9772 9773On systems where an underscore is normally prepended to the name of a C 9774variable, this feature allows you to define names for the 9775linker that do not start with an underscore. 9776 9777GCC does not support using this feature with a non-static local variable 9778since such variables do not have assembler names. If you are 9779trying to put the variable in a particular register, see 9780@ref{Explicit Register Variables}. 9781 9782@subsubheading Assembler names for functions: 9783 9784To specify the assembler name for functions, write a declaration for the 9785function before its definition and put @code{asm} there, like this: 9786 9787@smallexample 9788int func (int x, int y) asm ("MYFUNC"); 9789 9790int func (int x, int y) 9791@{ 9792 /* @r{@dots{}} */ 9793@end smallexample 9794 9795@noindent 9796This specifies that the name to be used for the function @code{func} in 9797the assembler code should be @code{MYFUNC}. 9798 9799@node Explicit Register Variables 9800@subsection Variables in Specified Registers 9801@anchor{Explicit Reg Vars} 9802@cindex explicit register variables 9803@cindex variables in specified registers 9804@cindex specified registers 9805 9806GNU C allows you to associate specific hardware registers with C 9807variables. In almost all cases, allowing the compiler to assign 9808registers produces the best code. However under certain unusual 9809circumstances, more precise control over the variable storage is 9810required. 9811 9812Both global and local variables can be associated with a register. The 9813consequences of performing this association are very different between 9814the two, as explained in the sections below. 9815 9816@menu 9817* Global Register Variables:: Variables declared at global scope. 9818* Local Register Variables:: Variables declared within a function. 9819@end menu 9820 9821@node Global Register Variables 9822@subsubsection Defining Global Register Variables 9823@anchor{Global Reg Vars} 9824@cindex global register variables 9825@cindex registers, global variables in 9826@cindex registers, global allocation 9827 9828You can define a global register variable and associate it with a specified 9829register like this: 9830 9831@smallexample 9832register int *foo asm ("r12"); 9833@end smallexample 9834 9835@noindent 9836Here @code{r12} is the name of the register that should be used. Note that 9837this is the same syntax used for defining local register variables, but for 9838a global variable the declaration appears outside a function. The 9839@code{register} keyword is required, and cannot be combined with 9840@code{static}. The register name must be a valid register name for the 9841target platform. 9842 9843Registers are a scarce resource on most systems and allowing the 9844compiler to manage their usage usually results in the best code. However, 9845under special circumstances it can make sense to reserve some globally. 9846For example this may be useful in programs such as programming language 9847interpreters that have a couple of global variables that are accessed 9848very often. 9849 9850After defining a global register variable, for the current compilation 9851unit: 9852 9853@itemize @bullet 9854@item The register is reserved entirely for this use, and will not be 9855allocated for any other purpose. 9856@item The register is not saved and restored by any functions. 9857@item Stores into this register are never deleted even if they appear to be 9858dead, but references may be deleted, moved or simplified. 9859@end itemize 9860 9861Note that these points @emph{only} apply to code that is compiled with the 9862definition. The behavior of code that is merely linked in (for example 9863code from libraries) is not affected. 9864 9865If you want to recompile source files that do not actually use your global 9866register variable so they do not use the specified register for any other 9867purpose, you need not actually add the global register declaration to 9868their source code. It suffices to specify the compiler option 9869@option{-ffixed-@var{reg}} (@pxref{Code Gen Options}) to reserve the 9870register. 9871 9872@subsubheading Declaring the variable 9873 9874Global register variables can not have initial values, because an 9875executable file has no means to supply initial contents for a register. 9876 9877When selecting a register, choose one that is normally saved and 9878restored by function calls on your machine. This ensures that code 9879which is unaware of this reservation (such as library routines) will 9880restore it before returning. 9881 9882On machines with register windows, be sure to choose a global 9883register that is not affected magically by the function call mechanism. 9884 9885@subsubheading Using the variable 9886 9887@cindex @code{qsort}, and global register variables 9888When calling routines that are not aware of the reservation, be 9889cautious if those routines call back into code which uses them. As an 9890example, if you call the system library version of @code{qsort}, it may 9891clobber your registers during execution, but (if you have selected 9892appropriate registers) it will restore them before returning. However 9893it will @emph{not} restore them before calling @code{qsort}'s comparison 9894function. As a result, global values will not reliably be available to 9895the comparison function unless the @code{qsort} function itself is rebuilt. 9896 9897Similarly, it is not safe to access the global register variables from signal 9898handlers or from more than one thread of control. Unless you recompile 9899them specially for the task at hand, the system library routines may 9900temporarily use the register for other things. 9901 9902@cindex register variable after @code{longjmp} 9903@cindex global register after @code{longjmp} 9904@cindex value after @code{longjmp} 9905@findex longjmp 9906@findex setjmp 9907On most machines, @code{longjmp} restores to each global register 9908variable the value it had at the time of the @code{setjmp}. On some 9909machines, however, @code{longjmp} does not change the value of global 9910register variables. To be portable, the function that called @code{setjmp} 9911should make other arrangements to save the values of the global register 9912variables, and to restore them in a @code{longjmp}. This way, the same 9913thing happens regardless of what @code{longjmp} does. 9914 9915Eventually there may be a way of asking the compiler to choose a register 9916automatically, but first we need to figure out how it should choose and 9917how to enable you to guide the choice. No solution is evident. 9918 9919@node Local Register Variables 9920@subsubsection Specifying Registers for Local Variables 9921@anchor{Local Reg Vars} 9922@cindex local variables, specifying registers 9923@cindex specifying registers for local variables 9924@cindex registers for local variables 9925 9926You can define a local register variable and associate it with a specified 9927register like this: 9928 9929@smallexample 9930register int *foo asm ("r12"); 9931@end smallexample 9932 9933@noindent 9934Here @code{r12} is the name of the register that should be used. Note 9935that this is the same syntax used for defining global register variables, 9936but for a local variable the declaration appears within a function. The 9937@code{register} keyword is required, and cannot be combined with 9938@code{static}. The register name must be a valid register name for the 9939target platform. 9940 9941As with global register variables, it is recommended that you choose 9942a register that is normally saved and restored by function calls on your 9943machine, so that calls to library routines will not clobber it. 9944 9945The only supported use for this feature is to specify registers 9946for input and output operands when calling Extended @code{asm} 9947(@pxref{Extended Asm}). This may be necessary if the constraints for a 9948particular machine don't provide sufficient control to select the desired 9949register. To force an operand into a register, create a local variable 9950and specify the register name after the variable's declaration. Then use 9951the local variable for the @code{asm} operand and specify any constraint 9952letter that matches the register: 9953 9954@smallexample 9955register int *p1 asm ("r0") = @dots{}; 9956register int *p2 asm ("r1") = @dots{}; 9957register int *result asm ("r0"); 9958asm ("sysint" : "=r" (result) : "0" (p1), "r" (p2)); 9959@end smallexample 9960 9961@emph{Warning:} In the above example, be aware that a register (for example 9962@code{r0}) can be call-clobbered by subsequent code, including function 9963calls and library calls for arithmetic operators on other variables (for 9964example the initialization of @code{p2}). In this case, use temporary 9965variables for expressions between the register assignments: 9966 9967@smallexample 9968int t1 = @dots{}; 9969register int *p1 asm ("r0") = @dots{}; 9970register int *p2 asm ("r1") = t1; 9971register int *result asm ("r0"); 9972asm ("sysint" : "=r" (result) : "0" (p1), "r" (p2)); 9973@end smallexample 9974 9975Defining a register variable does not reserve the register. Other than 9976when invoking the Extended @code{asm}, the contents of the specified 9977register are not guaranteed. For this reason, the following uses 9978are explicitly @emph{not} supported. If they appear to work, it is only 9979happenstance, and may stop working as intended due to (seemingly) 9980unrelated changes in surrounding code, or even minor changes in the 9981optimization of a future version of gcc: 9982 9983@itemize @bullet 9984@item Passing parameters to or from Basic @code{asm} 9985@item Passing parameters to or from Extended @code{asm} without using input 9986or output operands. 9987@item Passing parameters to or from routines written in assembler (or 9988other languages) using non-standard calling conventions. 9989@end itemize 9990 9991Some developers use Local Register Variables in an attempt to improve 9992gcc's allocation of registers, especially in large functions. In this 9993case the register name is essentially a hint to the register allocator. 9994While in some instances this can generate better code, improvements are 9995subject to the whims of the allocator/optimizers. Since there are no 9996guarantees that your improvements won't be lost, this usage of Local 9997Register Variables is discouraged. 9998 9999On the MIPS platform, there is related use for local register variables 10000with slightly different characteristics (@pxref{MIPS Coprocessors,, 10001Defining coprocessor specifics for MIPS targets, gccint, 10002GNU Compiler Collection (GCC) Internals}). 10003 10004@node Size of an asm 10005@subsection Size of an @code{asm} 10006 10007Some targets require that GCC track the size of each instruction used 10008in order to generate correct code. Because the final length of the 10009code produced by an @code{asm} statement is only known by the 10010assembler, GCC must make an estimate as to how big it will be. It 10011does this by counting the number of instructions in the pattern of the 10012@code{asm} and multiplying that by the length of the longest 10013instruction supported by that processor. (When working out the number 10014of instructions, it assumes that any occurrence of a newline or of 10015whatever statement separator character is supported by the assembler --- 10016typically @samp{;} --- indicates the end of an instruction.) 10017 10018Normally, GCC's estimate is adequate to ensure that correct 10019code is generated, but it is possible to confuse the compiler if you use 10020pseudo instructions or assembler macros that expand into multiple real 10021instructions, or if you use assembler directives that expand to more 10022space in the object file than is needed for a single instruction. 10023If this happens then the assembler may produce a diagnostic saying that 10024a label is unreachable. 10025 10026@cindex @code{asm inline} 10027This size is also used for inlining decisions. If you use @code{asm inline} 10028instead of just @code{asm}, then for inlining purposes the size of the asm 10029is taken as the minimum size, ignoring how many instructions GCC thinks it is. 10030 10031@node Alternate Keywords 10032@section Alternate Keywords 10033@cindex alternate keywords 10034@cindex keywords, alternate 10035 10036@option{-ansi} and the various @option{-std} options disable certain 10037keywords. This causes trouble when you want to use GNU C extensions, or 10038a general-purpose header file that should be usable by all programs, 10039including ISO C programs. The keywords @code{asm}, @code{typeof} and 10040@code{inline} are not available in programs compiled with 10041@option{-ansi} or @option{-std} (although @code{inline} can be used in a 10042program compiled with @option{-std=c99} or @option{-std=c11}). The 10043ISO C99 keyword 10044@code{restrict} is only available when @option{-std=gnu99} (which will 10045eventually be the default) or @option{-std=c99} (or the equivalent 10046@option{-std=iso9899:1999}), or an option for a later standard 10047version, is used. 10048 10049The way to solve these problems is to put @samp{__} at the beginning and 10050end of each problematical keyword. For example, use @code{__asm__} 10051instead of @code{asm}, and @code{__inline__} instead of @code{inline}. 10052 10053Other C compilers won't accept these alternative keywords; if you want to 10054compile with another compiler, you can define the alternate keywords as 10055macros to replace them with the customary keywords. It looks like this: 10056 10057@smallexample 10058#ifndef __GNUC__ 10059#define __asm__ asm 10060#endif 10061@end smallexample 10062 10063@findex __extension__ 10064@opindex pedantic 10065@option{-pedantic} and other options cause warnings for many GNU C extensions. 10066You can 10067prevent such warnings within one expression by writing 10068@code{__extension__} before the expression. @code{__extension__} has no 10069effect aside from this. 10070 10071@node Incomplete Enums 10072@section Incomplete @code{enum} Types 10073 10074You can define an @code{enum} tag without specifying its possible values. 10075This results in an incomplete type, much like what you get if you write 10076@code{struct foo} without describing the elements. A later declaration 10077that does specify the possible values completes the type. 10078 10079You cannot allocate variables or storage using the type while it is 10080incomplete. However, you can work with pointers to that type. 10081 10082This extension may not be very useful, but it makes the handling of 10083@code{enum} more consistent with the way @code{struct} and @code{union} 10084are handled. 10085 10086This extension is not supported by GNU C++. 10087 10088@node Function Names 10089@section Function Names as Strings 10090@cindex @code{__func__} identifier 10091@cindex @code{__FUNCTION__} identifier 10092@cindex @code{__PRETTY_FUNCTION__} identifier 10093 10094GCC provides three magic constants that hold the name of the current 10095function as a string. In C++11 and later modes, all three are treated 10096as constant expressions and can be used in @code{constexpr} constexts. 10097The first of these constants is @code{__func__}, which is part of 10098the C99 standard: 10099 10100The identifier @code{__func__} is implicitly declared by the translator 10101as if, immediately following the opening brace of each function 10102definition, the declaration 10103 10104@smallexample 10105static const char __func__[] = "function-name"; 10106@end smallexample 10107 10108@noindent 10109appeared, where function-name is the name of the lexically-enclosing 10110function. This name is the unadorned name of the function. As an 10111extension, at file (or, in C++, namespace scope), @code{__func__} 10112evaluates to the empty string. 10113 10114@code{__FUNCTION__} is another name for @code{__func__}, provided for 10115backward compatibility with old versions of GCC. 10116 10117In C, @code{__PRETTY_FUNCTION__} is yet another name for 10118@code{__func__}, except that at file (or, in C++, namespace scope), 10119it evaluates to the string @code{"top level"}. In addition, in C++, 10120@code{__PRETTY_FUNCTION__} contains the signature of the function as 10121well as its bare name. For example, this program: 10122 10123@smallexample 10124extern "C" int printf (const char *, ...); 10125 10126class a @{ 10127 public: 10128 void sub (int i) 10129 @{ 10130 printf ("__FUNCTION__ = %s\n", __FUNCTION__); 10131 printf ("__PRETTY_FUNCTION__ = %s\n", __PRETTY_FUNCTION__); 10132 @} 10133@}; 10134 10135int 10136main (void) 10137@{ 10138 a ax; 10139 ax.sub (0); 10140 return 0; 10141@} 10142@end smallexample 10143 10144@noindent 10145gives this output: 10146 10147@smallexample 10148__FUNCTION__ = sub 10149__PRETTY_FUNCTION__ = void a::sub(int) 10150@end smallexample 10151 10152These identifiers are variables, not preprocessor macros, and may not 10153be used to initialize @code{char} arrays or be concatenated with string 10154literals. 10155 10156@node Return Address 10157@section Getting the Return or Frame Address of a Function 10158 10159These functions may be used to get information about the callers of a 10160function. 10161 10162@deftypefn {Built-in Function} {void *} __builtin_return_address (unsigned int @var{level}) 10163This function returns the return address of the current function, or of 10164one of its callers. The @var{level} argument is number of frames to 10165scan up the call stack. A value of @code{0} yields the return address 10166of the current function, a value of @code{1} yields the return address 10167of the caller of the current function, and so forth. When inlining 10168the expected behavior is that the function returns the address of 10169the function that is returned to. To work around this behavior use 10170the @code{noinline} function attribute. 10171 10172The @var{level} argument must be a constant integer. 10173 10174On some machines it may be impossible to determine the return address of 10175any function other than the current one; in such cases, or when the top 10176of the stack has been reached, this function returns @code{0} or a 10177random value. In addition, @code{__builtin_frame_address} may be used 10178to determine if the top of the stack has been reached. 10179 10180Additional post-processing of the returned value may be needed, see 10181@code{__builtin_extract_return_addr}. 10182 10183Calling this function with a nonzero argument can have unpredictable 10184effects, including crashing the calling program. As a result, calls 10185that are considered unsafe are diagnosed when the @option{-Wframe-address} 10186option is in effect. Such calls should only be made in debugging 10187situations. 10188@end deftypefn 10189 10190@deftypefn {Built-in Function} {void *} __builtin_extract_return_addr (void *@var{addr}) 10191The address as returned by @code{__builtin_return_address} may have to be fed 10192through this function to get the actual encoded address. For example, on the 1019331-bit S/390 platform the highest bit has to be masked out, or on SPARC 10194platforms an offset has to be added for the true next instruction to be 10195executed. 10196 10197If no fixup is needed, this function simply passes through @var{addr}. 10198@end deftypefn 10199 10200@deftypefn {Built-in Function} {void *} __builtin_frob_return_address (void *@var{addr}) 10201This function does the reverse of @code{__builtin_extract_return_addr}. 10202@end deftypefn 10203 10204@deftypefn {Built-in Function} {void *} __builtin_frame_address (unsigned int @var{level}) 10205This function is similar to @code{__builtin_return_address}, but it 10206returns the address of the function frame rather than the return address 10207of the function. Calling @code{__builtin_frame_address} with a value of 10208@code{0} yields the frame address of the current function, a value of 10209@code{1} yields the frame address of the caller of the current function, 10210and so forth. 10211 10212The frame is the area on the stack that holds local variables and saved 10213registers. The frame address is normally the address of the first word 10214pushed on to the stack by the function. However, the exact definition 10215depends upon the processor and the calling convention. If the processor 10216has a dedicated frame pointer register, and the function has a frame, 10217then @code{__builtin_frame_address} returns the value of the frame 10218pointer register. 10219 10220On some machines it may be impossible to determine the frame address of 10221any function other than the current one; in such cases, or when the top 10222of the stack has been reached, this function returns @code{0} if 10223the first frame pointer is properly initialized by the startup code. 10224 10225Calling this function with a nonzero argument can have unpredictable 10226effects, including crashing the calling program. As a result, calls 10227that are considered unsafe are diagnosed when the @option{-Wframe-address} 10228option is in effect. Such calls should only be made in debugging 10229situations. 10230@end deftypefn 10231 10232@node Vector Extensions 10233@section Using Vector Instructions through Built-in Functions 10234 10235On some targets, the instruction set contains SIMD vector instructions which 10236operate on multiple values contained in one large register at the same time. 10237For example, on the x86 the MMX, 3DNow!@: and SSE extensions can be used 10238this way. 10239 10240The first step in using these extensions is to provide the necessary data 10241types. This should be done using an appropriate @code{typedef}: 10242 10243@smallexample 10244typedef int v4si __attribute__ ((vector_size (16))); 10245@end smallexample 10246 10247@noindent 10248The @code{int} type specifies the base type, while the attribute specifies 10249the vector size for the variable, measured in bytes. For example, the 10250declaration above causes the compiler to set the mode for the @code{v4si} 10251type to be 16 bytes wide and divided into @code{int} sized units. For 10252a 32-bit @code{int} this means a vector of 4 units of 4 bytes, and the 10253corresponding mode of @code{foo} is @acronym{V4SI}. 10254 10255The @code{vector_size} attribute is only applicable to integral and 10256float scalars, although arrays, pointers, and function return values 10257are allowed in conjunction with this construct. Only sizes that are 10258a power of two are currently allowed. 10259 10260All the basic integer types can be used as base types, both as signed 10261and as unsigned: @code{char}, @code{short}, @code{int}, @code{long}, 10262@code{long long}. In addition, @code{float} and @code{double} can be 10263used to build floating-point vector types. 10264 10265Specifying a combination that is not valid for the current architecture 10266causes GCC to synthesize the instructions using a narrower mode. 10267For example, if you specify a variable of type @code{V4SI} and your 10268architecture does not allow for this specific SIMD type, GCC 10269produces code that uses 4 @code{SIs}. 10270 10271The types defined in this manner can be used with a subset of normal C 10272operations. Currently, GCC allows using the following operators 10273on these types: @code{+, -, *, /, unary minus, ^, |, &, ~, %}@. 10274 10275The operations behave like C++ @code{valarrays}. Addition is defined as 10276the addition of the corresponding elements of the operands. For 10277example, in the code below, each of the 4 elements in @var{a} is 10278added to the corresponding 4 elements in @var{b} and the resulting 10279vector is stored in @var{c}. 10280 10281@smallexample 10282typedef int v4si __attribute__ ((vector_size (16))); 10283 10284v4si a, b, c; 10285 10286c = a + b; 10287@end smallexample 10288 10289Subtraction, multiplication, division, and the logical operations 10290operate in a similar manner. Likewise, the result of using the unary 10291minus or complement operators on a vector type is a vector whose 10292elements are the negative or complemented values of the corresponding 10293elements in the operand. 10294 10295It is possible to use shifting operators @code{<<}, @code{>>} on 10296integer-type vectors. The operation is defined as following: @code{@{a0, 10297a1, @dots{}, an@} >> @{b0, b1, @dots{}, bn@} == @{a0 >> b0, a1 >> b1, 10298@dots{}, an >> bn@}}@. Vector operands must have the same number of 10299elements. 10300 10301For convenience, it is allowed to use a binary vector operation 10302where one operand is a scalar. In that case the compiler transforms 10303the scalar operand into a vector where each element is the scalar from 10304the operation. The transformation happens only if the scalar could be 10305safely converted to the vector-element type. 10306Consider the following code. 10307 10308@smallexample 10309typedef int v4si __attribute__ ((vector_size (16))); 10310 10311v4si a, b, c; 10312long l; 10313 10314a = b + 1; /* a = b + @{1,1,1,1@}; */ 10315a = 2 * b; /* a = @{2,2,2,2@} * b; */ 10316 10317a = l + a; /* Error, cannot convert long to int. */ 10318@end smallexample 10319 10320Vectors can be subscripted as if the vector were an array with 10321the same number of elements and base type. Out of bound accesses 10322invoke undefined behavior at run time. Warnings for out of bound 10323accesses for vector subscription can be enabled with 10324@option{-Warray-bounds}. 10325 10326Vector comparison is supported with standard comparison 10327operators: @code{==, !=, <, <=, >, >=}. Comparison operands can be 10328vector expressions of integer-type or real-type. Comparison between 10329integer-type vectors and real-type vectors are not supported. The 10330result of the comparison is a vector of the same width and number of 10331elements as the comparison operands with a signed integral element 10332type. 10333 10334Vectors are compared element-wise producing 0 when comparison is false 10335and -1 (constant of the appropriate type where all bits are set) 10336otherwise. Consider the following example. 10337 10338@smallexample 10339typedef int v4si __attribute__ ((vector_size (16))); 10340 10341v4si a = @{1,2,3,4@}; 10342v4si b = @{3,2,1,4@}; 10343v4si c; 10344 10345c = a > b; /* The result would be @{0, 0,-1, 0@} */ 10346c = a == b; /* The result would be @{0,-1, 0,-1@} */ 10347@end smallexample 10348 10349In C++, the ternary operator @code{?:} is available. @code{a?b:c}, where 10350@code{b} and @code{c} are vectors of the same type and @code{a} is an 10351integer vector with the same number of elements of the same size as @code{b} 10352and @code{c}, computes all three arguments and creates a vector 10353@code{@{a[0]?b[0]:c[0], a[1]?b[1]:c[1], @dots{}@}}. Note that unlike in 10354OpenCL, @code{a} is thus interpreted as @code{a != 0} and not @code{a < 0}. 10355As in the case of binary operations, this syntax is also accepted when 10356one of @code{b} or @code{c} is a scalar that is then transformed into a 10357vector. If both @code{b} and @code{c} are scalars and the type of 10358@code{true?b:c} has the same size as the element type of @code{a}, then 10359@code{b} and @code{c} are converted to a vector type whose elements have 10360this type and with the same number of elements as @code{a}. 10361 10362In C++, the logic operators @code{!, &&, ||} are available for vectors. 10363@code{!v} is equivalent to @code{v == 0}, @code{a && b} is equivalent to 10364@code{a!=0 & b!=0} and @code{a || b} is equivalent to @code{a!=0 | b!=0}. 10365For mixed operations between a scalar @code{s} and a vector @code{v}, 10366@code{s && v} is equivalent to @code{s?v!=0:0} (the evaluation is 10367short-circuit) and @code{v && s} is equivalent to @code{v!=0 & (s?-1:0)}. 10368 10369@findex __builtin_shuffle 10370Vector shuffling is available using functions 10371@code{__builtin_shuffle (vec, mask)} and 10372@code{__builtin_shuffle (vec0, vec1, mask)}. 10373Both functions construct a permutation of elements from one or two 10374vectors and return a vector of the same type as the input vector(s). 10375The @var{mask} is an integral vector with the same width (@var{W}) 10376and element count (@var{N}) as the output vector. 10377 10378The elements of the input vectors are numbered in memory ordering of 10379@var{vec0} beginning at 0 and @var{vec1} beginning at @var{N}. The 10380elements of @var{mask} are considered modulo @var{N} in the single-operand 10381case and modulo @math{2*@var{N}} in the two-operand case. 10382 10383Consider the following example, 10384 10385@smallexample 10386typedef int v4si __attribute__ ((vector_size (16))); 10387 10388v4si a = @{1,2,3,4@}; 10389v4si b = @{5,6,7,8@}; 10390v4si mask1 = @{0,1,1,3@}; 10391v4si mask2 = @{0,4,2,5@}; 10392v4si res; 10393 10394res = __builtin_shuffle (a, mask1); /* res is @{1,2,2,4@} */ 10395res = __builtin_shuffle (a, b, mask2); /* res is @{1,5,3,6@} */ 10396@end smallexample 10397 10398Note that @code{__builtin_shuffle} is intentionally semantically 10399compatible with the OpenCL @code{shuffle} and @code{shuffle2} functions. 10400 10401You can declare variables and use them in function calls and returns, as 10402well as in assignments and some casts. You can specify a vector type as 10403a return type for a function. Vector types can also be used as function 10404arguments. It is possible to cast from one vector type to another, 10405provided they are of the same size (in fact, you can also cast vectors 10406to and from other datatypes of the same size). 10407 10408You cannot operate between vectors of different lengths or different 10409signedness without a cast. 10410 10411@node Offsetof 10412@section Support for @code{offsetof} 10413@findex __builtin_offsetof 10414 10415GCC implements for both C and C++ a syntactic extension to implement 10416the @code{offsetof} macro. 10417 10418@smallexample 10419primary: 10420 "__builtin_offsetof" "(" @code{typename} "," offsetof_member_designator ")" 10421 10422offsetof_member_designator: 10423 @code{identifier} 10424 | offsetof_member_designator "." @code{identifier} 10425 | offsetof_member_designator "[" @code{expr} "]" 10426@end smallexample 10427 10428This extension is sufficient such that 10429 10430@smallexample 10431#define offsetof(@var{type}, @var{member}) __builtin_offsetof (@var{type}, @var{member}) 10432@end smallexample 10433 10434@noindent 10435is a suitable definition of the @code{offsetof} macro. In C++, @var{type} 10436may be dependent. In either case, @var{member} may consist of a single 10437identifier, or a sequence of member accesses and array references. 10438 10439@node __sync Builtins 10440@section Legacy @code{__sync} Built-in Functions for Atomic Memory Access 10441 10442The following built-in functions 10443are intended to be compatible with those described 10444in the @cite{Intel Itanium Processor-specific Application Binary Interface}, 10445section 7.4. As such, they depart from normal GCC practice by not using 10446the @samp{__builtin_} prefix and also by being overloaded so that they 10447work on multiple types. 10448 10449The definition given in the Intel documentation allows only for the use of 10450the types @code{int}, @code{long}, @code{long long} or their unsigned 10451counterparts. GCC allows any scalar type that is 1, 2, 4 or 8 bytes in 10452size other than the C type @code{_Bool} or the C++ type @code{bool}. 10453Operations on pointer arguments are performed as if the operands were 10454of the @code{uintptr_t} type. That is, they are not scaled by the size 10455of the type to which the pointer points. 10456 10457These functions are implemented in terms of the @samp{__atomic} 10458builtins (@pxref{__atomic Builtins}). They should not be used for new 10459code which should use the @samp{__atomic} builtins instead. 10460 10461Not all operations are supported by all target processors. If a particular 10462operation cannot be implemented on the target processor, a warning is 10463generated and a call to an external function is generated. The external 10464function carries the same name as the built-in version, 10465with an additional suffix 10466@samp{_@var{n}} where @var{n} is the size of the data type. 10467 10468@c ??? Should we have a mechanism to suppress this warning? This is almost 10469@c useful for implementing the operation under the control of an external 10470@c mutex. 10471 10472In most cases, these built-in functions are considered a @dfn{full barrier}. 10473That is, 10474no memory operand is moved across the operation, either forward or 10475backward. Further, instructions are issued as necessary to prevent the 10476processor from speculating loads across the operation and from queuing stores 10477after the operation. 10478 10479All of the routines are described in the Intel documentation to take 10480``an optional list of variables protected by the memory barrier''. It's 10481not clear what is meant by that; it could mean that @emph{only} the 10482listed variables are protected, or it could mean a list of additional 10483variables to be protected. The list is ignored by GCC which treats it as 10484empty. GCC interprets an empty list as meaning that all globally 10485accessible variables should be protected. 10486 10487@table @code 10488@item @var{type} __sync_fetch_and_add (@var{type} *ptr, @var{type} value, ...) 10489@itemx @var{type} __sync_fetch_and_sub (@var{type} *ptr, @var{type} value, ...) 10490@itemx @var{type} __sync_fetch_and_or (@var{type} *ptr, @var{type} value, ...) 10491@itemx @var{type} __sync_fetch_and_and (@var{type} *ptr, @var{type} value, ...) 10492@itemx @var{type} __sync_fetch_and_xor (@var{type} *ptr, @var{type} value, ...) 10493@itemx @var{type} __sync_fetch_and_nand (@var{type} *ptr, @var{type} value, ...) 10494@findex __sync_fetch_and_add 10495@findex __sync_fetch_and_sub 10496@findex __sync_fetch_and_or 10497@findex __sync_fetch_and_and 10498@findex __sync_fetch_and_xor 10499@findex __sync_fetch_and_nand 10500These built-in functions perform the operation suggested by the name, and 10501returns the value that had previously been in memory. That is, operations 10502on integer operands have the following semantics. Operations on pointer 10503arguments are performed as if the operands were of the @code{uintptr_t} 10504type. That is, they are not scaled by the size of the type to which 10505the pointer points. 10506 10507@smallexample 10508@{ tmp = *ptr; *ptr @var{op}= value; return tmp; @} 10509@{ tmp = *ptr; *ptr = ~(tmp & value); return tmp; @} // nand 10510@end smallexample 10511 10512The object pointed to by the first argument must be of integer or pointer 10513type. It must not be a boolean type. 10514 10515@emph{Note:} GCC 4.4 and later implement @code{__sync_fetch_and_nand} 10516as @code{*ptr = ~(tmp & value)} instead of @code{*ptr = ~tmp & value}. 10517 10518@item @var{type} __sync_add_and_fetch (@var{type} *ptr, @var{type} value, ...) 10519@itemx @var{type} __sync_sub_and_fetch (@var{type} *ptr, @var{type} value, ...) 10520@itemx @var{type} __sync_or_and_fetch (@var{type} *ptr, @var{type} value, ...) 10521@itemx @var{type} __sync_and_and_fetch (@var{type} *ptr, @var{type} value, ...) 10522@itemx @var{type} __sync_xor_and_fetch (@var{type} *ptr, @var{type} value, ...) 10523@itemx @var{type} __sync_nand_and_fetch (@var{type} *ptr, @var{type} value, ...) 10524@findex __sync_add_and_fetch 10525@findex __sync_sub_and_fetch 10526@findex __sync_or_and_fetch 10527@findex __sync_and_and_fetch 10528@findex __sync_xor_and_fetch 10529@findex __sync_nand_and_fetch 10530These built-in functions perform the operation suggested by the name, and 10531return the new value. That is, operations on integer operands have 10532the following semantics. Operations on pointer operands are performed as 10533if the operand's type were @code{uintptr_t}. 10534 10535@smallexample 10536@{ *ptr @var{op}= value; return *ptr; @} 10537@{ *ptr = ~(*ptr & value); return *ptr; @} // nand 10538@end smallexample 10539 10540The same constraints on arguments apply as for the corresponding 10541@code{__sync_op_and_fetch} built-in functions. 10542 10543@emph{Note:} GCC 4.4 and later implement @code{__sync_nand_and_fetch} 10544as @code{*ptr = ~(*ptr & value)} instead of 10545@code{*ptr = ~*ptr & value}. 10546 10547@item bool __sync_bool_compare_and_swap (@var{type} *ptr, @var{type} oldval, @var{type} newval, ...) 10548@itemx @var{type} __sync_val_compare_and_swap (@var{type} *ptr, @var{type} oldval, @var{type} newval, ...) 10549@findex __sync_bool_compare_and_swap 10550@findex __sync_val_compare_and_swap 10551These built-in functions perform an atomic compare and swap. 10552That is, if the current 10553value of @code{*@var{ptr}} is @var{oldval}, then write @var{newval} into 10554@code{*@var{ptr}}. 10555 10556The ``bool'' version returns true if the comparison is successful and 10557@var{newval} is written. The ``val'' version returns the contents 10558of @code{*@var{ptr}} before the operation. 10559 10560@item __sync_synchronize (...) 10561@findex __sync_synchronize 10562This built-in function issues a full memory barrier. 10563 10564@item @var{type} __sync_lock_test_and_set (@var{type} *ptr, @var{type} value, ...) 10565@findex __sync_lock_test_and_set 10566This built-in function, as described by Intel, is not a traditional test-and-set 10567operation, but rather an atomic exchange operation. It writes @var{value} 10568into @code{*@var{ptr}}, and returns the previous contents of 10569@code{*@var{ptr}}. 10570 10571Many targets have only minimal support for such locks, and do not support 10572a full exchange operation. In this case, a target may support reduced 10573functionality here by which the @emph{only} valid value to store is the 10574immediate constant 1. The exact value actually stored in @code{*@var{ptr}} 10575is implementation defined. 10576 10577This built-in function is not a full barrier, 10578but rather an @dfn{acquire barrier}. 10579This means that references after the operation cannot move to (or be 10580speculated to) before the operation, but previous memory stores may not 10581be globally visible yet, and previous memory loads may not yet be 10582satisfied. 10583 10584@item void __sync_lock_release (@var{type} *ptr, ...) 10585@findex __sync_lock_release 10586This built-in function releases the lock acquired by 10587@code{__sync_lock_test_and_set}. 10588Normally this means writing the constant 0 to @code{*@var{ptr}}. 10589 10590This built-in function is not a full barrier, 10591but rather a @dfn{release barrier}. 10592This means that all previous memory stores are globally visible, and all 10593previous memory loads have been satisfied, but following memory reads 10594are not prevented from being speculated to before the barrier. 10595@end table 10596 10597@node __atomic Builtins 10598@section Built-in Functions for Memory Model Aware Atomic Operations 10599 10600The following built-in functions approximately match the requirements 10601for the C++11 memory model. They are all 10602identified by being prefixed with @samp{__atomic} and most are 10603overloaded so that they work with multiple types. 10604 10605These functions are intended to replace the legacy @samp{__sync} 10606builtins. The main difference is that the memory order that is requested 10607is a parameter to the functions. New code should always use the 10608@samp{__atomic} builtins rather than the @samp{__sync} builtins. 10609 10610Note that the @samp{__atomic} builtins assume that programs will 10611conform to the C++11 memory model. In particular, they assume 10612that programs are free of data races. See the C++11 standard for 10613detailed requirements. 10614 10615The @samp{__atomic} builtins can be used with any integral scalar or 10616pointer type that is 1, 2, 4, or 8 bytes in length. 16-byte integral 10617types are also allowed if @samp{__int128} (@pxref{__int128}) is 10618supported by the architecture. 10619 10620The four non-arithmetic functions (load, store, exchange, and 10621compare_exchange) all have a generic version as well. This generic 10622version works on any data type. It uses the lock-free built-in function 10623if the specific data type size makes that possible; otherwise, an 10624external call is left to be resolved at run time. This external call is 10625the same format with the addition of a @samp{size_t} parameter inserted 10626as the first parameter indicating the size of the object being pointed to. 10627All objects must be the same size. 10628 10629There are 6 different memory orders that can be specified. These map 10630to the C++11 memory orders with the same names, see the C++11 standard 10631or the @uref{http://gcc.gnu.org/wiki/Atomic/GCCMM/AtomicSync,GCC wiki 10632on atomic synchronization} for detailed definitions. Individual 10633targets may also support additional memory orders for use on specific 10634architectures. Refer to the target documentation for details of 10635these. 10636 10637An atomic operation can both constrain code motion and 10638be mapped to hardware instructions for synchronization between threads 10639(e.g., a fence). To which extent this happens is controlled by the 10640memory orders, which are listed here in approximately ascending order of 10641strength. The description of each memory order is only meant to roughly 10642illustrate the effects and is not a specification; see the C++11 10643memory model for precise semantics. 10644 10645@table @code 10646@item __ATOMIC_RELAXED 10647Implies no inter-thread ordering constraints. 10648@item __ATOMIC_CONSUME 10649This is currently implemented using the stronger @code{__ATOMIC_ACQUIRE} 10650memory order because of a deficiency in C++11's semantics for 10651@code{memory_order_consume}. 10652@item __ATOMIC_ACQUIRE 10653Creates an inter-thread happens-before constraint from the release (or 10654stronger) semantic store to this acquire load. Can prevent hoisting 10655of code to before the operation. 10656@item __ATOMIC_RELEASE 10657Creates an inter-thread happens-before constraint to acquire (or stronger) 10658semantic loads that read from this release store. Can prevent sinking 10659of code to after the operation. 10660@item __ATOMIC_ACQ_REL 10661Combines the effects of both @code{__ATOMIC_ACQUIRE} and 10662@code{__ATOMIC_RELEASE}. 10663@item __ATOMIC_SEQ_CST 10664Enforces total ordering with all other @code{__ATOMIC_SEQ_CST} operations. 10665@end table 10666 10667Note that in the C++11 memory model, @emph{fences} (e.g., 10668@samp{__atomic_thread_fence}) take effect in combination with other 10669atomic operations on specific memory locations (e.g., atomic loads); 10670operations on specific memory locations do not necessarily affect other 10671operations in the same way. 10672 10673Target architectures are encouraged to provide their own patterns for 10674each of the atomic built-in functions. If no target is provided, the original 10675non-memory model set of @samp{__sync} atomic built-in functions are 10676used, along with any required synchronization fences surrounding it in 10677order to achieve the proper behavior. Execution in this case is subject 10678to the same restrictions as those built-in functions. 10679 10680If there is no pattern or mechanism to provide a lock-free instruction 10681sequence, a call is made to an external routine with the same parameters 10682to be resolved at run time. 10683 10684When implementing patterns for these built-in functions, the memory order 10685parameter can be ignored as long as the pattern implements the most 10686restrictive @code{__ATOMIC_SEQ_CST} memory order. Any of the other memory 10687orders execute correctly with this memory order but they may not execute as 10688efficiently as they could with a more appropriate implementation of the 10689relaxed requirements. 10690 10691Note that the C++11 standard allows for the memory order parameter to be 10692determined at run time rather than at compile time. These built-in 10693functions map any run-time value to @code{__ATOMIC_SEQ_CST} rather 10694than invoke a runtime library call or inline a switch statement. This is 10695standard compliant, safe, and the simplest approach for now. 10696 10697The memory order parameter is a signed int, but only the lower 16 bits are 10698reserved for the memory order. The remainder of the signed int is reserved 10699for target use and should be 0. Use of the predefined atomic values 10700ensures proper usage. 10701 10702@deftypefn {Built-in Function} @var{type} __atomic_load_n (@var{type} *ptr, int memorder) 10703This built-in function implements an atomic load operation. It returns the 10704contents of @code{*@var{ptr}}. 10705 10706The valid memory order variants are 10707@code{__ATOMIC_RELAXED}, @code{__ATOMIC_SEQ_CST}, @code{__ATOMIC_ACQUIRE}, 10708and @code{__ATOMIC_CONSUME}. 10709 10710@end deftypefn 10711 10712@deftypefn {Built-in Function} void __atomic_load (@var{type} *ptr, @var{type} *ret, int memorder) 10713This is the generic version of an atomic load. It returns the 10714contents of @code{*@var{ptr}} in @code{*@var{ret}}. 10715 10716@end deftypefn 10717 10718@deftypefn {Built-in Function} void __atomic_store_n (@var{type} *ptr, @var{type} val, int memorder) 10719This built-in function implements an atomic store operation. It writes 10720@code{@var{val}} into @code{*@var{ptr}}. 10721 10722The valid memory order variants are 10723@code{__ATOMIC_RELAXED}, @code{__ATOMIC_SEQ_CST}, and @code{__ATOMIC_RELEASE}. 10724 10725@end deftypefn 10726 10727@deftypefn {Built-in Function} void __atomic_store (@var{type} *ptr, @var{type} *val, int memorder) 10728This is the generic version of an atomic store. It stores the value 10729of @code{*@var{val}} into @code{*@var{ptr}}. 10730 10731@end deftypefn 10732 10733@deftypefn {Built-in Function} @var{type} __atomic_exchange_n (@var{type} *ptr, @var{type} val, int memorder) 10734This built-in function implements an atomic exchange operation. It writes 10735@var{val} into @code{*@var{ptr}}, and returns the previous contents of 10736@code{*@var{ptr}}. 10737 10738The valid memory order variants are 10739@code{__ATOMIC_RELAXED}, @code{__ATOMIC_SEQ_CST}, @code{__ATOMIC_ACQUIRE}, 10740@code{__ATOMIC_RELEASE}, and @code{__ATOMIC_ACQ_REL}. 10741 10742@end deftypefn 10743 10744@deftypefn {Built-in Function} void __atomic_exchange (@var{type} *ptr, @var{type} *val, @var{type} *ret, int memorder) 10745This is the generic version of an atomic exchange. It stores the 10746contents of @code{*@var{val}} into @code{*@var{ptr}}. The original value 10747of @code{*@var{ptr}} is copied into @code{*@var{ret}}. 10748 10749@end deftypefn 10750 10751@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) 10752This built-in function implements an atomic compare and exchange operation. 10753This compares the contents of @code{*@var{ptr}} with the contents of 10754@code{*@var{expected}}. If equal, the operation is a @emph{read-modify-write} 10755operation that writes @var{desired} into @code{*@var{ptr}}. If they are not 10756equal, the operation is a @emph{read} and the current contents of 10757@code{*@var{ptr}} are written into @code{*@var{expected}}. @var{weak} is true 10758for weak compare_exchange, which may fail spuriously, and false for 10759the strong variation, which never fails spuriously. Many targets 10760only offer the strong variation and ignore the parameter. When in doubt, use 10761the strong variation. 10762 10763If @var{desired} is written into @code{*@var{ptr}} then true is returned 10764and memory is affected according to the 10765memory order specified by @var{success_memorder}. There are no 10766restrictions on what memory order can be used here. 10767 10768Otherwise, false is returned and memory is affected according 10769to @var{failure_memorder}. This memory order cannot be 10770@code{__ATOMIC_RELEASE} nor @code{__ATOMIC_ACQ_REL}. It also cannot be a 10771stronger order than that specified by @var{success_memorder}. 10772 10773@end deftypefn 10774 10775@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) 10776This built-in function implements the generic version of 10777@code{__atomic_compare_exchange}. The function is virtually identical to 10778@code{__atomic_compare_exchange_n}, except the desired value is also a 10779pointer. 10780 10781@end deftypefn 10782 10783@deftypefn {Built-in Function} @var{type} __atomic_add_fetch (@var{type} *ptr, @var{type} val, int memorder) 10784@deftypefnx {Built-in Function} @var{type} __atomic_sub_fetch (@var{type} *ptr, @var{type} val, int memorder) 10785@deftypefnx {Built-in Function} @var{type} __atomic_and_fetch (@var{type} *ptr, @var{type} val, int memorder) 10786@deftypefnx {Built-in Function} @var{type} __atomic_xor_fetch (@var{type} *ptr, @var{type} val, int memorder) 10787@deftypefnx {Built-in Function} @var{type} __atomic_or_fetch (@var{type} *ptr, @var{type} val, int memorder) 10788@deftypefnx {Built-in Function} @var{type} __atomic_nand_fetch (@var{type} *ptr, @var{type} val, int memorder) 10789These built-in functions perform the operation suggested by the name, and 10790return the result of the operation. Operations on pointer arguments are 10791performed as if the operands were of the @code{uintptr_t} type. That is, 10792they are not scaled by the size of the type to which the pointer points. 10793 10794@smallexample 10795@{ *ptr @var{op}= val; return *ptr; @} 10796@end smallexample 10797 10798The object pointed to by the first argument must be of integer or pointer 10799type. It must not be a boolean type. All memory orders are valid. 10800 10801@end deftypefn 10802 10803@deftypefn {Built-in Function} @var{type} __atomic_fetch_add (@var{type} *ptr, @var{type} val, int memorder) 10804@deftypefnx {Built-in Function} @var{type} __atomic_fetch_sub (@var{type} *ptr, @var{type} val, int memorder) 10805@deftypefnx {Built-in Function} @var{type} __atomic_fetch_and (@var{type} *ptr, @var{type} val, int memorder) 10806@deftypefnx {Built-in Function} @var{type} __atomic_fetch_xor (@var{type} *ptr, @var{type} val, int memorder) 10807@deftypefnx {Built-in Function} @var{type} __atomic_fetch_or (@var{type} *ptr, @var{type} val, int memorder) 10808@deftypefnx {Built-in Function} @var{type} __atomic_fetch_nand (@var{type} *ptr, @var{type} val, int memorder) 10809These built-in functions perform the operation suggested by the name, and 10810return the value that had previously been in @code{*@var{ptr}}. Operations 10811on pointer arguments are performed as if the operands were of 10812the @code{uintptr_t} type. That is, they are not scaled by the size of 10813the type to which the pointer points. 10814 10815@smallexample 10816@{ tmp = *ptr; *ptr @var{op}= val; return tmp; @} 10817@end smallexample 10818 10819The same constraints on arguments apply as for the corresponding 10820@code{__atomic_op_fetch} built-in functions. All memory orders are valid. 10821 10822@end deftypefn 10823 10824@deftypefn {Built-in Function} bool __atomic_test_and_set (void *ptr, int memorder) 10825 10826This built-in function performs an atomic test-and-set operation on 10827the byte at @code{*@var{ptr}}. The byte is set to some implementation 10828defined nonzero ``set'' value and the return value is @code{true} if and only 10829if the previous contents were ``set''. 10830It should be only used for operands of type @code{bool} or @code{char}. For 10831other types only part of the value may be set. 10832 10833All memory orders are valid. 10834 10835@end deftypefn 10836 10837@deftypefn {Built-in Function} void __atomic_clear (bool *ptr, int memorder) 10838 10839This built-in function performs an atomic clear operation on 10840@code{*@var{ptr}}. After the operation, @code{*@var{ptr}} contains 0. 10841It should be only used for operands of type @code{bool} or @code{char} and 10842in conjunction with @code{__atomic_test_and_set}. 10843For other types it may only clear partially. If the type is not @code{bool} 10844prefer using @code{__atomic_store}. 10845 10846The valid memory order variants are 10847@code{__ATOMIC_RELAXED}, @code{__ATOMIC_SEQ_CST}, and 10848@code{__ATOMIC_RELEASE}. 10849 10850@end deftypefn 10851 10852@deftypefn {Built-in Function} void __atomic_thread_fence (int memorder) 10853 10854This built-in function acts as a synchronization fence between threads 10855based on the specified memory order. 10856 10857All memory orders are valid. 10858 10859@end deftypefn 10860 10861@deftypefn {Built-in Function} void __atomic_signal_fence (int memorder) 10862 10863This built-in function acts as a synchronization fence between a thread 10864and signal handlers based in the same thread. 10865 10866All memory orders are valid. 10867 10868@end deftypefn 10869 10870@deftypefn {Built-in Function} bool __atomic_always_lock_free (size_t size, void *ptr) 10871 10872This built-in function returns true if objects of @var{size} bytes always 10873generate lock-free atomic instructions for the target architecture. 10874@var{size} must resolve to a compile-time constant and the result also 10875resolves to a compile-time constant. 10876 10877@var{ptr} is an optional pointer to the object that may be used to determine 10878alignment. A value of 0 indicates typical alignment should be used. The 10879compiler may also ignore this parameter. 10880 10881@smallexample 10882if (__atomic_always_lock_free (sizeof (long long), 0)) 10883@end smallexample 10884 10885@end deftypefn 10886 10887@deftypefn {Built-in Function} bool __atomic_is_lock_free (size_t size, void *ptr) 10888 10889This built-in function returns true if objects of @var{size} bytes always 10890generate lock-free atomic instructions for the target architecture. If 10891the built-in function is not known to be lock-free, a call is made to a 10892runtime routine named @code{__atomic_is_lock_free}. 10893 10894@var{ptr} is an optional pointer to the object that may be used to determine 10895alignment. A value of 0 indicates typical alignment should be used. The 10896compiler may also ignore this parameter. 10897@end deftypefn 10898 10899@node Integer Overflow Builtins 10900@section Built-in Functions to Perform Arithmetic with Overflow Checking 10901 10902The following built-in functions allow performing simple arithmetic operations 10903together with checking whether the operations overflowed. 10904 10905@deftypefn {Built-in Function} bool __builtin_add_overflow (@var{type1} a, @var{type2} b, @var{type3} *res) 10906@deftypefnx {Built-in Function} bool __builtin_sadd_overflow (int a, int b, int *res) 10907@deftypefnx {Built-in Function} bool __builtin_saddl_overflow (long int a, long int b, long int *res) 10908@deftypefnx {Built-in Function} bool __builtin_saddll_overflow (long long int a, long long int b, long long int *res) 10909@deftypefnx {Built-in Function} bool __builtin_uadd_overflow (unsigned int a, unsigned int b, unsigned int *res) 10910@deftypefnx {Built-in Function} bool __builtin_uaddl_overflow (unsigned long int a, unsigned long int b, unsigned long int *res) 10911@deftypefnx {Built-in Function} bool __builtin_uaddll_overflow (unsigned long long int a, unsigned long long int b, unsigned long long int *res) 10912 10913These built-in functions promote the first two operands into infinite precision signed 10914type and perform addition on those promoted operands. The result is then 10915cast to the type the third pointer argument points to and stored there. 10916If the stored result is equal to the infinite precision result, the built-in 10917functions return false, otherwise they return true. As the addition is 10918performed in infinite signed precision, these built-in functions have fully defined 10919behavior for all argument values. 10920 10921The first built-in function allows arbitrary integral types for operands and 10922the result type must be pointer to some integral type other than enumerated or 10923boolean type, the rest of the built-in functions have explicit integer types. 10924 10925The compiler will attempt to use hardware instructions to implement 10926these built-in functions where possible, like conditional jump on overflow 10927after addition, conditional jump on carry etc. 10928 10929@end deftypefn 10930 10931@deftypefn {Built-in Function} bool __builtin_sub_overflow (@var{type1} a, @var{type2} b, @var{type3} *res) 10932@deftypefnx {Built-in Function} bool __builtin_ssub_overflow (int a, int b, int *res) 10933@deftypefnx {Built-in Function} bool __builtin_ssubl_overflow (long int a, long int b, long int *res) 10934@deftypefnx {Built-in Function} bool __builtin_ssubll_overflow (long long int a, long long int b, long long int *res) 10935@deftypefnx {Built-in Function} bool __builtin_usub_overflow (unsigned int a, unsigned int b, unsigned int *res) 10936@deftypefnx {Built-in Function} bool __builtin_usubl_overflow (unsigned long int a, unsigned long int b, unsigned long int *res) 10937@deftypefnx {Built-in Function} bool __builtin_usubll_overflow (unsigned long long int a, unsigned long long int b, unsigned long long int *res) 10938 10939These built-in functions are similar to the add overflow checking built-in 10940functions above, except they perform subtraction, subtract the second argument 10941from the first one, instead of addition. 10942 10943@end deftypefn 10944 10945@deftypefn {Built-in Function} bool __builtin_mul_overflow (@var{type1} a, @var{type2} b, @var{type3} *res) 10946@deftypefnx {Built-in Function} bool __builtin_smul_overflow (int a, int b, int *res) 10947@deftypefnx {Built-in Function} bool __builtin_smull_overflow (long int a, long int b, long int *res) 10948@deftypefnx {Built-in Function} bool __builtin_smulll_overflow (long long int a, long long int b, long long int *res) 10949@deftypefnx {Built-in Function} bool __builtin_umul_overflow (unsigned int a, unsigned int b, unsigned int *res) 10950@deftypefnx {Built-in Function} bool __builtin_umull_overflow (unsigned long int a, unsigned long int b, unsigned long int *res) 10951@deftypefnx {Built-in Function} bool __builtin_umulll_overflow (unsigned long long int a, unsigned long long int b, unsigned long long int *res) 10952 10953These built-in functions are similar to the add overflow checking built-in 10954functions above, except they perform multiplication, instead of addition. 10955 10956@end deftypefn 10957 10958The following built-in functions allow checking if simple arithmetic operation 10959would overflow. 10960 10961@deftypefn {Built-in Function} bool __builtin_add_overflow_p (@var{type1} a, @var{type2} b, @var{type3} c) 10962@deftypefnx {Built-in Function} bool __builtin_sub_overflow_p (@var{type1} a, @var{type2} b, @var{type3} c) 10963@deftypefnx {Built-in Function} bool __builtin_mul_overflow_p (@var{type1} a, @var{type2} b, @var{type3} c) 10964 10965These built-in functions are similar to @code{__builtin_add_overflow}, 10966@code{__builtin_sub_overflow}, or @code{__builtin_mul_overflow}, except that 10967they don't store the result of the arithmetic operation anywhere and the 10968last argument is not a pointer, but some expression with integral type other 10969than enumerated or boolean type. 10970 10971The built-in functions promote the first two operands into infinite precision signed type 10972and perform addition on those promoted operands. The result is then 10973cast to the type of the third argument. If the cast result is equal to the infinite 10974precision result, the built-in functions return false, otherwise they return true. 10975The value of the third argument is ignored, just the side effects in the third argument 10976are evaluated, and no integral argument promotions are performed on the last argument. 10977If the third argument is a bit-field, the type used for the result cast has the 10978precision and signedness of the given bit-field, rather than precision and signedness 10979of the underlying type. 10980 10981For example, the following macro can be used to portably check, at 10982compile-time, whether or not adding two constant integers will overflow, 10983and perform the addition only when it is known to be safe and not to trigger 10984a @option{-Woverflow} warning. 10985 10986@smallexample 10987#define INT_ADD_OVERFLOW_P(a, b) \ 10988 __builtin_add_overflow_p (a, b, (__typeof__ ((a) + (b))) 0) 10989 10990enum @{ 10991 A = INT_MAX, B = 3, 10992 C = INT_ADD_OVERFLOW_P (A, B) ? 0 : A + B, 10993 D = __builtin_add_overflow_p (1, SCHAR_MAX, (signed char) 0) 10994@}; 10995@end smallexample 10996 10997The compiler will attempt to use hardware instructions to implement 10998these built-in functions where possible, like conditional jump on overflow 10999after addition, conditional jump on carry etc. 11000 11001@end deftypefn 11002 11003@node x86 specific memory model extensions for transactional memory 11004@section x86-Specific Memory Model Extensions for Transactional Memory 11005 11006The x86 architecture supports additional memory ordering flags 11007to mark critical sections for hardware lock elision. 11008These must be specified in addition to an existing memory order to 11009atomic intrinsics. 11010 11011@table @code 11012@item __ATOMIC_HLE_ACQUIRE 11013Start lock elision on a lock variable. 11014Memory order must be @code{__ATOMIC_ACQUIRE} or stronger. 11015@item __ATOMIC_HLE_RELEASE 11016End lock elision on a lock variable. 11017Memory order must be @code{__ATOMIC_RELEASE} or stronger. 11018@end table 11019 11020When a lock acquire fails, it is required for good performance to abort 11021the transaction quickly. This can be done with a @code{_mm_pause}. 11022 11023@smallexample 11024#include <immintrin.h> // For _mm_pause 11025 11026int lockvar; 11027 11028/* Acquire lock with lock elision */ 11029while (__atomic_exchange_n(&lockvar, 1, __ATOMIC_ACQUIRE|__ATOMIC_HLE_ACQUIRE)) 11030 _mm_pause(); /* Abort failed transaction */ 11031... 11032/* Free lock with lock elision */ 11033__atomic_store_n(&lockvar, 0, __ATOMIC_RELEASE|__ATOMIC_HLE_RELEASE); 11034@end smallexample 11035 11036@node Object Size Checking 11037@section Object Size Checking Built-in Functions 11038@findex __builtin_object_size 11039@findex __builtin___memcpy_chk 11040@findex __builtin___mempcpy_chk 11041@findex __builtin___memmove_chk 11042@findex __builtin___memset_chk 11043@findex __builtin___strcpy_chk 11044@findex __builtin___stpcpy_chk 11045@findex __builtin___strncpy_chk 11046@findex __builtin___strcat_chk 11047@findex __builtin___strncat_chk 11048@findex __builtin___sprintf_chk 11049@findex __builtin___snprintf_chk 11050@findex __builtin___vsprintf_chk 11051@findex __builtin___vsnprintf_chk 11052@findex __builtin___printf_chk 11053@findex __builtin___vprintf_chk 11054@findex __builtin___fprintf_chk 11055@findex __builtin___vfprintf_chk 11056 11057GCC implements a limited buffer overflow protection mechanism that can 11058prevent some buffer overflow attacks by determining the sizes of objects 11059into which data is about to be written and preventing the writes when 11060the size isn't sufficient. The built-in functions described below yield 11061the best results when used together and when optimization is enabled. 11062For example, to detect object sizes across function boundaries or to 11063follow pointer assignments through non-trivial control flow they rely 11064on various optimization passes enabled with @option{-O2}. However, to 11065a limited extent, they can be used without optimization as well. 11066 11067@deftypefn {Built-in Function} {size_t} __builtin_object_size (const void * @var{ptr}, int @var{type}) 11068is a built-in construct that returns a constant number of bytes from 11069@var{ptr} to the end of the object @var{ptr} pointer points to 11070(if known at compile time). @code{__builtin_object_size} never evaluates 11071its arguments for side effects. If there are any side effects in them, it 11072returns @code{(size_t) -1} for @var{type} 0 or 1 and @code{(size_t) 0} 11073for @var{type} 2 or 3. If there are multiple objects @var{ptr} can 11074point to and all of them are known at compile time, the returned number 11075is the maximum of remaining byte counts in those objects if @var{type} & 2 is 110760 and minimum if nonzero. If it is not possible to determine which objects 11077@var{ptr} points to at compile time, @code{__builtin_object_size} should 11078return @code{(size_t) -1} for @var{type} 0 or 1 and @code{(size_t) 0} 11079for @var{type} 2 or 3. 11080 11081@var{type} is an integer constant from 0 to 3. If the least significant 11082bit is clear, objects are whole variables, if it is set, a closest 11083surrounding subobject is considered the object a pointer points to. 11084The second bit determines if maximum or minimum of remaining bytes 11085is computed. 11086 11087@smallexample 11088struct V @{ char buf1[10]; int b; char buf2[10]; @} var; 11089char *p = &var.buf1[1], *q = &var.b; 11090 11091/* Here the object p points to is var. */ 11092assert (__builtin_object_size (p, 0) == sizeof (var) - 1); 11093/* The subobject p points to is var.buf1. */ 11094assert (__builtin_object_size (p, 1) == sizeof (var.buf1) - 1); 11095/* The object q points to is var. */ 11096assert (__builtin_object_size (q, 0) 11097 == (char *) (&var + 1) - (char *) &var.b); 11098/* The subobject q points to is var.b. */ 11099assert (__builtin_object_size (q, 1) == sizeof (var.b)); 11100@end smallexample 11101@end deftypefn 11102 11103There are built-in functions added for many common string operation 11104functions, e.g., for @code{memcpy} @code{__builtin___memcpy_chk} 11105built-in is provided. This built-in has an additional last argument, 11106which is the number of bytes remaining in the object the @var{dest} 11107argument points to or @code{(size_t) -1} if the size is not known. 11108 11109The built-in functions are optimized into the normal string functions 11110like @code{memcpy} if the last argument is @code{(size_t) -1} or if 11111it is known at compile time that the destination object will not 11112be overflowed. If the compiler can determine at compile time that the 11113object will always be overflowed, it issues a warning. 11114 11115The intended use can be e.g.@: 11116 11117@smallexample 11118#undef memcpy 11119#define bos0(dest) __builtin_object_size (dest, 0) 11120#define memcpy(dest, src, n) \ 11121 __builtin___memcpy_chk (dest, src, n, bos0 (dest)) 11122 11123char *volatile p; 11124char buf[10]; 11125/* It is unknown what object p points to, so this is optimized 11126 into plain memcpy - no checking is possible. */ 11127memcpy (p, "abcde", n); 11128/* Destination is known and length too. It is known at compile 11129 time there will be no overflow. */ 11130memcpy (&buf[5], "abcde", 5); 11131/* Destination is known, but the length is not known at compile time. 11132 This will result in __memcpy_chk call that can check for overflow 11133 at run time. */ 11134memcpy (&buf[5], "abcde", n); 11135/* Destination is known and it is known at compile time there will 11136 be overflow. There will be a warning and __memcpy_chk call that 11137 will abort the program at run time. */ 11138memcpy (&buf[6], "abcde", 5); 11139@end smallexample 11140 11141Such built-in functions are provided for @code{memcpy}, @code{mempcpy}, 11142@code{memmove}, @code{memset}, @code{strcpy}, @code{stpcpy}, @code{strncpy}, 11143@code{strcat} and @code{strncat}. 11144 11145There are also checking built-in functions for formatted output functions. 11146@smallexample 11147int __builtin___sprintf_chk (char *s, int flag, size_t os, const char *fmt, ...); 11148int __builtin___snprintf_chk (char *s, size_t maxlen, int flag, size_t os, 11149 const char *fmt, ...); 11150int __builtin___vsprintf_chk (char *s, int flag, size_t os, const char *fmt, 11151 va_list ap); 11152int __builtin___vsnprintf_chk (char *s, size_t maxlen, int flag, size_t os, 11153 const char *fmt, va_list ap); 11154@end smallexample 11155 11156The added @var{flag} argument is passed unchanged to @code{__sprintf_chk} 11157etc.@: functions and can contain implementation specific flags on what 11158additional security measures the checking function might take, such as 11159handling @code{%n} differently. 11160 11161The @var{os} argument is the object size @var{s} points to, like in the 11162other built-in functions. There is a small difference in the behavior 11163though, if @var{os} is @code{(size_t) -1}, the built-in functions are 11164optimized into the non-checking functions only if @var{flag} is 0, otherwise 11165the checking function is called with @var{os} argument set to 11166@code{(size_t) -1}. 11167 11168In addition to this, there are checking built-in functions 11169@code{__builtin___printf_chk}, @code{__builtin___vprintf_chk}, 11170@code{__builtin___fprintf_chk} and @code{__builtin___vfprintf_chk}. 11171These have just one additional argument, @var{flag}, right before 11172format string @var{fmt}. If the compiler is able to optimize them to 11173@code{fputc} etc.@: functions, it does, otherwise the checking function 11174is called and the @var{flag} argument passed to it. 11175 11176@node Pointer Bounds Checker builtins 11177@section Pointer Bounds Checker Built-in Functions 11178@cindex Pointer Bounds Checker builtins 11179@findex __builtin___bnd_set_ptr_bounds 11180@findex __builtin___bnd_narrow_ptr_bounds 11181@findex __builtin___bnd_copy_ptr_bounds 11182@findex __builtin___bnd_init_ptr_bounds 11183@findex __builtin___bnd_null_ptr_bounds 11184@findex __builtin___bnd_store_ptr_bounds 11185@findex __builtin___bnd_chk_ptr_lbounds 11186@findex __builtin___bnd_chk_ptr_ubounds 11187@findex __builtin___bnd_chk_ptr_bounds 11188@findex __builtin___bnd_get_ptr_lbound 11189@findex __builtin___bnd_get_ptr_ubound 11190 11191GCC provides a set of built-in functions to control Pointer Bounds Checker 11192instrumentation. Note that all Pointer Bounds Checker builtins can be used 11193even if you compile with Pointer Bounds Checker off 11194(@option{-fno-check-pointer-bounds}). 11195The behavior may differ in such case as documented below. 11196 11197@deftypefn {Built-in Function} {void *} __builtin___bnd_set_ptr_bounds (const void *@var{q}, size_t @var{size}) 11198 11199This built-in function returns a new pointer with the value of @var{q}, and 11200associate it with the bounds [@var{q}, @var{q}+@var{size}-1]. With Pointer 11201Bounds Checker off, the built-in function just returns the first argument. 11202 11203@smallexample 11204extern void *__wrap_malloc (size_t n) 11205@{ 11206 void *p = (void *)__real_malloc (n); 11207 if (!p) return __builtin___bnd_null_ptr_bounds (p); 11208 return __builtin___bnd_set_ptr_bounds (p, n); 11209@} 11210@end smallexample 11211 11212@end deftypefn 11213 11214@deftypefn {Built-in Function} {void *} __builtin___bnd_narrow_ptr_bounds (const void *@var{p}, const void *@var{q}, size_t @var{size}) 11215 11216This built-in function returns a new pointer with the value of @var{p} 11217and associates it with the narrowed bounds formed by the intersection 11218of bounds associated with @var{q} and the bounds 11219[@var{p}, @var{p} + @var{size} - 1]. 11220With Pointer Bounds Checker off, the built-in function just returns the first 11221argument. 11222 11223@smallexample 11224void init_objects (object *objs, size_t size) 11225@{ 11226 size_t i; 11227 /* Initialize objects one-by-one passing pointers with bounds of 11228 an object, not the full array of objects. */ 11229 for (i = 0; i < size; i++) 11230 init_object (__builtin___bnd_narrow_ptr_bounds (objs + i, objs, 11231 sizeof(object))); 11232@} 11233@end smallexample 11234 11235@end deftypefn 11236 11237@deftypefn {Built-in Function} {void *} __builtin___bnd_copy_ptr_bounds (const void *@var{q}, const void *@var{r}) 11238 11239This built-in function returns a new pointer with the value of @var{q}, 11240and associates it with the bounds already associated with pointer @var{r}. 11241With Pointer Bounds Checker off, the built-in function just returns the first 11242argument. 11243 11244@smallexample 11245/* Here is a way to get pointer to object's field but 11246 still with the full object's bounds. */ 11247int *field_ptr = __builtin___bnd_copy_ptr_bounds (&objptr->int_field, 11248 objptr); 11249@end smallexample 11250 11251@end deftypefn 11252 11253@deftypefn {Built-in Function} {void *} __builtin___bnd_init_ptr_bounds (const void *@var{q}) 11254 11255This built-in function returns a new pointer with the value of @var{q}, and 11256associates it with INIT (allowing full memory access) bounds. With Pointer 11257Bounds Checker off, the built-in function just returns the first argument. 11258 11259@end deftypefn 11260 11261@deftypefn {Built-in Function} {void *} __builtin___bnd_null_ptr_bounds (const void *@var{q}) 11262 11263This built-in function returns a new pointer with the value of @var{q}, and 11264associates it with NULL (allowing no memory access) bounds. With Pointer 11265Bounds Checker off, the built-in function just returns the first argument. 11266 11267@end deftypefn 11268 11269@deftypefn {Built-in Function} void __builtin___bnd_store_ptr_bounds (const void **@var{ptr_addr}, const void *@var{ptr_val}) 11270 11271This built-in function stores the bounds associated with pointer @var{ptr_val} 11272and location @var{ptr_addr} into Bounds Table. This can be useful to propagate 11273bounds from legacy code without touching the associated pointer's memory when 11274pointers are copied as integers. With Pointer Bounds Checker off, the built-in 11275function call is ignored. 11276 11277@end deftypefn 11278 11279@deftypefn {Built-in Function} void __builtin___bnd_chk_ptr_lbounds (const void *@var{q}) 11280 11281This built-in function checks if the pointer @var{q} is within the lower 11282bound of its associated bounds. With Pointer Bounds Checker off, the built-in 11283function call is ignored. 11284 11285@smallexample 11286extern void *__wrap_memset (void *dst, int c, size_t len) 11287@{ 11288 if (len > 0) 11289 @{ 11290 __builtin___bnd_chk_ptr_lbounds (dst); 11291 __builtin___bnd_chk_ptr_ubounds ((char *)dst + len - 1); 11292 __real_memset (dst, c, len); 11293 @} 11294 return dst; 11295@} 11296@end smallexample 11297 11298@end deftypefn 11299 11300@deftypefn {Built-in Function} void __builtin___bnd_chk_ptr_ubounds (const void *@var{q}) 11301 11302This built-in function checks if the pointer @var{q} is within the upper 11303bound of its associated bounds. With Pointer Bounds Checker off, the built-in 11304function call is ignored. 11305 11306@end deftypefn 11307 11308@deftypefn {Built-in Function} void __builtin___bnd_chk_ptr_bounds (const void *@var{q}, size_t @var{size}) 11309 11310This built-in function checks if [@var{q}, @var{q} + @var{size} - 1] is within 11311the lower and upper bounds associated with @var{q}. With Pointer Bounds Checker 11312off, the built-in function call is ignored. 11313 11314@smallexample 11315extern void *__wrap_memcpy (void *dst, const void *src, size_t n) 11316@{ 11317 if (n > 0) 11318 @{ 11319 __bnd_chk_ptr_bounds (dst, n); 11320 __bnd_chk_ptr_bounds (src, n); 11321 __real_memcpy (dst, src, n); 11322 @} 11323 return dst; 11324@} 11325@end smallexample 11326 11327@end deftypefn 11328 11329@deftypefn {Built-in Function} {const void *} __builtin___bnd_get_ptr_lbound (const void *@var{q}) 11330 11331This built-in function returns the lower bound associated 11332with the pointer @var{q}, as a pointer value. 11333This is useful for debugging using @code{printf}. 11334With Pointer Bounds Checker off, the built-in function returns 0. 11335 11336@smallexample 11337void *lb = __builtin___bnd_get_ptr_lbound (q); 11338void *ub = __builtin___bnd_get_ptr_ubound (q); 11339printf ("q = %p lb(q) = %p ub(q) = %p", q, lb, ub); 11340@end smallexample 11341 11342@end deftypefn 11343 11344@deftypefn {Built-in Function} {const void *} __builtin___bnd_get_ptr_ubound (const void *@var{q}) 11345 11346This built-in function returns the upper bound (which is a pointer) associated 11347with the pointer @var{q}. With Pointer Bounds Checker off, 11348the built-in function returns -1. 11349 11350@end deftypefn 11351 11352@node Other Builtins 11353@section Other Built-in Functions Provided by GCC 11354@cindex built-in functions 11355@findex __builtin_alloca 11356@findex __builtin_alloca_with_align 11357@findex __builtin_alloca_with_align_and_max 11358@findex __builtin_call_with_static_chain 11359@findex __builtin_extend_pointer 11360@findex __builtin_fpclassify 11361@findex __builtin_isfinite 11362@findex __builtin_isnormal 11363@findex __builtin_isgreater 11364@findex __builtin_isgreaterequal 11365@findex __builtin_isinf_sign 11366@findex __builtin_isless 11367@findex __builtin_islessequal 11368@findex __builtin_islessgreater 11369@findex __builtin_isunordered 11370@findex __builtin_powi 11371@findex __builtin_powif 11372@findex __builtin_powil 11373@findex _Exit 11374@findex _exit 11375@findex abort 11376@findex abs 11377@findex acos 11378@findex acosf 11379@findex acosh 11380@findex acoshf 11381@findex acoshl 11382@findex acosl 11383@findex alloca 11384@findex asin 11385@findex asinf 11386@findex asinh 11387@findex asinhf 11388@findex asinhl 11389@findex asinl 11390@findex atan 11391@findex atan2 11392@findex atan2f 11393@findex atan2l 11394@findex atanf 11395@findex atanh 11396@findex atanhf 11397@findex atanhl 11398@findex atanl 11399@findex bcmp 11400@findex bzero 11401@findex cabs 11402@findex cabsf 11403@findex cabsl 11404@findex cacos 11405@findex cacosf 11406@findex cacosh 11407@findex cacoshf 11408@findex cacoshl 11409@findex cacosl 11410@findex calloc 11411@findex carg 11412@findex cargf 11413@findex cargl 11414@findex casin 11415@findex casinf 11416@findex casinh 11417@findex casinhf 11418@findex casinhl 11419@findex casinl 11420@findex catan 11421@findex catanf 11422@findex catanh 11423@findex catanhf 11424@findex catanhl 11425@findex catanl 11426@findex cbrt 11427@findex cbrtf 11428@findex cbrtl 11429@findex ccos 11430@findex ccosf 11431@findex ccosh 11432@findex ccoshf 11433@findex ccoshl 11434@findex ccosl 11435@findex ceil 11436@findex ceilf 11437@findex ceill 11438@findex cexp 11439@findex cexpf 11440@findex cexpl 11441@findex cimag 11442@findex cimagf 11443@findex cimagl 11444@findex clog 11445@findex clogf 11446@findex clogl 11447@findex clog10 11448@findex clog10f 11449@findex clog10l 11450@findex conj 11451@findex conjf 11452@findex conjl 11453@findex copysign 11454@findex copysignf 11455@findex copysignl 11456@findex cos 11457@findex cosf 11458@findex cosh 11459@findex coshf 11460@findex coshl 11461@findex cosl 11462@findex cpow 11463@findex cpowf 11464@findex cpowl 11465@findex cproj 11466@findex cprojf 11467@findex cprojl 11468@findex creal 11469@findex crealf 11470@findex creall 11471@findex csin 11472@findex csinf 11473@findex csinh 11474@findex csinhf 11475@findex csinhl 11476@findex csinl 11477@findex csqrt 11478@findex csqrtf 11479@findex csqrtl 11480@findex ctan 11481@findex ctanf 11482@findex ctanh 11483@findex ctanhf 11484@findex ctanhl 11485@findex ctanl 11486@findex dcgettext 11487@findex dgettext 11488@findex drem 11489@findex dremf 11490@findex dreml 11491@findex erf 11492@findex erfc 11493@findex erfcf 11494@findex erfcl 11495@findex erff 11496@findex erfl 11497@findex exit 11498@findex exp 11499@findex exp10 11500@findex exp10f 11501@findex exp10l 11502@findex exp2 11503@findex exp2f 11504@findex exp2l 11505@findex expf 11506@findex expl 11507@findex expm1 11508@findex expm1f 11509@findex expm1l 11510@findex fabs 11511@findex fabsf 11512@findex fabsl 11513@findex fdim 11514@findex fdimf 11515@findex fdiml 11516@findex ffs 11517@findex floor 11518@findex floorf 11519@findex floorl 11520@findex fma 11521@findex fmaf 11522@findex fmal 11523@findex fmax 11524@findex fmaxf 11525@findex fmaxl 11526@findex fmin 11527@findex fminf 11528@findex fminl 11529@findex fmod 11530@findex fmodf 11531@findex fmodl 11532@findex fprintf 11533@findex fprintf_unlocked 11534@findex fputs 11535@findex fputs_unlocked 11536@findex frexp 11537@findex frexpf 11538@findex frexpl 11539@findex fscanf 11540@findex gamma 11541@findex gammaf 11542@findex gammal 11543@findex gamma_r 11544@findex gammaf_r 11545@findex gammal_r 11546@findex gettext 11547@findex hypot 11548@findex hypotf 11549@findex hypotl 11550@findex ilogb 11551@findex ilogbf 11552@findex ilogbl 11553@findex imaxabs 11554@findex index 11555@findex isalnum 11556@findex isalpha 11557@findex isascii 11558@findex isblank 11559@findex iscntrl 11560@findex isdigit 11561@findex isgraph 11562@findex islower 11563@findex isprint 11564@findex ispunct 11565@findex isspace 11566@findex isupper 11567@findex iswalnum 11568@findex iswalpha 11569@findex iswblank 11570@findex iswcntrl 11571@findex iswdigit 11572@findex iswgraph 11573@findex iswlower 11574@findex iswprint 11575@findex iswpunct 11576@findex iswspace 11577@findex iswupper 11578@findex iswxdigit 11579@findex isxdigit 11580@findex j0 11581@findex j0f 11582@findex j0l 11583@findex j1 11584@findex j1f 11585@findex j1l 11586@findex jn 11587@findex jnf 11588@findex jnl 11589@findex labs 11590@findex ldexp 11591@findex ldexpf 11592@findex ldexpl 11593@findex lgamma 11594@findex lgammaf 11595@findex lgammal 11596@findex lgamma_r 11597@findex lgammaf_r 11598@findex lgammal_r 11599@findex llabs 11600@findex llrint 11601@findex llrintf 11602@findex llrintl 11603@findex llround 11604@findex llroundf 11605@findex llroundl 11606@findex log 11607@findex log10 11608@findex log10f 11609@findex log10l 11610@findex log1p 11611@findex log1pf 11612@findex log1pl 11613@findex log2 11614@findex log2f 11615@findex log2l 11616@findex logb 11617@findex logbf 11618@findex logbl 11619@findex logf 11620@findex logl 11621@findex lrint 11622@findex lrintf 11623@findex lrintl 11624@findex lround 11625@findex lroundf 11626@findex lroundl 11627@findex malloc 11628@findex memchr 11629@findex memcmp 11630@findex memcpy 11631@findex mempcpy 11632@findex memset 11633@findex modf 11634@findex modff 11635@findex modfl 11636@findex nearbyint 11637@findex nearbyintf 11638@findex nearbyintl 11639@findex nextafter 11640@findex nextafterf 11641@findex nextafterl 11642@findex nexttoward 11643@findex nexttowardf 11644@findex nexttowardl 11645@findex pow 11646@findex pow10 11647@findex pow10f 11648@findex pow10l 11649@findex powf 11650@findex powl 11651@findex printf 11652@findex printf_unlocked 11653@findex putchar 11654@findex puts 11655@findex remainder 11656@findex remainderf 11657@findex remainderl 11658@findex remquo 11659@findex remquof 11660@findex remquol 11661@findex rindex 11662@findex rint 11663@findex rintf 11664@findex rintl 11665@findex round 11666@findex roundf 11667@findex roundl 11668@findex scalb 11669@findex scalbf 11670@findex scalbl 11671@findex scalbln 11672@findex scalblnf 11673@findex scalblnf 11674@findex scalbn 11675@findex scalbnf 11676@findex scanfnl 11677@findex signbit 11678@findex signbitf 11679@findex signbitl 11680@findex signbitd32 11681@findex signbitd64 11682@findex signbitd128 11683@findex significand 11684@findex significandf 11685@findex significandl 11686@findex sin 11687@findex sincos 11688@findex sincosf 11689@findex sincosl 11690@findex sinf 11691@findex sinh 11692@findex sinhf 11693@findex sinhl 11694@findex sinl 11695@findex snprintf 11696@findex sprintf 11697@findex sqrt 11698@findex sqrtf 11699@findex sqrtl 11700@findex sscanf 11701@findex stpcpy 11702@findex stpncpy 11703@findex strcasecmp 11704@findex strcat 11705@findex strchr 11706@findex strcmp 11707@findex strcpy 11708@findex strcspn 11709@findex strdup 11710@findex strfmon 11711@findex strftime 11712@findex strlen 11713@findex strncasecmp 11714@findex strncat 11715@findex strncmp 11716@findex strncpy 11717@findex strndup 11718@findex strpbrk 11719@findex strrchr 11720@findex strspn 11721@findex strstr 11722@findex tan 11723@findex tanf 11724@findex tanh 11725@findex tanhf 11726@findex tanhl 11727@findex tanl 11728@findex tgamma 11729@findex tgammaf 11730@findex tgammal 11731@findex toascii 11732@findex tolower 11733@findex toupper 11734@findex towlower 11735@findex towupper 11736@findex trunc 11737@findex truncf 11738@findex truncl 11739@findex vfprintf 11740@findex vfscanf 11741@findex vprintf 11742@findex vscanf 11743@findex vsnprintf 11744@findex vsprintf 11745@findex vsscanf 11746@findex y0 11747@findex y0f 11748@findex y0l 11749@findex y1 11750@findex y1f 11751@findex y1l 11752@findex yn 11753@findex ynf 11754@findex ynl 11755 11756GCC provides a large number of built-in functions other than the ones 11757mentioned above. Some of these are for internal use in the processing 11758of exceptions or variable-length argument lists and are not 11759documented here because they may change from time to time; we do not 11760recommend general use of these functions. 11761 11762The remaining functions are provided for optimization purposes. 11763 11764With the exception of built-ins that have library equivalents such as 11765the standard C library functions discussed below, or that expand to 11766library calls, GCC built-in functions are always expanded inline and 11767thus do not have corresponding entry points and their address cannot 11768be obtained. Attempting to use them in an expression other than 11769a function call results in a compile-time error. 11770 11771@opindex fno-builtin 11772GCC includes built-in versions of many of the functions in the standard 11773C library. These functions come in two forms: one whose names start with 11774the @code{__builtin_} prefix, and the other without. Both forms have the 11775same type (including prototype), the same address (when their address is 11776taken), and the same meaning as the C library functions even if you specify 11777the @option{-fno-builtin} option @pxref{C Dialect Options}). Many of these 11778functions are only optimized in certain cases; if they are not optimized in 11779a particular case, a call to the library function is emitted. 11780 11781@opindex ansi 11782@opindex std 11783Outside strict ISO C mode (@option{-ansi}, @option{-std=c90}, 11784@option{-std=c99} or @option{-std=c11}), the functions 11785@code{_exit}, @code{alloca}, @code{bcmp}, @code{bzero}, 11786@code{dcgettext}, @code{dgettext}, @code{dremf}, @code{dreml}, 11787@code{drem}, @code{exp10f}, @code{exp10l}, @code{exp10}, @code{ffsll}, 11788@code{ffsl}, @code{ffs}, @code{fprintf_unlocked}, 11789@code{fputs_unlocked}, @code{gammaf}, @code{gammal}, @code{gamma}, 11790@code{gammaf_r}, @code{gammal_r}, @code{gamma_r}, @code{gettext}, 11791@code{index}, @code{isascii}, @code{j0f}, @code{j0l}, @code{j0}, 11792@code{j1f}, @code{j1l}, @code{j1}, @code{jnf}, @code{jnl}, @code{jn}, 11793@code{lgammaf_r}, @code{lgammal_r}, @code{lgamma_r}, @code{mempcpy}, 11794@code{pow10f}, @code{pow10l}, @code{pow10}, @code{printf_unlocked}, 11795@code{rindex}, @code{scalbf}, @code{scalbl}, @code{scalb}, 11796@code{signbit}, @code{signbitf}, @code{signbitl}, @code{signbitd32}, 11797@code{signbitd64}, @code{signbitd128}, @code{significandf}, 11798@code{significandl}, @code{significand}, @code{sincosf}, 11799@code{sincosl}, @code{sincos}, @code{stpcpy}, @code{stpncpy}, 11800@code{strcasecmp}, @code{strdup}, @code{strfmon}, @code{strncasecmp}, 11801@code{strndup}, @code{toascii}, @code{y0f}, @code{y0l}, @code{y0}, 11802@code{y1f}, @code{y1l}, @code{y1}, @code{ynf}, @code{ynl} and 11803@code{yn} 11804may be handled as built-in functions. 11805All these functions have corresponding versions 11806prefixed with @code{__builtin_}, which may be used even in strict C90 11807mode. 11808 11809The ISO C99 functions 11810@code{_Exit}, @code{acoshf}, @code{acoshl}, @code{acosh}, @code{asinhf}, 11811@code{asinhl}, @code{asinh}, @code{atanhf}, @code{atanhl}, @code{atanh}, 11812@code{cabsf}, @code{cabsl}, @code{cabs}, @code{cacosf}, @code{cacoshf}, 11813@code{cacoshl}, @code{cacosh}, @code{cacosl}, @code{cacos}, 11814@code{cargf}, @code{cargl}, @code{carg}, @code{casinf}, @code{casinhf}, 11815@code{casinhl}, @code{casinh}, @code{casinl}, @code{casin}, 11816@code{catanf}, @code{catanhf}, @code{catanhl}, @code{catanh}, 11817@code{catanl}, @code{catan}, @code{cbrtf}, @code{cbrtl}, @code{cbrt}, 11818@code{ccosf}, @code{ccoshf}, @code{ccoshl}, @code{ccosh}, @code{ccosl}, 11819@code{ccos}, @code{cexpf}, @code{cexpl}, @code{cexp}, @code{cimagf}, 11820@code{cimagl}, @code{cimag}, @code{clogf}, @code{clogl}, @code{clog}, 11821@code{conjf}, @code{conjl}, @code{conj}, @code{copysignf}, @code{copysignl}, 11822@code{copysign}, @code{cpowf}, @code{cpowl}, @code{cpow}, @code{cprojf}, 11823@code{cprojl}, @code{cproj}, @code{crealf}, @code{creall}, @code{creal}, 11824@code{csinf}, @code{csinhf}, @code{csinhl}, @code{csinh}, @code{csinl}, 11825@code{csin}, @code{csqrtf}, @code{csqrtl}, @code{csqrt}, @code{ctanf}, 11826@code{ctanhf}, @code{ctanhl}, @code{ctanh}, @code{ctanl}, @code{ctan}, 11827@code{erfcf}, @code{erfcl}, @code{erfc}, @code{erff}, @code{erfl}, 11828@code{erf}, @code{exp2f}, @code{exp2l}, @code{exp2}, @code{expm1f}, 11829@code{expm1l}, @code{expm1}, @code{fdimf}, @code{fdiml}, @code{fdim}, 11830@code{fmaf}, @code{fmal}, @code{fmaxf}, @code{fmaxl}, @code{fmax}, 11831@code{fma}, @code{fminf}, @code{fminl}, @code{fmin}, @code{hypotf}, 11832@code{hypotl}, @code{hypot}, @code{ilogbf}, @code{ilogbl}, @code{ilogb}, 11833@code{imaxabs}, @code{isblank}, @code{iswblank}, @code{lgammaf}, 11834@code{lgammal}, @code{lgamma}, @code{llabs}, @code{llrintf}, @code{llrintl}, 11835@code{llrint}, @code{llroundf}, @code{llroundl}, @code{llround}, 11836@code{log1pf}, @code{log1pl}, @code{log1p}, @code{log2f}, @code{log2l}, 11837@code{log2}, @code{logbf}, @code{logbl}, @code{logb}, @code{lrintf}, 11838@code{lrintl}, @code{lrint}, @code{lroundf}, @code{lroundl}, 11839@code{lround}, @code{nearbyintf}, @code{nearbyintl}, @code{nearbyint}, 11840@code{nextafterf}, @code{nextafterl}, @code{nextafter}, 11841@code{nexttowardf}, @code{nexttowardl}, @code{nexttoward}, 11842@code{remainderf}, @code{remainderl}, @code{remainder}, @code{remquof}, 11843@code{remquol}, @code{remquo}, @code{rintf}, @code{rintl}, @code{rint}, 11844@code{roundf}, @code{roundl}, @code{round}, @code{scalblnf}, 11845@code{scalblnl}, @code{scalbln}, @code{scalbnf}, @code{scalbnl}, 11846@code{scalbn}, @code{snprintf}, @code{tgammaf}, @code{tgammal}, 11847@code{tgamma}, @code{truncf}, @code{truncl}, @code{trunc}, 11848@code{vfscanf}, @code{vscanf}, @code{vsnprintf} and @code{vsscanf} 11849are handled as built-in functions 11850except in strict ISO C90 mode (@option{-ansi} or @option{-std=c90}). 11851 11852There are also built-in versions of the ISO C99 functions 11853@code{acosf}, @code{acosl}, @code{asinf}, @code{asinl}, @code{atan2f}, 11854@code{atan2l}, @code{atanf}, @code{atanl}, @code{ceilf}, @code{ceill}, 11855@code{cosf}, @code{coshf}, @code{coshl}, @code{cosl}, @code{expf}, 11856@code{expl}, @code{fabsf}, @code{fabsl}, @code{floorf}, @code{floorl}, 11857@code{fmodf}, @code{fmodl}, @code{frexpf}, @code{frexpl}, @code{ldexpf}, 11858@code{ldexpl}, @code{log10f}, @code{log10l}, @code{logf}, @code{logl}, 11859@code{modfl}, @code{modf}, @code{powf}, @code{powl}, @code{sinf}, 11860@code{sinhf}, @code{sinhl}, @code{sinl}, @code{sqrtf}, @code{sqrtl}, 11861@code{tanf}, @code{tanhf}, @code{tanhl} and @code{tanl} 11862that are recognized in any mode since ISO C90 reserves these names for 11863the purpose to which ISO C99 puts them. All these functions have 11864corresponding versions prefixed with @code{__builtin_}. 11865 11866There are also built-in functions @code{__builtin_fabsf@var{n}}, 11867@code{__builtin_fabsf@var{n}x}, @code{__builtin_copysignf@var{n}} and 11868@code{__builtin_copysignf@var{n}x}, corresponding to the TS 18661-3 11869functions @code{fabsf@var{n}}, @code{fabsf@var{n}x}, 11870@code{copysignf@var{n}} and @code{copysignf@var{n}x}, for supported 11871types @code{_Float@var{n}} and @code{_Float@var{n}x}. 11872 11873There are also GNU extension functions @code{clog10}, @code{clog10f} and 11874@code{clog10l} which names are reserved by ISO C99 for future use. 11875All these functions have versions prefixed with @code{__builtin_}. 11876 11877The ISO C94 functions 11878@code{iswalnum}, @code{iswalpha}, @code{iswcntrl}, @code{iswdigit}, 11879@code{iswgraph}, @code{iswlower}, @code{iswprint}, @code{iswpunct}, 11880@code{iswspace}, @code{iswupper}, @code{iswxdigit}, @code{towlower} and 11881@code{towupper} 11882are handled as built-in functions 11883except in strict ISO C90 mode (@option{-ansi} or @option{-std=c90}). 11884 11885The ISO C90 functions 11886@code{abort}, @code{abs}, @code{acos}, @code{asin}, @code{atan2}, 11887@code{atan}, @code{calloc}, @code{ceil}, @code{cosh}, @code{cos}, 11888@code{exit}, @code{exp}, @code{fabs}, @code{floor}, @code{fmod}, 11889@code{fprintf}, @code{fputs}, @code{frexp}, @code{fscanf}, 11890@code{isalnum}, @code{isalpha}, @code{iscntrl}, @code{isdigit}, 11891@code{isgraph}, @code{islower}, @code{isprint}, @code{ispunct}, 11892@code{isspace}, @code{isupper}, @code{isxdigit}, @code{tolower}, 11893@code{toupper}, @code{labs}, @code{ldexp}, @code{log10}, @code{log}, 11894@code{malloc}, @code{memchr}, @code{memcmp}, @code{memcpy}, 11895@code{memset}, @code{modf}, @code{pow}, @code{printf}, @code{putchar}, 11896@code{puts}, @code{scanf}, @code{sinh}, @code{sin}, @code{snprintf}, 11897@code{sprintf}, @code{sqrt}, @code{sscanf}, @code{strcat}, 11898@code{strchr}, @code{strcmp}, @code{strcpy}, @code{strcspn}, 11899@code{strlen}, @code{strncat}, @code{strncmp}, @code{strncpy}, 11900@code{strpbrk}, @code{strrchr}, @code{strspn}, @code{strstr}, 11901@code{tanh}, @code{tan}, @code{vfprintf}, @code{vprintf} and @code{vsprintf} 11902are all recognized as built-in functions unless 11903@option{-fno-builtin} is specified (or @option{-fno-builtin-@var{function}} 11904is specified for an individual function). All of these functions have 11905corresponding versions prefixed with @code{__builtin_}. 11906 11907GCC provides built-in versions of the ISO C99 floating-point comparison 11908macros that avoid raising exceptions for unordered operands. They have 11909the same names as the standard macros ( @code{isgreater}, 11910@code{isgreaterequal}, @code{isless}, @code{islessequal}, 11911@code{islessgreater}, and @code{isunordered}) , with @code{__builtin_} 11912prefixed. We intend for a library implementor to be able to simply 11913@code{#define} each standard macro to its built-in equivalent. 11914In the same fashion, GCC provides @code{fpclassify}, @code{isfinite}, 11915@code{isinf_sign}, @code{isnormal} and @code{signbit} built-ins used with 11916@code{__builtin_} prefixed. The @code{isinf} and @code{isnan} 11917built-in functions appear both with and without the @code{__builtin_} prefix. 11918 11919@deftypefn {Built-in Function} void *__builtin_alloca (size_t size) 11920The @code{__builtin_alloca} function must be called at block scope. 11921The function allocates an object @var{size} bytes large on the stack 11922of the calling function. The object is aligned on the default stack 11923alignment boundary for the target determined by the 11924@code{__BIGGEST_ALIGNMENT__} macro. The @code{__builtin_alloca} 11925function returns a pointer to the first byte of the allocated object. 11926The lifetime of the allocated object ends just before the calling 11927function returns to its caller. This is so even when 11928@code{__builtin_alloca} is called within a nested block. 11929 11930For example, the following function allocates eight objects of @code{n} 11931bytes each on the stack, storing a pointer to each in consecutive elements 11932of the array @code{a}. It then passes the array to function @code{g} 11933which can safely use the storage pointed to by each of the array elements. 11934 11935@smallexample 11936void f (unsigned n) 11937@{ 11938 void *a [8]; 11939 for (int i = 0; i != 8; ++i) 11940 a [i] = __builtin_alloca (n); 11941 11942 g (a, n); // @r{safe} 11943@} 11944@end smallexample 11945 11946Since the @code{__builtin_alloca} function doesn't validate its argument 11947it is the responsibility of its caller to make sure the argument doesn't 11948cause it to exceed the stack size limit. 11949The @code{__builtin_alloca} function is provided to make it possible to 11950allocate on the stack arrays of bytes with an upper bound that may be 11951computed at run time. Since C99 Variable Length Arrays offer 11952similar functionality under a portable, more convenient, and safer 11953interface they are recommended instead, in both C99 and C++ programs 11954where GCC provides them as an extension. 11955@xref{Variable Length}, for details. 11956 11957@end deftypefn 11958 11959@deftypefn {Built-in Function} void *__builtin_alloca_with_align (size_t size, size_t alignment) 11960The @code{__builtin_alloca_with_align} function must be called at block 11961scope. The function allocates an object @var{size} bytes large on 11962the stack of the calling function. The allocated object is aligned on 11963the boundary specified by the argument @var{alignment} whose unit is given 11964in bits (not bytes). The @var{size} argument must be positive and not 11965exceed the stack size limit. The @var{alignment} argument must be a constant 11966integer expression that evaluates to a power of 2 greater than or equal to 11967@code{CHAR_BIT} and less than some unspecified maximum. Invocations 11968with other values are rejected with an error indicating the valid bounds. 11969The function returns a pointer to the first byte of the allocated object. 11970The lifetime of the allocated object ends at the end of the block in which 11971the function was called. The allocated storage is released no later than 11972just before the calling function returns to its caller, but may be released 11973at the end of the block in which the function was called. 11974 11975For example, in the following function the call to @code{g} is unsafe 11976because when @code{overalign} is non-zero, the space allocated by 11977@code{__builtin_alloca_with_align} may have been released at the end 11978of the @code{if} statement in which it was called. 11979 11980@smallexample 11981void f (unsigned n, bool overalign) 11982@{ 11983 void *p; 11984 if (overalign) 11985 p = __builtin_alloca_with_align (n, 64 /* bits */); 11986 else 11987 p = __builtin_alloc (n); 11988 11989 g (p, n); // @r{unsafe} 11990@} 11991@end smallexample 11992 11993Since the @code{__builtin_alloca_with_align} function doesn't validate its 11994@var{size} argument it is the responsibility of its caller to make sure 11995the argument doesn't cause it to exceed the stack size limit. 11996The @code{__builtin_alloca_with_align} function is provided to make 11997it possible to allocate on the stack overaligned arrays of bytes with 11998an upper bound that may be computed at run time. Since C99 11999Variable Length Arrays offer the same functionality under 12000a portable, more convenient, and safer interface they are recommended 12001instead, in both C99 and C++ programs where GCC provides them as 12002an extension. @xref{Variable Length}, for details. 12003 12004@end deftypefn 12005 12006@deftypefn {Built-in Function} void *__builtin_alloca_with_align_and_max (size_t size, size_t alignment, size_t max_size) 12007Similar to @code{__builtin_alloca_with_align} but takes an extra argument 12008specifying an upper bound for @var{size} in case its value cannot be computed 12009at compile time, for use by @option{-fstack-usage}, @option{-Wstack-usage} 12010and @option{-Walloca-larger-than}. @var{max_size} must be a constant integer 12011expression, it has no effect on code generation and no attempt is made to 12012check its compatibility with @var{size}. 12013 12014@end deftypefn 12015 12016@deftypefn {Built-in Function} int __builtin_types_compatible_p (@var{type1}, @var{type2}) 12017 12018You can use the built-in function @code{__builtin_types_compatible_p} to 12019determine whether two types are the same. 12020 12021This built-in function returns 1 if the unqualified versions of the 12022types @var{type1} and @var{type2} (which are types, not expressions) are 12023compatible, 0 otherwise. The result of this built-in function can be 12024used in integer constant expressions. 12025 12026This built-in function ignores top level qualifiers (e.g., @code{const}, 12027@code{volatile}). For example, @code{int} is equivalent to @code{const 12028int}. 12029 12030The type @code{int[]} and @code{int[5]} are compatible. On the other 12031hand, @code{int} and @code{char *} are not compatible, even if the size 12032of their types, on the particular architecture are the same. Also, the 12033amount of pointer indirection is taken into account when determining 12034similarity. Consequently, @code{short *} is not similar to 12035@code{short **}. Furthermore, two types that are typedefed are 12036considered compatible if their underlying types are compatible. 12037 12038An @code{enum} type is not considered to be compatible with another 12039@code{enum} type even if both are compatible with the same integer 12040type; this is what the C standard specifies. 12041For example, @code{enum @{foo, bar@}} is not similar to 12042@code{enum @{hot, dog@}}. 12043 12044You typically use this function in code whose execution varies 12045depending on the arguments' types. For example: 12046 12047@smallexample 12048#define foo(x) \ 12049 (@{ \ 12050 typeof (x) tmp = (x); \ 12051 if (__builtin_types_compatible_p (typeof (x), long double)) \ 12052 tmp = foo_long_double (tmp); \ 12053 else if (__builtin_types_compatible_p (typeof (x), double)) \ 12054 tmp = foo_double (tmp); \ 12055 else if (__builtin_types_compatible_p (typeof (x), float)) \ 12056 tmp = foo_float (tmp); \ 12057 else \ 12058 abort (); \ 12059 tmp; \ 12060 @}) 12061@end smallexample 12062 12063@emph{Note:} This construct is only available for C@. 12064 12065@end deftypefn 12066 12067@deftypefn {Built-in Function} @var{type} __builtin_call_with_static_chain (@var{call_exp}, @var{pointer_exp}) 12068 12069The @var{call_exp} expression must be a function call, and the 12070@var{pointer_exp} expression must be a pointer. The @var{pointer_exp} 12071is passed to the function call in the target's static chain location. 12072The result of builtin is the result of the function call. 12073 12074@emph{Note:} This builtin is only available for C@. 12075This builtin can be used to call Go closures from C. 12076 12077@end deftypefn 12078 12079@deftypefn {Built-in Function} @var{type} __builtin_choose_expr (@var{const_exp}, @var{exp1}, @var{exp2}) 12080 12081You can use the built-in function @code{__builtin_choose_expr} to 12082evaluate code depending on the value of a constant expression. This 12083built-in function returns @var{exp1} if @var{const_exp}, which is an 12084integer constant expression, is nonzero. Otherwise it returns @var{exp2}. 12085 12086This built-in function is analogous to the @samp{? :} operator in C, 12087except that the expression returned has its type unaltered by promotion 12088rules. Also, the built-in function does not evaluate the expression 12089that is not chosen. For example, if @var{const_exp} evaluates to true, 12090@var{exp2} is not evaluated even if it has side effects. 12091 12092This built-in function can return an lvalue if the chosen argument is an 12093lvalue. 12094 12095If @var{exp1} is returned, the return type is the same as @var{exp1}'s 12096type. Similarly, if @var{exp2} is returned, its return type is the same 12097as @var{exp2}. 12098 12099Example: 12100 12101@smallexample 12102#define foo(x) \ 12103 __builtin_choose_expr ( \ 12104 __builtin_types_compatible_p (typeof (x), double), \ 12105 foo_double (x), \ 12106 __builtin_choose_expr ( \ 12107 __builtin_types_compatible_p (typeof (x), float), \ 12108 foo_float (x), \ 12109 /* @r{The void expression results in a compile-time error} \ 12110 @r{when assigning the result to something.} */ \ 12111 (void)0)) 12112@end smallexample 12113 12114@emph{Note:} This construct is only available for C@. Furthermore, the 12115unused expression (@var{exp1} or @var{exp2} depending on the value of 12116@var{const_exp}) may still generate syntax errors. This may change in 12117future revisions. 12118 12119@end deftypefn 12120 12121@deftypefn {Built-in Function} @var{type} __builtin_tgmath (@var{functions}, @var{arguments}) 12122 12123The built-in function @code{__builtin_tgmath}, available only for C 12124and Objective-C, calls a function determined according to the rules of 12125@code{<tgmath.h>} macros. It is intended to be used in 12126implementations of that header, so that expansions of macros from that 12127header only expand each of their arguments once, to avoid problems 12128when calls to such macros are nested inside the arguments of other 12129calls to such macros; in addition, it results in better diagnostics 12130for invalid calls to @code{<tgmath.h>} macros than implementations 12131using other GNU C language features. For example, the @code{pow} 12132type-generic macro might be defined as: 12133 12134@smallexample 12135#define pow(a, b) __builtin_tgmath (powf, pow, powl, \ 12136 cpowf, cpow, cpowl, a, b) 12137@end smallexample 12138 12139The arguments to @code{__builtin_tgmath} are at least two pointers to 12140functions, followed by the arguments to the type-generic macro (which 12141will be passed as arguments to the selected function). All the 12142pointers to functions must be pointers to prototyped functions, none 12143of which may have variable arguments, and all of which must have the 12144same number of parameters; the number of parameters of the first 12145function determines how many arguments to @code{__builtin_tgmath} are 12146interpreted as function pointers, and how many as the arguments to the 12147called function. 12148 12149The types of the specified functions must all be different, but 12150related to each other in the same way as a set of functions that may 12151be selected between by a macro in @code{<tgmath.h>}. This means that 12152the functions are parameterized by a floating-point type @var{t}, 12153different for each such function. The function return types may all 12154be the same type, or they may be @var{t} for each function, or they 12155may be the real type corresponding to @var{t} for each function (if 12156some of the types @var{t} are complex). Likewise, for each parameter 12157position, the type of the parameter in that position may always be the 12158same type, or may be @var{t} for each function (this case must apply 12159for at least one parameter position), or may be the real type 12160corresponding to @var{t} for each function. 12161 12162The standard rules for @code{<tgmath.h>} macros are used to find a 12163common type @var{u} from the types of the arguments for parameters 12164whose types vary between the functions; complex integer types (a GNU 12165extension) are treated like @code{_Complex double} for this purpose 12166(or @code{_Complex _Float64} if all the function return types are the 12167same @code{_Float@var{n}} or @code{_Float@var{n}x} type). 12168If the function return types vary, or are all the same integer type, 12169the function called is the one for which @var{t} is @var{u}, and it is 12170an error if there is no such function. If the function return types 12171are all the same floating-point type, the type-generic macro is taken 12172to be one of those from TS 18661 that rounds the result to a narrower 12173type; if there is a function for which @var{t} is @var{u}, it is 12174called, and otherwise the first function, if any, for which @var{t} 12175has at least the range and precision of @var{u} is called, and it is 12176an error if there is no such function. 12177 12178@end deftypefn 12179 12180@deftypefn {Built-in Function} @var{type} __builtin_complex (@var{real}, @var{imag}) 12181 12182The built-in function @code{__builtin_complex} is provided for use in 12183implementing the ISO C11 macros @code{CMPLXF}, @code{CMPLX} and 12184@code{CMPLXL}. @var{real} and @var{imag} must have the same type, a 12185real binary floating-point type, and the result has the corresponding 12186complex type with real and imaginary parts @var{real} and @var{imag}. 12187Unlike @samp{@var{real} + I * @var{imag}}, this works even when 12188infinities, NaNs and negative zeros are involved. 12189 12190@end deftypefn 12191 12192@deftypefn {Built-in Function} int __builtin_constant_p (@var{exp}) 12193You can use the built-in function @code{__builtin_constant_p} to 12194determine if a value is known to be constant at compile time and hence 12195that GCC can perform constant-folding on expressions involving that 12196value. The argument of the function is the value to test. The function 12197returns the integer 1 if the argument is known to be a compile-time 12198constant and 0 if it is not known to be a compile-time constant. A 12199return of 0 does not indicate that the value is @emph{not} a constant, 12200but merely that GCC cannot prove it is a constant with the specified 12201value of the @option{-O} option. 12202 12203You typically use this function in an embedded application where 12204memory is a critical resource. If you have some complex calculation, 12205you may want it to be folded if it involves constants, but need to call 12206a function if it does not. For example: 12207 12208@smallexample 12209#define Scale_Value(X) \ 12210 (__builtin_constant_p (X) \ 12211 ? ((X) * SCALE + OFFSET) : Scale (X)) 12212@end smallexample 12213 12214You may use this built-in function in either a macro or an inline 12215function. However, if you use it in an inlined function and pass an 12216argument of the function as the argument to the built-in, GCC 12217never returns 1 when you call the inline function with a string constant 12218or compound literal (@pxref{Compound Literals}) and does not return 1 12219when you pass a constant numeric value to the inline function unless you 12220specify the @option{-O} option. 12221 12222You may also use @code{__builtin_constant_p} in initializers for static 12223data. For instance, you can write 12224 12225@smallexample 12226static const int table[] = @{ 12227 __builtin_constant_p (EXPRESSION) ? (EXPRESSION) : -1, 12228 /* @r{@dots{}} */ 12229@}; 12230@end smallexample 12231 12232@noindent 12233This is an acceptable initializer even if @var{EXPRESSION} is not a 12234constant expression, including the case where 12235@code{__builtin_constant_p} returns 1 because @var{EXPRESSION} can be 12236folded to a constant but @var{EXPRESSION} contains operands that are 12237not otherwise permitted in a static initializer (for example, 12238@code{0 && foo ()}). GCC must be more conservative about evaluating the 12239built-in in this case, because it has no opportunity to perform 12240optimization. 12241@end deftypefn 12242 12243@deftypefn {Built-in Function} long __builtin_expect (long @var{exp}, long @var{c}) 12244@opindex fprofile-arcs 12245You may use @code{__builtin_expect} to provide the compiler with 12246branch prediction information. In general, you should prefer to 12247use actual profile feedback for this (@option{-fprofile-arcs}), as 12248programmers are notoriously bad at predicting how their programs 12249actually perform. However, there are applications in which this 12250data is hard to collect. 12251 12252The return value is the value of @var{exp}, which should be an integral 12253expression. The semantics of the built-in are that it is expected that 12254@var{exp} == @var{c}. For example: 12255 12256@smallexample 12257if (__builtin_expect (x, 0)) 12258 foo (); 12259@end smallexample 12260 12261@noindent 12262indicates that we do not expect to call @code{foo}, since 12263we expect @code{x} to be zero. Since you are limited to integral 12264expressions for @var{exp}, you should use constructions such as 12265 12266@smallexample 12267if (__builtin_expect (ptr != NULL, 1)) 12268 foo (*ptr); 12269@end smallexample 12270 12271@noindent 12272when testing pointer or floating-point values. 12273@end deftypefn 12274 12275@deftypefn {Built-in Function} void __builtin_trap (void) 12276This function causes the program to exit abnormally. GCC implements 12277this function by using a target-dependent mechanism (such as 12278intentionally executing an illegal instruction) or by calling 12279@code{abort}. The mechanism used may vary from release to release so 12280you should not rely on any particular implementation. 12281@end deftypefn 12282 12283@deftypefn {Built-in Function} void __builtin_unreachable (void) 12284If control flow reaches the point of the @code{__builtin_unreachable}, 12285the program is undefined. It is useful in situations where the 12286compiler cannot deduce the unreachability of the code. 12287 12288One such case is immediately following an @code{asm} statement that 12289either never terminates, or one that transfers control elsewhere 12290and never returns. In this example, without the 12291@code{__builtin_unreachable}, GCC issues a warning that control 12292reaches the end of a non-void function. It also generates code 12293to return after the @code{asm}. 12294 12295@smallexample 12296int f (int c, int v) 12297@{ 12298 if (c) 12299 @{ 12300 return v; 12301 @} 12302 else 12303 @{ 12304 asm("jmp error_handler"); 12305 __builtin_unreachable (); 12306 @} 12307@} 12308@end smallexample 12309 12310@noindent 12311Because the @code{asm} statement unconditionally transfers control out 12312of the function, control never reaches the end of the function 12313body. The @code{__builtin_unreachable} is in fact unreachable and 12314communicates this fact to the compiler. 12315 12316Another use for @code{__builtin_unreachable} is following a call a 12317function that never returns but that is not declared 12318@code{__attribute__((noreturn))}, as in this example: 12319 12320@smallexample 12321void function_that_never_returns (void); 12322 12323int g (int c) 12324@{ 12325 if (c) 12326 @{ 12327 return 1; 12328 @} 12329 else 12330 @{ 12331 function_that_never_returns (); 12332 __builtin_unreachable (); 12333 @} 12334@} 12335@end smallexample 12336 12337@end deftypefn 12338 12339@deftypefn {Built-in Function} {void *} __builtin_assume_aligned (const void *@var{exp}, size_t @var{align}, ...) 12340This function returns its first argument, and allows the compiler 12341to assume that the returned pointer is at least @var{align} bytes 12342aligned. This built-in can have either two or three arguments, 12343if it has three, the third argument should have integer type, and 12344if it is nonzero means misalignment offset. For example: 12345 12346@smallexample 12347void *x = __builtin_assume_aligned (arg, 16); 12348@end smallexample 12349 12350@noindent 12351means that the compiler can assume @code{x}, set to @code{arg}, is at least 1235216-byte aligned, while: 12353 12354@smallexample 12355void *x = __builtin_assume_aligned (arg, 32, 8); 12356@end smallexample 12357 12358@noindent 12359means that the compiler can assume for @code{x}, set to @code{arg}, that 12360@code{(char *) x - 8} is 32-byte aligned. 12361@end deftypefn 12362 12363@deftypefn {Built-in Function} int __builtin_LINE () 12364This function is the equivalent of the preprocessor @code{__LINE__} 12365macro and returns a constant integer expression that evaluates to 12366the line number of the invocation of the built-in. When used as a C++ 12367default argument for a function @var{F}, it returns the line number 12368of the call to @var{F}. 12369@end deftypefn 12370 12371@deftypefn {Built-in Function} {const char *} __builtin_FUNCTION () 12372This function is the equivalent of the @code{__FUNCTION__} symbol 12373and returns an address constant pointing to the name of the function 12374from which the built-in was invoked, or the empty string if 12375the invocation is not at function scope. When used as a C++ default 12376argument for a function @var{F}, it returns the name of @var{F}'s 12377caller or the empty string if the call was not made at function 12378scope. 12379@end deftypefn 12380 12381@deftypefn {Built-in Function} {const char *} __builtin_FILE () 12382This function is the equivalent of the preprocessor @code{__FILE__} 12383macro and returns an address constant pointing to the file name 12384containing the invocation of the built-in, or the empty string if 12385the invocation is not at function scope. When used as a C++ default 12386argument for a function @var{F}, it returns the file name of the call 12387to @var{F} or the empty string if the call was not made at function 12388scope. 12389 12390For example, in the following, each call to function @code{foo} will 12391print a line similar to @code{"file.c:123: foo: message"} with the name 12392of the file and the line number of the @code{printf} call, the name of 12393the function @code{foo}, followed by the word @code{message}. 12394 12395@smallexample 12396const char* 12397function (const char *func = __builtin_FUNCTION ()) 12398@{ 12399 return func; 12400@} 12401 12402void foo (void) 12403@{ 12404 printf ("%s:%i: %s: message\n", file (), line (), function ()); 12405@} 12406@end smallexample 12407 12408@end deftypefn 12409 12410@deftypefn {Built-in Function} void __builtin___clear_cache (char *@var{begin}, char *@var{end}) 12411This function is used to flush the processor's instruction cache for 12412the region of memory between @var{begin} inclusive and @var{end} 12413exclusive. Some targets require that the instruction cache be 12414flushed, after modifying memory containing code, in order to obtain 12415deterministic behavior. 12416 12417If the target does not require instruction cache flushes, 12418@code{__builtin___clear_cache} has no effect. Otherwise either 12419instructions are emitted in-line to clear the instruction cache or a 12420call to the @code{__clear_cache} function in libgcc is made. 12421@end deftypefn 12422 12423@deftypefn {Built-in Function} void __builtin_prefetch (const void *@var{addr}, ...) 12424This function is used to minimize cache-miss latency by moving data into 12425a cache before it is accessed. 12426You can insert calls to @code{__builtin_prefetch} into code for which 12427you know addresses of data in memory that is likely to be accessed soon. 12428If the target supports them, data prefetch instructions are generated. 12429If the prefetch is done early enough before the access then the data will 12430be in the cache by the time it is accessed. 12431 12432The value of @var{addr} is the address of the memory to prefetch. 12433There are two optional arguments, @var{rw} and @var{locality}. 12434The value of @var{rw} is a compile-time constant one or zero; one 12435means that the prefetch is preparing for a write to the memory address 12436and zero, the default, means that the prefetch is preparing for a read. 12437The value @var{locality} must be a compile-time constant integer between 12438zero and three. A value of zero means that the data has no temporal 12439locality, so it need not be left in the cache after the access. A value 12440of three means that the data has a high degree of temporal locality and 12441should be left in all levels of cache possible. Values of one and two 12442mean, respectively, a low or moderate degree of temporal locality. The 12443default is three. 12444 12445@smallexample 12446for (i = 0; i < n; i++) 12447 @{ 12448 a[i] = a[i] + b[i]; 12449 __builtin_prefetch (&a[i+j], 1, 1); 12450 __builtin_prefetch (&b[i+j], 0, 1); 12451 /* @r{@dots{}} */ 12452 @} 12453@end smallexample 12454 12455Data prefetch does not generate faults if @var{addr} is invalid, but 12456the address expression itself must be valid. For example, a prefetch 12457of @code{p->next} does not fault if @code{p->next} is not a valid 12458address, but evaluation faults if @code{p} is not a valid address. 12459 12460If the target does not support data prefetch, the address expression 12461is evaluated if it includes side effects but no other code is generated 12462and GCC does not issue a warning. 12463@end deftypefn 12464 12465@deftypefn {Built-in Function} double __builtin_huge_val (void) 12466Returns a positive infinity, if supported by the floating-point format, 12467else @code{DBL_MAX}. This function is suitable for implementing the 12468ISO C macro @code{HUGE_VAL}. 12469@end deftypefn 12470 12471@deftypefn {Built-in Function} float __builtin_huge_valf (void) 12472Similar to @code{__builtin_huge_val}, except the return type is @code{float}. 12473@end deftypefn 12474 12475@deftypefn {Built-in Function} {long double} __builtin_huge_vall (void) 12476Similar to @code{__builtin_huge_val}, except the return 12477type is @code{long double}. 12478@end deftypefn 12479 12480@deftypefn {Built-in Function} _Float@var{n} __builtin_huge_valf@var{n} (void) 12481Similar to @code{__builtin_huge_val}, except the return type is 12482@code{_Float@var{n}}. 12483@end deftypefn 12484 12485@deftypefn {Built-in Function} _Float@var{n}x __builtin_huge_valf@var{n}x (void) 12486Similar to @code{__builtin_huge_val}, except the return type is 12487@code{_Float@var{n}x}. 12488@end deftypefn 12489 12490@deftypefn {Built-in Function} int __builtin_fpclassify (int, int, int, int, int, ...) 12491This built-in implements the C99 fpclassify functionality. The first 12492five int arguments should be the target library's notion of the 12493possible FP classes and are used for return values. They must be 12494constant values and they must appear in this order: @code{FP_NAN}, 12495@code{FP_INFINITE}, @code{FP_NORMAL}, @code{FP_SUBNORMAL} and 12496@code{FP_ZERO}. The ellipsis is for exactly one floating-point value 12497to classify. GCC treats the last argument as type-generic, which 12498means it does not do default promotion from float to double. 12499@end deftypefn 12500 12501@deftypefn {Built-in Function} double __builtin_inf (void) 12502Similar to @code{__builtin_huge_val}, except a warning is generated 12503if the target floating-point format does not support infinities. 12504@end deftypefn 12505 12506@deftypefn {Built-in Function} _Decimal32 __builtin_infd32 (void) 12507Similar to @code{__builtin_inf}, except the return type is @code{_Decimal32}. 12508@end deftypefn 12509 12510@deftypefn {Built-in Function} _Decimal64 __builtin_infd64 (void) 12511Similar to @code{__builtin_inf}, except the return type is @code{_Decimal64}. 12512@end deftypefn 12513 12514@deftypefn {Built-in Function} _Decimal128 __builtin_infd128 (void) 12515Similar to @code{__builtin_inf}, except the return type is @code{_Decimal128}. 12516@end deftypefn 12517 12518@deftypefn {Built-in Function} float __builtin_inff (void) 12519Similar to @code{__builtin_inf}, except the return type is @code{float}. 12520This function is suitable for implementing the ISO C99 macro @code{INFINITY}. 12521@end deftypefn 12522 12523@deftypefn {Built-in Function} {long double} __builtin_infl (void) 12524Similar to @code{__builtin_inf}, except the return 12525type is @code{long double}. 12526@end deftypefn 12527 12528@deftypefn {Built-in Function} _Float@var{n} __builtin_inff@var{n} (void) 12529Similar to @code{__builtin_inf}, except the return 12530type is @code{_Float@var{n}}. 12531@end deftypefn 12532 12533@deftypefn {Built-in Function} _Float@var{n} __builtin_inff@var{n}x (void) 12534Similar to @code{__builtin_inf}, except the return 12535type is @code{_Float@var{n}x}. 12536@end deftypefn 12537 12538@deftypefn {Built-in Function} int __builtin_isinf_sign (...) 12539Similar to @code{isinf}, except the return value is -1 for 12540an argument of @code{-Inf} and 1 for an argument of @code{+Inf}. 12541Note while the parameter list is an 12542ellipsis, this function only accepts exactly one floating-point 12543argument. GCC treats this parameter as type-generic, which means it 12544does not do default promotion from float to double. 12545@end deftypefn 12546 12547@deftypefn {Built-in Function} double __builtin_nan (const char *str) 12548This is an implementation of the ISO C99 function @code{nan}. 12549 12550Since ISO C99 defines this function in terms of @code{strtod}, which we 12551do not implement, a description of the parsing is in order. The string 12552is parsed as by @code{strtol}; that is, the base is recognized by 12553leading @samp{0} or @samp{0x} prefixes. The number parsed is placed 12554in the significand such that the least significant bit of the number 12555is at the least significant bit of the significand. The number is 12556truncated to fit the significand field provided. The significand is 12557forced to be a quiet NaN@. 12558 12559This function, if given a string literal all of which would have been 12560consumed by @code{strtol}, is evaluated early enough that it is considered a 12561compile-time constant. 12562@end deftypefn 12563 12564@deftypefn {Built-in Function} _Decimal32 __builtin_nand32 (const char *str) 12565Similar to @code{__builtin_nan}, except the return type is @code{_Decimal32}. 12566@end deftypefn 12567 12568@deftypefn {Built-in Function} _Decimal64 __builtin_nand64 (const char *str) 12569Similar to @code{__builtin_nan}, except the return type is @code{_Decimal64}. 12570@end deftypefn 12571 12572@deftypefn {Built-in Function} _Decimal128 __builtin_nand128 (const char *str) 12573Similar to @code{__builtin_nan}, except the return type is @code{_Decimal128}. 12574@end deftypefn 12575 12576@deftypefn {Built-in Function} float __builtin_nanf (const char *str) 12577Similar to @code{__builtin_nan}, except the return type is @code{float}. 12578@end deftypefn 12579 12580@deftypefn {Built-in Function} {long double} __builtin_nanl (const char *str) 12581Similar to @code{__builtin_nan}, except the return type is @code{long double}. 12582@end deftypefn 12583 12584@deftypefn {Built-in Function} _Float@var{n} __builtin_nanf@var{n} (const char *str) 12585Similar to @code{__builtin_nan}, except the return type is 12586@code{_Float@var{n}}. 12587@end deftypefn 12588 12589@deftypefn {Built-in Function} _Float@var{n}x __builtin_nanf@var{n}x (const char *str) 12590Similar to @code{__builtin_nan}, except the return type is 12591@code{_Float@var{n}x}. 12592@end deftypefn 12593 12594@deftypefn {Built-in Function} double __builtin_nans (const char *str) 12595Similar to @code{__builtin_nan}, except the significand is forced 12596to be a signaling NaN@. The @code{nans} function is proposed by 12597@uref{http://www.open-std.org/jtc1/sc22/wg14/www/docs/n965.htm,,WG14 N965}. 12598@end deftypefn 12599 12600@deftypefn {Built-in Function} float __builtin_nansf (const char *str) 12601Similar to @code{__builtin_nans}, except the return type is @code{float}. 12602@end deftypefn 12603 12604@deftypefn {Built-in Function} {long double} __builtin_nansl (const char *str) 12605Similar to @code{__builtin_nans}, except the return type is @code{long double}. 12606@end deftypefn 12607 12608@deftypefn {Built-in Function} _Float@var{n} __builtin_nansf@var{n} (const char *str) 12609Similar to @code{__builtin_nans}, except the return type is 12610@code{_Float@var{n}}. 12611@end deftypefn 12612 12613@deftypefn {Built-in Function} _Float@var{n}x __builtin_nansf@var{n}x (const char *str) 12614Similar to @code{__builtin_nans}, except the return type is 12615@code{_Float@var{n}x}. 12616@end deftypefn 12617 12618@deftypefn {Built-in Function} int __builtin_ffs (int x) 12619Returns one plus the index of the least significant 1-bit of @var{x}, or 12620if @var{x} is zero, returns zero. 12621@end deftypefn 12622 12623@deftypefn {Built-in Function} int __builtin_clz (unsigned int x) 12624Returns the number of leading 0-bits in @var{x}, starting at the most 12625significant bit position. If @var{x} is 0, the result is undefined. 12626@end deftypefn 12627 12628@deftypefn {Built-in Function} int __builtin_ctz (unsigned int x) 12629Returns the number of trailing 0-bits in @var{x}, starting at the least 12630significant bit position. If @var{x} is 0, the result is undefined. 12631@end deftypefn 12632 12633@deftypefn {Built-in Function} int __builtin_clrsb (int x) 12634Returns the number of leading redundant sign bits in @var{x}, i.e.@: the 12635number of bits following the most significant bit that are identical 12636to it. There are no special cases for 0 or other values. 12637@end deftypefn 12638 12639@deftypefn {Built-in Function} int __builtin_popcount (unsigned int x) 12640Returns the number of 1-bits in @var{x}. 12641@end deftypefn 12642 12643@deftypefn {Built-in Function} int __builtin_parity (unsigned int x) 12644Returns the parity of @var{x}, i.e.@: the number of 1-bits in @var{x} 12645modulo 2. 12646@end deftypefn 12647 12648@deftypefn {Built-in Function} int __builtin_ffsl (long) 12649Similar to @code{__builtin_ffs}, except the argument type is 12650@code{long}. 12651@end deftypefn 12652 12653@deftypefn {Built-in Function} int __builtin_clzl (unsigned long) 12654Similar to @code{__builtin_clz}, except the argument type is 12655@code{unsigned long}. 12656@end deftypefn 12657 12658@deftypefn {Built-in Function} int __builtin_ctzl (unsigned long) 12659Similar to @code{__builtin_ctz}, except the argument type is 12660@code{unsigned long}. 12661@end deftypefn 12662 12663@deftypefn {Built-in Function} int __builtin_clrsbl (long) 12664Similar to @code{__builtin_clrsb}, except the argument type is 12665@code{long}. 12666@end deftypefn 12667 12668@deftypefn {Built-in Function} int __builtin_popcountl (unsigned long) 12669Similar to @code{__builtin_popcount}, except the argument type is 12670@code{unsigned long}. 12671@end deftypefn 12672 12673@deftypefn {Built-in Function} int __builtin_parityl (unsigned long) 12674Similar to @code{__builtin_parity}, except the argument type is 12675@code{unsigned long}. 12676@end deftypefn 12677 12678@deftypefn {Built-in Function} int __builtin_ffsll (long long) 12679Similar to @code{__builtin_ffs}, except the argument type is 12680@code{long long}. 12681@end deftypefn 12682 12683@deftypefn {Built-in Function} int __builtin_clzll (unsigned long long) 12684Similar to @code{__builtin_clz}, except the argument type is 12685@code{unsigned long long}. 12686@end deftypefn 12687 12688@deftypefn {Built-in Function} int __builtin_ctzll (unsigned long long) 12689Similar to @code{__builtin_ctz}, except the argument type is 12690@code{unsigned long long}. 12691@end deftypefn 12692 12693@deftypefn {Built-in Function} int __builtin_clrsbll (long long) 12694Similar to @code{__builtin_clrsb}, except the argument type is 12695@code{long long}. 12696@end deftypefn 12697 12698@deftypefn {Built-in Function} int __builtin_popcountll (unsigned long long) 12699Similar to @code{__builtin_popcount}, except the argument type is 12700@code{unsigned long long}. 12701@end deftypefn 12702 12703@deftypefn {Built-in Function} int __builtin_parityll (unsigned long long) 12704Similar to @code{__builtin_parity}, except the argument type is 12705@code{unsigned long long}. 12706@end deftypefn 12707 12708@deftypefn {Built-in Function} double __builtin_powi (double, int) 12709Returns the first argument raised to the power of the second. Unlike the 12710@code{pow} function no guarantees about precision and rounding are made. 12711@end deftypefn 12712 12713@deftypefn {Built-in Function} float __builtin_powif (float, int) 12714Similar to @code{__builtin_powi}, except the argument and return types 12715are @code{float}. 12716@end deftypefn 12717 12718@deftypefn {Built-in Function} {long double} __builtin_powil (long double, int) 12719Similar to @code{__builtin_powi}, except the argument and return types 12720are @code{long double}. 12721@end deftypefn 12722 12723@deftypefn {Built-in Function} uint16_t __builtin_bswap16 (uint16_t x) 12724Returns @var{x} with the order of the bytes reversed; for example, 12725@code{0xaabb} becomes @code{0xbbaa}. Byte here always means 12726exactly 8 bits. 12727@end deftypefn 12728 12729@deftypefn {Built-in Function} uint32_t __builtin_bswap32 (uint32_t x) 12730Similar to @code{__builtin_bswap16}, except the argument and return types 12731are 32 bit. 12732@end deftypefn 12733 12734@deftypefn {Built-in Function} uint64_t __builtin_bswap64 (uint64_t x) 12735Similar to @code{__builtin_bswap32}, except the argument and return types 12736are 64 bit. 12737@end deftypefn 12738 12739@deftypefn {Built-in Function} Pmode __builtin_extend_pointer (void * x) 12740On targets where the user visible pointer size is smaller than the size 12741of an actual hardware address this function returns the extended user 12742pointer. Targets where this is true included ILP32 mode on x86_64 or 12743Aarch64. This function is mainly useful when writing inline assembly 12744code. 12745@end deftypefn 12746 12747@node Target Builtins 12748@section Built-in Functions Specific to Particular Target Machines 12749 12750On some target machines, GCC supports many built-in functions specific 12751to those machines. Generally these generate calls to specific machine 12752instructions, but allow the compiler to schedule those calls. 12753 12754@menu 12755* AArch64 Built-in Functions:: 12756* Alpha Built-in Functions:: 12757* Altera Nios II Built-in Functions:: 12758* ARC Built-in Functions:: 12759* ARC SIMD Built-in Functions:: 12760* ARM iWMMXt Built-in Functions:: 12761* ARM C Language Extensions (ACLE):: 12762* ARM Floating Point Status and Control Intrinsics:: 12763* ARM ARMv8-M Security Extensions:: 12764* AVR Built-in Functions:: 12765* Blackfin Built-in Functions:: 12766* FR-V Built-in Functions:: 12767* MIPS DSP Built-in Functions:: 12768* MIPS Paired-Single Support:: 12769* MIPS Loongson Built-in Functions:: 12770* MIPS SIMD Architecture (MSA) Support:: 12771* Other MIPS Built-in Functions:: 12772* MSP430 Built-in Functions:: 12773* NDS32 Built-in Functions:: 12774* picoChip Built-in Functions:: 12775* PowerPC Built-in Functions:: 12776* PowerPC AltiVec/VSX Built-in Functions:: 12777* PowerPC Hardware Transactional Memory Built-in Functions:: 12778* PowerPC Atomic Memory Operation Functions:: 12779* RX Built-in Functions:: 12780* S/390 System z Built-in Functions:: 12781* SH Built-in Functions:: 12782* SPARC VIS Built-in Functions:: 12783* SPU Built-in Functions:: 12784* TI C6X Built-in Functions:: 12785* TILE-Gx Built-in Functions:: 12786* TILEPro Built-in Functions:: 12787* x86 Built-in Functions:: 12788* x86 transactional memory intrinsics:: 12789* x86 control-flow protection intrinsics:: 12790@end menu 12791 12792@node AArch64 Built-in Functions 12793@subsection AArch64 Built-in Functions 12794 12795These built-in functions are available for the AArch64 family of 12796processors. 12797@smallexample 12798unsigned int __builtin_aarch64_get_fpcr () 12799void __builtin_aarch64_set_fpcr (unsigned int) 12800unsigned int __builtin_aarch64_get_fpsr () 12801void __builtin_aarch64_set_fpsr (unsigned int) 12802@end smallexample 12803 12804@node Alpha Built-in Functions 12805@subsection Alpha Built-in Functions 12806 12807These built-in functions are available for the Alpha family of 12808processors, depending on the command-line switches used. 12809 12810The following built-in functions are always available. They 12811all generate the machine instruction that is part of the name. 12812 12813@smallexample 12814long __builtin_alpha_implver (void) 12815long __builtin_alpha_rpcc (void) 12816long __builtin_alpha_amask (long) 12817long __builtin_alpha_cmpbge (long, long) 12818long __builtin_alpha_extbl (long, long) 12819long __builtin_alpha_extwl (long, long) 12820long __builtin_alpha_extll (long, long) 12821long __builtin_alpha_extql (long, long) 12822long __builtin_alpha_extwh (long, long) 12823long __builtin_alpha_extlh (long, long) 12824long __builtin_alpha_extqh (long, long) 12825long __builtin_alpha_insbl (long, long) 12826long __builtin_alpha_inswl (long, long) 12827long __builtin_alpha_insll (long, long) 12828long __builtin_alpha_insql (long, long) 12829long __builtin_alpha_inswh (long, long) 12830long __builtin_alpha_inslh (long, long) 12831long __builtin_alpha_insqh (long, long) 12832long __builtin_alpha_mskbl (long, long) 12833long __builtin_alpha_mskwl (long, long) 12834long __builtin_alpha_mskll (long, long) 12835long __builtin_alpha_mskql (long, long) 12836long __builtin_alpha_mskwh (long, long) 12837long __builtin_alpha_msklh (long, long) 12838long __builtin_alpha_mskqh (long, long) 12839long __builtin_alpha_umulh (long, long) 12840long __builtin_alpha_zap (long, long) 12841long __builtin_alpha_zapnot (long, long) 12842@end smallexample 12843 12844The following built-in functions are always with @option{-mmax} 12845or @option{-mcpu=@var{cpu}} where @var{cpu} is @code{pca56} or 12846later. They all generate the machine instruction that is part 12847of the name. 12848 12849@smallexample 12850long __builtin_alpha_pklb (long) 12851long __builtin_alpha_pkwb (long) 12852long __builtin_alpha_unpkbl (long) 12853long __builtin_alpha_unpkbw (long) 12854long __builtin_alpha_minub8 (long, long) 12855long __builtin_alpha_minsb8 (long, long) 12856long __builtin_alpha_minuw4 (long, long) 12857long __builtin_alpha_minsw4 (long, long) 12858long __builtin_alpha_maxub8 (long, long) 12859long __builtin_alpha_maxsb8 (long, long) 12860long __builtin_alpha_maxuw4 (long, long) 12861long __builtin_alpha_maxsw4 (long, long) 12862long __builtin_alpha_perr (long, long) 12863@end smallexample 12864 12865The following built-in functions are always with @option{-mcix} 12866or @option{-mcpu=@var{cpu}} where @var{cpu} is @code{ev67} or 12867later. They all generate the machine instruction that is part 12868of the name. 12869 12870@smallexample 12871long __builtin_alpha_cttz (long) 12872long __builtin_alpha_ctlz (long) 12873long __builtin_alpha_ctpop (long) 12874@end smallexample 12875 12876The following built-in functions are available on systems that use the OSF/1 12877PALcode. Normally they invoke the @code{rduniq} and @code{wruniq} 12878PAL calls, but when invoked with @option{-mtls-kernel}, they invoke 12879@code{rdval} and @code{wrval}. 12880 12881@smallexample 12882void *__builtin_thread_pointer (void) 12883void __builtin_set_thread_pointer (void *) 12884@end smallexample 12885 12886@node Altera Nios II Built-in Functions 12887@subsection Altera Nios II Built-in Functions 12888 12889These built-in functions are available for the Altera Nios II 12890family of processors. 12891 12892The following built-in functions are always available. They 12893all generate the machine instruction that is part of the name. 12894 12895@example 12896int __builtin_ldbio (volatile const void *) 12897int __builtin_ldbuio (volatile const void *) 12898int __builtin_ldhio (volatile const void *) 12899int __builtin_ldhuio (volatile const void *) 12900int __builtin_ldwio (volatile const void *) 12901void __builtin_stbio (volatile void *, int) 12902void __builtin_sthio (volatile void *, int) 12903void __builtin_stwio (volatile void *, int) 12904void __builtin_sync (void) 12905int __builtin_rdctl (int) 12906int __builtin_rdprs (int, int) 12907void __builtin_wrctl (int, int) 12908void __builtin_flushd (volatile void *) 12909void __builtin_flushda (volatile void *) 12910int __builtin_wrpie (int); 12911void __builtin_eni (int); 12912int __builtin_ldex (volatile const void *) 12913int __builtin_stex (volatile void *, int) 12914int __builtin_ldsex (volatile const void *) 12915int __builtin_stsex (volatile void *, int) 12916@end example 12917 12918The following built-in functions are always available. They 12919all generate a Nios II Custom Instruction. The name of the 12920function represents the types that the function takes and 12921returns. The letter before the @code{n} is the return type 12922or void if absent. The @code{n} represents the first parameter 12923to all the custom instructions, the custom instruction number. 12924The two letters after the @code{n} represent the up to two 12925parameters to the function. 12926 12927The letters represent the following data types: 12928@table @code 12929@item <no letter> 12930@code{void} for return type and no parameter for parameter types. 12931 12932@item i 12933@code{int} for return type and parameter type 12934 12935@item f 12936@code{float} for return type and parameter type 12937 12938@item p 12939@code{void *} for return type and parameter type 12940 12941@end table 12942 12943And the function names are: 12944@example 12945void __builtin_custom_n (void) 12946void __builtin_custom_ni (int) 12947void __builtin_custom_nf (float) 12948void __builtin_custom_np (void *) 12949void __builtin_custom_nii (int, int) 12950void __builtin_custom_nif (int, float) 12951void __builtin_custom_nip (int, void *) 12952void __builtin_custom_nfi (float, int) 12953void __builtin_custom_nff (float, float) 12954void __builtin_custom_nfp (float, void *) 12955void __builtin_custom_npi (void *, int) 12956void __builtin_custom_npf (void *, float) 12957void __builtin_custom_npp (void *, void *) 12958int __builtin_custom_in (void) 12959int __builtin_custom_ini (int) 12960int __builtin_custom_inf (float) 12961int __builtin_custom_inp (void *) 12962int __builtin_custom_inii (int, int) 12963int __builtin_custom_inif (int, float) 12964int __builtin_custom_inip (int, void *) 12965int __builtin_custom_infi (float, int) 12966int __builtin_custom_inff (float, float) 12967int __builtin_custom_infp (float, void *) 12968int __builtin_custom_inpi (void *, int) 12969int __builtin_custom_inpf (void *, float) 12970int __builtin_custom_inpp (void *, void *) 12971float __builtin_custom_fn (void) 12972float __builtin_custom_fni (int) 12973float __builtin_custom_fnf (float) 12974float __builtin_custom_fnp (void *) 12975float __builtin_custom_fnii (int, int) 12976float __builtin_custom_fnif (int, float) 12977float __builtin_custom_fnip (int, void *) 12978float __builtin_custom_fnfi (float, int) 12979float __builtin_custom_fnff (float, float) 12980float __builtin_custom_fnfp (float, void *) 12981float __builtin_custom_fnpi (void *, int) 12982float __builtin_custom_fnpf (void *, float) 12983float __builtin_custom_fnpp (void *, void *) 12984void * __builtin_custom_pn (void) 12985void * __builtin_custom_pni (int) 12986void * __builtin_custom_pnf (float) 12987void * __builtin_custom_pnp (void *) 12988void * __builtin_custom_pnii (int, int) 12989void * __builtin_custom_pnif (int, float) 12990void * __builtin_custom_pnip (int, void *) 12991void * __builtin_custom_pnfi (float, int) 12992void * __builtin_custom_pnff (float, float) 12993void * __builtin_custom_pnfp (float, void *) 12994void * __builtin_custom_pnpi (void *, int) 12995void * __builtin_custom_pnpf (void *, float) 12996void * __builtin_custom_pnpp (void *, void *) 12997@end example 12998 12999@node ARC Built-in Functions 13000@subsection ARC Built-in Functions 13001 13002The following built-in functions are provided for ARC targets. The 13003built-ins generate the corresponding assembly instructions. In the 13004examples given below, the generated code often requires an operand or 13005result to be in a register. Where necessary further code will be 13006generated to ensure this is true, but for brevity this is not 13007described in each case. 13008 13009@emph{Note:} Using a built-in to generate an instruction not supported 13010by a target may cause problems. At present the compiler is not 13011guaranteed to detect such misuse, and as a result an internal compiler 13012error may be generated. 13013 13014@deftypefn {Built-in Function} int __builtin_arc_aligned (void *@var{val}, int @var{alignval}) 13015Return 1 if @var{val} is known to have the byte alignment given 13016by @var{alignval}, otherwise return 0. 13017Note that this is different from 13018@smallexample 13019__alignof__(*(char *)@var{val}) >= alignval 13020@end smallexample 13021because __alignof__ sees only the type of the dereference, whereas 13022__builtin_arc_align uses alignment information from the pointer 13023as well as from the pointed-to type. 13024The information available will depend on optimization level. 13025@end deftypefn 13026 13027@deftypefn {Built-in Function} void __builtin_arc_brk (void) 13028Generates 13029@example 13030brk 13031@end example 13032@end deftypefn 13033 13034@deftypefn {Built-in Function} {unsigned int} __builtin_arc_core_read (unsigned int @var{regno}) 13035The operand is the number of a register to be read. Generates: 13036@example 13037mov @var{dest}, r@var{regno} 13038@end example 13039where the value in @var{dest} will be the result returned from the 13040built-in. 13041@end deftypefn 13042 13043@deftypefn {Built-in Function} void __builtin_arc_core_write (unsigned int @var{regno}, unsigned int @var{val}) 13044The first operand is the number of a register to be written, the 13045second operand is a compile time constant to write into that 13046register. Generates: 13047@example 13048mov r@var{regno}, @var{val} 13049@end example 13050@end deftypefn 13051 13052@deftypefn {Built-in Function} int __builtin_arc_divaw (int @var{a}, int @var{b}) 13053Only available if either @option{-mcpu=ARC700} or @option{-meA} is set. 13054Generates: 13055@example 13056divaw @var{dest}, @var{a}, @var{b} 13057@end example 13058where the value in @var{dest} will be the result returned from the 13059built-in. 13060@end deftypefn 13061 13062@deftypefn {Built-in Function} void __builtin_arc_flag (unsigned int @var{a}) 13063Generates 13064@example 13065flag @var{a} 13066@end example 13067@end deftypefn 13068 13069@deftypefn {Built-in Function} {unsigned int} __builtin_arc_lr (unsigned int @var{auxr}) 13070The operand, @var{auxv}, is the address of an auxiliary register and 13071must be a compile time constant. Generates: 13072@example 13073lr @var{dest}, [@var{auxr}] 13074@end example 13075Where the value in @var{dest} will be the result returned from the 13076built-in. 13077@end deftypefn 13078 13079@deftypefn {Built-in Function} void __builtin_arc_mul64 (int @var{a}, int @var{b}) 13080Only available with @option{-mmul64}. Generates: 13081@example 13082mul64 @var{a}, @var{b} 13083@end example 13084@end deftypefn 13085 13086@deftypefn {Built-in Function} void __builtin_arc_mulu64 (unsigned int @var{a}, unsigned int @var{b}) 13087Only available with @option{-mmul64}. Generates: 13088@example 13089mulu64 @var{a}, @var{b} 13090@end example 13091@end deftypefn 13092 13093@deftypefn {Built-in Function} void __builtin_arc_nop (void) 13094Generates: 13095@example 13096nop 13097@end example 13098@end deftypefn 13099 13100@deftypefn {Built-in Function} int __builtin_arc_norm (int @var{src}) 13101Only valid if the @samp{norm} instruction is available through the 13102@option{-mnorm} option or by default with @option{-mcpu=ARC700}. 13103Generates: 13104@example 13105norm @var{dest}, @var{src} 13106@end example 13107Where the value in @var{dest} will be the result returned from the 13108built-in. 13109@end deftypefn 13110 13111@deftypefn {Built-in Function} {short int} __builtin_arc_normw (short int @var{src}) 13112Only valid if the @samp{normw} instruction is available through the 13113@option{-mnorm} option or by default with @option{-mcpu=ARC700}. 13114Generates: 13115@example 13116normw @var{dest}, @var{src} 13117@end example 13118Where the value in @var{dest} will be the result returned from the 13119built-in. 13120@end deftypefn 13121 13122@deftypefn {Built-in Function} void __builtin_arc_rtie (void) 13123Generates: 13124@example 13125rtie 13126@end example 13127@end deftypefn 13128 13129@deftypefn {Built-in Function} void __builtin_arc_sleep (int @var{a} 13130Generates: 13131@example 13132sleep @var{a} 13133@end example 13134@end deftypefn 13135 13136@deftypefn {Built-in Function} void __builtin_arc_sr (unsigned int @var{auxr}, unsigned int @var{val}) 13137The first argument, @var{auxv}, is the address of an auxiliary 13138register, the second argument, @var{val}, is a compile time constant 13139to be written to the register. Generates: 13140@example 13141sr @var{auxr}, [@var{val}] 13142@end example 13143@end deftypefn 13144 13145@deftypefn {Built-in Function} int __builtin_arc_swap (int @var{src}) 13146Only valid with @option{-mswap}. Generates: 13147@example 13148swap @var{dest}, @var{src} 13149@end example 13150Where the value in @var{dest} will be the result returned from the 13151built-in. 13152@end deftypefn 13153 13154@deftypefn {Built-in Function} void __builtin_arc_swi (void) 13155Generates: 13156@example 13157swi 13158@end example 13159@end deftypefn 13160 13161@deftypefn {Built-in Function} void __builtin_arc_sync (void) 13162Only available with @option{-mcpu=ARC700}. Generates: 13163@example 13164sync 13165@end example 13166@end deftypefn 13167 13168@deftypefn {Built-in Function} void __builtin_arc_trap_s (unsigned int @var{c}) 13169Only available with @option{-mcpu=ARC700}. Generates: 13170@example 13171trap_s @var{c} 13172@end example 13173@end deftypefn 13174 13175@deftypefn {Built-in Function} void __builtin_arc_unimp_s (void) 13176Only available with @option{-mcpu=ARC700}. Generates: 13177@example 13178unimp_s 13179@end example 13180@end deftypefn 13181 13182The instructions generated by the following builtins are not 13183considered as candidates for scheduling. They are not moved around by 13184the compiler during scheduling, and thus can be expected to appear 13185where they are put in the C code: 13186@example 13187__builtin_arc_brk() 13188__builtin_arc_core_read() 13189__builtin_arc_core_write() 13190__builtin_arc_flag() 13191__builtin_arc_lr() 13192__builtin_arc_sleep() 13193__builtin_arc_sr() 13194__builtin_arc_swi() 13195@end example 13196 13197@node ARC SIMD Built-in Functions 13198@subsection ARC SIMD Built-in Functions 13199 13200SIMD builtins provided by the compiler can be used to generate the 13201vector instructions. This section describes the available builtins 13202and their usage in programs. With the @option{-msimd} option, the 13203compiler provides 128-bit vector types, which can be specified using 13204the @code{vector_size} attribute. The header file @file{arc-simd.h} 13205can be included to use the following predefined types: 13206@example 13207typedef int __v4si __attribute__((vector_size(16))); 13208typedef short __v8hi __attribute__((vector_size(16))); 13209@end example 13210 13211These types can be used to define 128-bit variables. The built-in 13212functions listed in the following section can be used on these 13213variables to generate the vector operations. 13214 13215For all builtins, @code{__builtin_arc_@var{someinsn}}, the header file 13216@file{arc-simd.h} also provides equivalent macros called 13217@code{_@var{someinsn}} that can be used for programming ease and 13218improved readability. The following macros for DMA control are also 13219provided: 13220@example 13221#define _setup_dma_in_channel_reg _vdiwr 13222#define _setup_dma_out_channel_reg _vdowr 13223@end example 13224 13225The following is a complete list of all the SIMD built-ins provided 13226for ARC, grouped by calling signature. 13227 13228The following take two @code{__v8hi} arguments and return a 13229@code{__v8hi} result: 13230@example 13231__v8hi __builtin_arc_vaddaw (__v8hi, __v8hi) 13232__v8hi __builtin_arc_vaddw (__v8hi, __v8hi) 13233__v8hi __builtin_arc_vand (__v8hi, __v8hi) 13234__v8hi __builtin_arc_vandaw (__v8hi, __v8hi) 13235__v8hi __builtin_arc_vavb (__v8hi, __v8hi) 13236__v8hi __builtin_arc_vavrb (__v8hi, __v8hi) 13237__v8hi __builtin_arc_vbic (__v8hi, __v8hi) 13238__v8hi __builtin_arc_vbicaw (__v8hi, __v8hi) 13239__v8hi __builtin_arc_vdifaw (__v8hi, __v8hi) 13240__v8hi __builtin_arc_vdifw (__v8hi, __v8hi) 13241__v8hi __builtin_arc_veqw (__v8hi, __v8hi) 13242__v8hi __builtin_arc_vh264f (__v8hi, __v8hi) 13243__v8hi __builtin_arc_vh264ft (__v8hi, __v8hi) 13244__v8hi __builtin_arc_vh264fw (__v8hi, __v8hi) 13245__v8hi __builtin_arc_vlew (__v8hi, __v8hi) 13246__v8hi __builtin_arc_vltw (__v8hi, __v8hi) 13247__v8hi __builtin_arc_vmaxaw (__v8hi, __v8hi) 13248__v8hi __builtin_arc_vmaxw (__v8hi, __v8hi) 13249__v8hi __builtin_arc_vminaw (__v8hi, __v8hi) 13250__v8hi __builtin_arc_vminw (__v8hi, __v8hi) 13251__v8hi __builtin_arc_vmr1aw (__v8hi, __v8hi) 13252__v8hi __builtin_arc_vmr1w (__v8hi, __v8hi) 13253__v8hi __builtin_arc_vmr2aw (__v8hi, __v8hi) 13254__v8hi __builtin_arc_vmr2w (__v8hi, __v8hi) 13255__v8hi __builtin_arc_vmr3aw (__v8hi, __v8hi) 13256__v8hi __builtin_arc_vmr3w (__v8hi, __v8hi) 13257__v8hi __builtin_arc_vmr4aw (__v8hi, __v8hi) 13258__v8hi __builtin_arc_vmr4w (__v8hi, __v8hi) 13259__v8hi __builtin_arc_vmr5aw (__v8hi, __v8hi) 13260__v8hi __builtin_arc_vmr5w (__v8hi, __v8hi) 13261__v8hi __builtin_arc_vmr6aw (__v8hi, __v8hi) 13262__v8hi __builtin_arc_vmr6w (__v8hi, __v8hi) 13263__v8hi __builtin_arc_vmr7aw (__v8hi, __v8hi) 13264__v8hi __builtin_arc_vmr7w (__v8hi, __v8hi) 13265__v8hi __builtin_arc_vmrb (__v8hi, __v8hi) 13266__v8hi __builtin_arc_vmulaw (__v8hi, __v8hi) 13267__v8hi __builtin_arc_vmulfaw (__v8hi, __v8hi) 13268__v8hi __builtin_arc_vmulfw (__v8hi, __v8hi) 13269__v8hi __builtin_arc_vmulw (__v8hi, __v8hi) 13270__v8hi __builtin_arc_vnew (__v8hi, __v8hi) 13271__v8hi __builtin_arc_vor (__v8hi, __v8hi) 13272__v8hi __builtin_arc_vsubaw (__v8hi, __v8hi) 13273__v8hi __builtin_arc_vsubw (__v8hi, __v8hi) 13274__v8hi __builtin_arc_vsummw (__v8hi, __v8hi) 13275__v8hi __builtin_arc_vvc1f (__v8hi, __v8hi) 13276__v8hi __builtin_arc_vvc1ft (__v8hi, __v8hi) 13277__v8hi __builtin_arc_vxor (__v8hi, __v8hi) 13278__v8hi __builtin_arc_vxoraw (__v8hi, __v8hi) 13279@end example 13280 13281The following take one @code{__v8hi} and one @code{int} argument and return a 13282@code{__v8hi} result: 13283 13284@example 13285__v8hi __builtin_arc_vbaddw (__v8hi, int) 13286__v8hi __builtin_arc_vbmaxw (__v8hi, int) 13287__v8hi __builtin_arc_vbminw (__v8hi, int) 13288__v8hi __builtin_arc_vbmulaw (__v8hi, int) 13289__v8hi __builtin_arc_vbmulfw (__v8hi, int) 13290__v8hi __builtin_arc_vbmulw (__v8hi, int) 13291__v8hi __builtin_arc_vbrsubw (__v8hi, int) 13292__v8hi __builtin_arc_vbsubw (__v8hi, int) 13293@end example 13294 13295The following take one @code{__v8hi} argument and one @code{int} argument which 13296must be a 3-bit compile time constant indicating a register number 13297I0-I7. They return a @code{__v8hi} result. 13298@example 13299__v8hi __builtin_arc_vasrw (__v8hi, const int) 13300__v8hi __builtin_arc_vsr8 (__v8hi, const int) 13301__v8hi __builtin_arc_vsr8aw (__v8hi, const int) 13302@end example 13303 13304The following take one @code{__v8hi} argument and one @code{int} 13305argument which must be a 6-bit compile time constant. They return a 13306@code{__v8hi} result. 13307@example 13308__v8hi __builtin_arc_vasrpwbi (__v8hi, const int) 13309__v8hi __builtin_arc_vasrrpwbi (__v8hi, const int) 13310__v8hi __builtin_arc_vasrrwi (__v8hi, const int) 13311__v8hi __builtin_arc_vasrsrwi (__v8hi, const int) 13312__v8hi __builtin_arc_vasrwi (__v8hi, const int) 13313__v8hi __builtin_arc_vsr8awi (__v8hi, const int) 13314__v8hi __builtin_arc_vsr8i (__v8hi, const int) 13315@end example 13316 13317The following take one @code{__v8hi} argument and one @code{int} argument which 13318must be a 8-bit compile time constant. They return a @code{__v8hi} 13319result. 13320@example 13321__v8hi __builtin_arc_vd6tapf (__v8hi, const int) 13322__v8hi __builtin_arc_vmvaw (__v8hi, const int) 13323__v8hi __builtin_arc_vmvw (__v8hi, const int) 13324__v8hi __builtin_arc_vmvzw (__v8hi, const int) 13325@end example 13326 13327The following take two @code{int} arguments, the second of which which 13328must be a 8-bit compile time constant. They return a @code{__v8hi} 13329result: 13330@example 13331__v8hi __builtin_arc_vmovaw (int, const int) 13332__v8hi __builtin_arc_vmovw (int, const int) 13333__v8hi __builtin_arc_vmovzw (int, const int) 13334@end example 13335 13336The following take a single @code{__v8hi} argument and return a 13337@code{__v8hi} result: 13338@example 13339__v8hi __builtin_arc_vabsaw (__v8hi) 13340__v8hi __builtin_arc_vabsw (__v8hi) 13341__v8hi __builtin_arc_vaddsuw (__v8hi) 13342__v8hi __builtin_arc_vexch1 (__v8hi) 13343__v8hi __builtin_arc_vexch2 (__v8hi) 13344__v8hi __builtin_arc_vexch4 (__v8hi) 13345__v8hi __builtin_arc_vsignw (__v8hi) 13346__v8hi __builtin_arc_vupbaw (__v8hi) 13347__v8hi __builtin_arc_vupbw (__v8hi) 13348__v8hi __builtin_arc_vupsbaw (__v8hi) 13349__v8hi __builtin_arc_vupsbw (__v8hi) 13350@end example 13351 13352The following take two @code{int} arguments and return no result: 13353@example 13354void __builtin_arc_vdirun (int, int) 13355void __builtin_arc_vdorun (int, int) 13356@end example 13357 13358The following take two @code{int} arguments and return no result. The 13359first argument must a 3-bit compile time constant indicating one of 13360the DR0-DR7 DMA setup channels: 13361@example 13362void __builtin_arc_vdiwr (const int, int) 13363void __builtin_arc_vdowr (const int, int) 13364@end example 13365 13366The following take an @code{int} argument and return no result: 13367@example 13368void __builtin_arc_vendrec (int) 13369void __builtin_arc_vrec (int) 13370void __builtin_arc_vrecrun (int) 13371void __builtin_arc_vrun (int) 13372@end example 13373 13374The following take a @code{__v8hi} argument and two @code{int} 13375arguments and return a @code{__v8hi} result. The second argument must 13376be a 3-bit compile time constants, indicating one the registers I0-I7, 13377and the third argument must be an 8-bit compile time constant. 13378 13379@emph{Note:} Although the equivalent hardware instructions do not take 13380an SIMD register as an operand, these builtins overwrite the relevant 13381bits of the @code{__v8hi} register provided as the first argument with 13382the value loaded from the @code{[Ib, u8]} location in the SDM. 13383 13384@example 13385__v8hi __builtin_arc_vld32 (__v8hi, const int, const int) 13386__v8hi __builtin_arc_vld32wh (__v8hi, const int, const int) 13387__v8hi __builtin_arc_vld32wl (__v8hi, const int, const int) 13388__v8hi __builtin_arc_vld64 (__v8hi, const int, const int) 13389@end example 13390 13391The following take two @code{int} arguments and return a @code{__v8hi} 13392result. The first argument must be a 3-bit compile time constants, 13393indicating one the registers I0-I7, and the second argument must be an 133948-bit compile time constant. 13395 13396@example 13397__v8hi __builtin_arc_vld128 (const int, const int) 13398__v8hi __builtin_arc_vld64w (const int, const int) 13399@end example 13400 13401The following take a @code{__v8hi} argument and two @code{int} 13402arguments and return no result. The second argument must be a 3-bit 13403compile time constants, indicating one the registers I0-I7, and the 13404third argument must be an 8-bit compile time constant. 13405 13406@example 13407void __builtin_arc_vst128 (__v8hi, const int, const int) 13408void __builtin_arc_vst64 (__v8hi, const int, const int) 13409@end example 13410 13411The following take a @code{__v8hi} argument and three @code{int} 13412arguments and return no result. The second argument must be a 3-bit 13413compile-time constant, identifying the 16-bit sub-register to be 13414stored, the third argument must be a 3-bit compile time constants, 13415indicating one the registers I0-I7, and the fourth argument must be an 134168-bit compile time constant. 13417 13418@example 13419void __builtin_arc_vst16_n (__v8hi, const int, const int, const int) 13420void __builtin_arc_vst32_n (__v8hi, const int, const int, const int) 13421@end example 13422 13423@node ARM iWMMXt Built-in Functions 13424@subsection ARM iWMMXt Built-in Functions 13425 13426These built-in functions are available for the ARM family of 13427processors when the @option{-mcpu=iwmmxt} switch is used: 13428 13429@smallexample 13430typedef int v2si __attribute__ ((vector_size (8))); 13431typedef short v4hi __attribute__ ((vector_size (8))); 13432typedef char v8qi __attribute__ ((vector_size (8))); 13433 13434int __builtin_arm_getwcgr0 (void) 13435void __builtin_arm_setwcgr0 (int) 13436int __builtin_arm_getwcgr1 (void) 13437void __builtin_arm_setwcgr1 (int) 13438int __builtin_arm_getwcgr2 (void) 13439void __builtin_arm_setwcgr2 (int) 13440int __builtin_arm_getwcgr3 (void) 13441void __builtin_arm_setwcgr3 (int) 13442int __builtin_arm_textrmsb (v8qi, int) 13443int __builtin_arm_textrmsh (v4hi, int) 13444int __builtin_arm_textrmsw (v2si, int) 13445int __builtin_arm_textrmub (v8qi, int) 13446int __builtin_arm_textrmuh (v4hi, int) 13447int __builtin_arm_textrmuw (v2si, int) 13448v8qi __builtin_arm_tinsrb (v8qi, int, int) 13449v4hi __builtin_arm_tinsrh (v4hi, int, int) 13450v2si __builtin_arm_tinsrw (v2si, int, int) 13451long long __builtin_arm_tmia (long long, int, int) 13452long long __builtin_arm_tmiabb (long long, int, int) 13453long long __builtin_arm_tmiabt (long long, int, int) 13454long long __builtin_arm_tmiaph (long long, int, int) 13455long long __builtin_arm_tmiatb (long long, int, int) 13456long long __builtin_arm_tmiatt (long long, int, int) 13457int __builtin_arm_tmovmskb (v8qi) 13458int __builtin_arm_tmovmskh (v4hi) 13459int __builtin_arm_tmovmskw (v2si) 13460long long __builtin_arm_waccb (v8qi) 13461long long __builtin_arm_wacch (v4hi) 13462long long __builtin_arm_waccw (v2si) 13463v8qi __builtin_arm_waddb (v8qi, v8qi) 13464v8qi __builtin_arm_waddbss (v8qi, v8qi) 13465v8qi __builtin_arm_waddbus (v8qi, v8qi) 13466v4hi __builtin_arm_waddh (v4hi, v4hi) 13467v4hi __builtin_arm_waddhss (v4hi, v4hi) 13468v4hi __builtin_arm_waddhus (v4hi, v4hi) 13469v2si __builtin_arm_waddw (v2si, v2si) 13470v2si __builtin_arm_waddwss (v2si, v2si) 13471v2si __builtin_arm_waddwus (v2si, v2si) 13472v8qi __builtin_arm_walign (v8qi, v8qi, int) 13473long long __builtin_arm_wand(long long, long long) 13474long long __builtin_arm_wandn (long long, long long) 13475v8qi __builtin_arm_wavg2b (v8qi, v8qi) 13476v8qi __builtin_arm_wavg2br (v8qi, v8qi) 13477v4hi __builtin_arm_wavg2h (v4hi, v4hi) 13478v4hi __builtin_arm_wavg2hr (v4hi, v4hi) 13479v8qi __builtin_arm_wcmpeqb (v8qi, v8qi) 13480v4hi __builtin_arm_wcmpeqh (v4hi, v4hi) 13481v2si __builtin_arm_wcmpeqw (v2si, v2si) 13482v8qi __builtin_arm_wcmpgtsb (v8qi, v8qi) 13483v4hi __builtin_arm_wcmpgtsh (v4hi, v4hi) 13484v2si __builtin_arm_wcmpgtsw (v2si, v2si) 13485v8qi __builtin_arm_wcmpgtub (v8qi, v8qi) 13486v4hi __builtin_arm_wcmpgtuh (v4hi, v4hi) 13487v2si __builtin_arm_wcmpgtuw (v2si, v2si) 13488long long __builtin_arm_wmacs (long long, v4hi, v4hi) 13489long long __builtin_arm_wmacsz (v4hi, v4hi) 13490long long __builtin_arm_wmacu (long long, v4hi, v4hi) 13491long long __builtin_arm_wmacuz (v4hi, v4hi) 13492v4hi __builtin_arm_wmadds (v4hi, v4hi) 13493v4hi __builtin_arm_wmaddu (v4hi, v4hi) 13494v8qi __builtin_arm_wmaxsb (v8qi, v8qi) 13495v4hi __builtin_arm_wmaxsh (v4hi, v4hi) 13496v2si __builtin_arm_wmaxsw (v2si, v2si) 13497v8qi __builtin_arm_wmaxub (v8qi, v8qi) 13498v4hi __builtin_arm_wmaxuh (v4hi, v4hi) 13499v2si __builtin_arm_wmaxuw (v2si, v2si) 13500v8qi __builtin_arm_wminsb (v8qi, v8qi) 13501v4hi __builtin_arm_wminsh (v4hi, v4hi) 13502v2si __builtin_arm_wminsw (v2si, v2si) 13503v8qi __builtin_arm_wminub (v8qi, v8qi) 13504v4hi __builtin_arm_wminuh (v4hi, v4hi) 13505v2si __builtin_arm_wminuw (v2si, v2si) 13506v4hi __builtin_arm_wmulsm (v4hi, v4hi) 13507v4hi __builtin_arm_wmulul (v4hi, v4hi) 13508v4hi __builtin_arm_wmulum (v4hi, v4hi) 13509long long __builtin_arm_wor (long long, long long) 13510v2si __builtin_arm_wpackdss (long long, long long) 13511v2si __builtin_arm_wpackdus (long long, long long) 13512v8qi __builtin_arm_wpackhss (v4hi, v4hi) 13513v8qi __builtin_arm_wpackhus (v4hi, v4hi) 13514v4hi __builtin_arm_wpackwss (v2si, v2si) 13515v4hi __builtin_arm_wpackwus (v2si, v2si) 13516long long __builtin_arm_wrord (long long, long long) 13517long long __builtin_arm_wrordi (long long, int) 13518v4hi __builtin_arm_wrorh (v4hi, long long) 13519v4hi __builtin_arm_wrorhi (v4hi, int) 13520v2si __builtin_arm_wrorw (v2si, long long) 13521v2si __builtin_arm_wrorwi (v2si, int) 13522v2si __builtin_arm_wsadb (v2si, v8qi, v8qi) 13523v2si __builtin_arm_wsadbz (v8qi, v8qi) 13524v2si __builtin_arm_wsadh (v2si, v4hi, v4hi) 13525v2si __builtin_arm_wsadhz (v4hi, v4hi) 13526v4hi __builtin_arm_wshufh (v4hi, int) 13527long long __builtin_arm_wslld (long long, long long) 13528long long __builtin_arm_wslldi (long long, int) 13529v4hi __builtin_arm_wsllh (v4hi, long long) 13530v4hi __builtin_arm_wsllhi (v4hi, int) 13531v2si __builtin_arm_wsllw (v2si, long long) 13532v2si __builtin_arm_wsllwi (v2si, int) 13533long long __builtin_arm_wsrad (long long, long long) 13534long long __builtin_arm_wsradi (long long, int) 13535v4hi __builtin_arm_wsrah (v4hi, long long) 13536v4hi __builtin_arm_wsrahi (v4hi, int) 13537v2si __builtin_arm_wsraw (v2si, long long) 13538v2si __builtin_arm_wsrawi (v2si, int) 13539long long __builtin_arm_wsrld (long long, long long) 13540long long __builtin_arm_wsrldi (long long, int) 13541v4hi __builtin_arm_wsrlh (v4hi, long long) 13542v4hi __builtin_arm_wsrlhi (v4hi, int) 13543v2si __builtin_arm_wsrlw (v2si, long long) 13544v2si __builtin_arm_wsrlwi (v2si, int) 13545v8qi __builtin_arm_wsubb (v8qi, v8qi) 13546v8qi __builtin_arm_wsubbss (v8qi, v8qi) 13547v8qi __builtin_arm_wsubbus (v8qi, v8qi) 13548v4hi __builtin_arm_wsubh (v4hi, v4hi) 13549v4hi __builtin_arm_wsubhss (v4hi, v4hi) 13550v4hi __builtin_arm_wsubhus (v4hi, v4hi) 13551v2si __builtin_arm_wsubw (v2si, v2si) 13552v2si __builtin_arm_wsubwss (v2si, v2si) 13553v2si __builtin_arm_wsubwus (v2si, v2si) 13554v4hi __builtin_arm_wunpckehsb (v8qi) 13555v2si __builtin_arm_wunpckehsh (v4hi) 13556long long __builtin_arm_wunpckehsw (v2si) 13557v4hi __builtin_arm_wunpckehub (v8qi) 13558v2si __builtin_arm_wunpckehuh (v4hi) 13559long long __builtin_arm_wunpckehuw (v2si) 13560v4hi __builtin_arm_wunpckelsb (v8qi) 13561v2si __builtin_arm_wunpckelsh (v4hi) 13562long long __builtin_arm_wunpckelsw (v2si) 13563v4hi __builtin_arm_wunpckelub (v8qi) 13564v2si __builtin_arm_wunpckeluh (v4hi) 13565long long __builtin_arm_wunpckeluw (v2si) 13566v8qi __builtin_arm_wunpckihb (v8qi, v8qi) 13567v4hi __builtin_arm_wunpckihh (v4hi, v4hi) 13568v2si __builtin_arm_wunpckihw (v2si, v2si) 13569v8qi __builtin_arm_wunpckilb (v8qi, v8qi) 13570v4hi __builtin_arm_wunpckilh (v4hi, v4hi) 13571v2si __builtin_arm_wunpckilw (v2si, v2si) 13572long long __builtin_arm_wxor (long long, long long) 13573long long __builtin_arm_wzero () 13574@end smallexample 13575 13576 13577@node ARM C Language Extensions (ACLE) 13578@subsection ARM C Language Extensions (ACLE) 13579 13580GCC implements extensions for C as described in the ARM C Language 13581Extensions (ACLE) specification, which can be found at 13582@uref{http://infocenter.arm.com/help/topic/com.arm.doc.ihi0053c/IHI0053C_acle_2_0.pdf}. 13583 13584As a part of ACLE, GCC implements extensions for Advanced SIMD as described in 13585the ARM C Language Extensions Specification. The complete list of Advanced SIMD 13586intrinsics can be found at 13587@uref{http://infocenter.arm.com/help/topic/com.arm.doc.ihi0073a/IHI0073A_arm_neon_intrinsics_ref.pdf}. 13588The built-in intrinsics for the Advanced SIMD extension are available when 13589NEON is enabled. 13590 13591Currently, ARM and AArch64 back ends do not support ACLE 2.0 fully. Both 13592back ends support CRC32 intrinsics and the ARM back end supports the 13593Coprocessor intrinsics, all from @file{arm_acle.h}. The ARM back end's 16-bit 13594floating-point Advanced SIMD intrinsics currently comply to ACLE v1.1. 13595AArch64's back end does not have support for 16-bit floating point Advanced SIMD 13596intrinsics yet. 13597 13598See @ref{ARM Options} and @ref{AArch64 Options} for more information on the 13599availability of extensions. 13600 13601@node ARM Floating Point Status and Control Intrinsics 13602@subsection ARM Floating Point Status and Control Intrinsics 13603 13604These built-in functions are available for the ARM family of 13605processors with floating-point unit. 13606 13607@smallexample 13608unsigned int __builtin_arm_get_fpscr () 13609void __builtin_arm_set_fpscr (unsigned int) 13610@end smallexample 13611 13612@node ARM ARMv8-M Security Extensions 13613@subsection ARM ARMv8-M Security Extensions 13614 13615GCC implements the ARMv8-M Security Extensions as described in the ARMv8-M 13616Security Extensions: Requirements on Development Tools Engineering 13617Specification, which can be found at 13618@uref{http://infocenter.arm.com/help/topic/com.arm.doc.ecm0359818/ECM0359818_armv8m_security_extensions_reqs_on_dev_tools_1_0.pdf}. 13619 13620As part of the Security Extensions GCC implements two new function attributes: 13621@code{cmse_nonsecure_entry} and @code{cmse_nonsecure_call}. 13622 13623As part of the Security Extensions GCC implements the intrinsics below. FPTR 13624is used here to mean any function pointer type. 13625 13626@smallexample 13627cmse_address_info_t cmse_TT (void *) 13628cmse_address_info_t cmse_TT_fptr (FPTR) 13629cmse_address_info_t cmse_TTT (void *) 13630cmse_address_info_t cmse_TTT_fptr (FPTR) 13631cmse_address_info_t cmse_TTA (void *) 13632cmse_address_info_t cmse_TTA_fptr (FPTR) 13633cmse_address_info_t cmse_TTAT (void *) 13634cmse_address_info_t cmse_TTAT_fptr (FPTR) 13635void * cmse_check_address_range (void *, size_t, int) 13636typeof(p) cmse_nsfptr_create (FPTR p) 13637intptr_t cmse_is_nsfptr (FPTR) 13638int cmse_nonsecure_caller (void) 13639@end smallexample 13640 13641@node AVR Built-in Functions 13642@subsection AVR Built-in Functions 13643 13644For each built-in function for AVR, there is an equally named, 13645uppercase built-in macro defined. That way users can easily query if 13646or if not a specific built-in is implemented or not. For example, if 13647@code{__builtin_avr_nop} is available the macro 13648@code{__BUILTIN_AVR_NOP} is defined to @code{1} and undefined otherwise. 13649 13650@table @code 13651 13652@item void __builtin_avr_nop (void) 13653@itemx void __builtin_avr_sei (void) 13654@itemx void __builtin_avr_cli (void) 13655@itemx void __builtin_avr_sleep (void) 13656@itemx void __builtin_avr_wdr (void) 13657@itemx unsigned char __builtin_avr_swap (unsigned char) 13658@itemx unsigned int __builtin_avr_fmul (unsigned char, unsigned char) 13659@itemx int __builtin_avr_fmuls (char, char) 13660@itemx int __builtin_avr_fmulsu (char, unsigned char) 13661These built-in functions map to the respective machine 13662instruction, i.e.@: @code{nop}, @code{sei}, @code{cli}, @code{sleep}, 13663@code{wdr}, @code{swap}, @code{fmul}, @code{fmuls} 13664resp. @code{fmulsu}. The three @code{fmul*} built-ins are implemented 13665as library call if no hardware multiplier is available. 13666 13667@item void __builtin_avr_delay_cycles (unsigned long ticks) 13668Delay execution for @var{ticks} cycles. Note that this 13669built-in does not take into account the effect of interrupts that 13670might increase delay time. @var{ticks} must be a compile-time 13671integer constant; delays with a variable number of cycles are not supported. 13672 13673@item char __builtin_avr_flash_segment (const __memx void*) 13674This built-in takes a byte address to the 24-bit 13675@ref{AVR Named Address Spaces,address space} @code{__memx} and returns 13676the number of the flash segment (the 64 KiB chunk) where the address 13677points to. Counting starts at @code{0}. 13678If the address does not point to flash memory, return @code{-1}. 13679 13680@item uint8_t __builtin_avr_insert_bits (uint32_t map, uint8_t bits, uint8_t val) 13681Insert bits from @var{bits} into @var{val} and return the resulting 13682value. The nibbles of @var{map} determine how the insertion is 13683performed: Let @var{X} be the @var{n}-th nibble of @var{map} 13684@enumerate 13685@item If @var{X} is @code{0xf}, 13686then the @var{n}-th bit of @var{val} is returned unaltered. 13687 13688@item If X is in the range 0@dots{}7, 13689then the @var{n}-th result bit is set to the @var{X}-th bit of @var{bits} 13690 13691@item If X is in the range 8@dots{}@code{0xe}, 13692then the @var{n}-th result bit is undefined. 13693@end enumerate 13694 13695@noindent 13696One typical use case for this built-in is adjusting input and 13697output values to non-contiguous port layouts. Some examples: 13698 13699@smallexample 13700// same as val, bits is unused 13701__builtin_avr_insert_bits (0xffffffff, bits, val) 13702@end smallexample 13703 13704@smallexample 13705// same as bits, val is unused 13706__builtin_avr_insert_bits (0x76543210, bits, val) 13707@end smallexample 13708 13709@smallexample 13710// same as rotating bits by 4 13711__builtin_avr_insert_bits (0x32107654, bits, 0) 13712@end smallexample 13713 13714@smallexample 13715// high nibble of result is the high nibble of val 13716// low nibble of result is the low nibble of bits 13717__builtin_avr_insert_bits (0xffff3210, bits, val) 13718@end smallexample 13719 13720@smallexample 13721// reverse the bit order of bits 13722__builtin_avr_insert_bits (0x01234567, bits, 0) 13723@end smallexample 13724 13725@item void __builtin_avr_nops (unsigned count) 13726Insert @var{count} @code{NOP} instructions. 13727The number of instructions must be a compile-time integer constant. 13728 13729@end table 13730 13731@noindent 13732There are many more AVR-specific built-in functions that are used to 13733implement the ISO/IEC TR 18037 ``Embedded C'' fixed-point functions of 13734section 7.18a.6. You don't need to use these built-ins directly. 13735Instead, use the declarations as supplied by the @code{stdfix.h} header 13736with GNU-C99: 13737 13738@smallexample 13739#include <stdfix.h> 13740 13741// Re-interpret the bit representation of unsigned 16-bit 13742// integer @var{uval} as Q-format 0.16 value. 13743unsigned fract get_bits (uint_ur_t uval) 13744@{ 13745 return urbits (uval); 13746@} 13747@end smallexample 13748 13749@node Blackfin Built-in Functions 13750@subsection Blackfin Built-in Functions 13751 13752Currently, there are two Blackfin-specific built-in functions. These are 13753used for generating @code{CSYNC} and @code{SSYNC} machine insns without 13754using inline assembly; by using these built-in functions the compiler can 13755automatically add workarounds for hardware errata involving these 13756instructions. These functions are named as follows: 13757 13758@smallexample 13759void __builtin_bfin_csync (void) 13760void __builtin_bfin_ssync (void) 13761@end smallexample 13762 13763@node FR-V Built-in Functions 13764@subsection FR-V Built-in Functions 13765 13766GCC provides many FR-V-specific built-in functions. In general, 13767these functions are intended to be compatible with those described 13768by @cite{FR-V Family, Softune C/C++ Compiler Manual (V6), Fujitsu 13769Semiconductor}. The two exceptions are @code{__MDUNPACKH} and 13770@code{__MBTOHE}, the GCC forms of which pass 128-bit values by 13771pointer rather than by value. 13772 13773Most of the functions are named after specific FR-V instructions. 13774Such functions are said to be ``directly mapped'' and are summarized 13775here in tabular form. 13776 13777@menu 13778* Argument Types:: 13779* Directly-mapped Integer Functions:: 13780* Directly-mapped Media Functions:: 13781* Raw read/write Functions:: 13782* Other Built-in Functions:: 13783@end menu 13784 13785@node Argument Types 13786@subsubsection Argument Types 13787 13788The arguments to the built-in functions can be divided into three groups: 13789register numbers, compile-time constants and run-time values. In order 13790to make this classification clear at a glance, the arguments and return 13791values are given the following pseudo types: 13792 13793@multitable @columnfractions .20 .30 .15 .35 13794@item Pseudo type @tab Real C type @tab Constant? @tab Description 13795@item @code{uh} @tab @code{unsigned short} @tab No @tab an unsigned halfword 13796@item @code{uw1} @tab @code{unsigned int} @tab No @tab an unsigned word 13797@item @code{sw1} @tab @code{int} @tab No @tab a signed word 13798@item @code{uw2} @tab @code{unsigned long long} @tab No 13799@tab an unsigned doubleword 13800@item @code{sw2} @tab @code{long long} @tab No @tab a signed doubleword 13801@item @code{const} @tab @code{int} @tab Yes @tab an integer constant 13802@item @code{acc} @tab @code{int} @tab Yes @tab an ACC register number 13803@item @code{iacc} @tab @code{int} @tab Yes @tab an IACC register number 13804@end multitable 13805 13806These pseudo types are not defined by GCC, they are simply a notational 13807convenience used in this manual. 13808 13809Arguments of type @code{uh}, @code{uw1}, @code{sw1}, @code{uw2} 13810and @code{sw2} are evaluated at run time. They correspond to 13811register operands in the underlying FR-V instructions. 13812 13813@code{const} arguments represent immediate operands in the underlying 13814FR-V instructions. They must be compile-time constants. 13815 13816@code{acc} arguments are evaluated at compile time and specify the number 13817of an accumulator register. For example, an @code{acc} argument of 2 13818selects the ACC2 register. 13819 13820@code{iacc} arguments are similar to @code{acc} arguments but specify the 13821number of an IACC register. See @pxref{Other Built-in Functions} 13822for more details. 13823 13824@node Directly-mapped Integer Functions 13825@subsubsection Directly-Mapped Integer Functions 13826 13827The functions listed below map directly to FR-V I-type instructions. 13828 13829@multitable @columnfractions .45 .32 .23 13830@item Function prototype @tab Example usage @tab Assembly output 13831@item @code{sw1 __ADDSS (sw1, sw1)} 13832@tab @code{@var{c} = __ADDSS (@var{a}, @var{b})} 13833@tab @code{ADDSS @var{a},@var{b},@var{c}} 13834@item @code{sw1 __SCAN (sw1, sw1)} 13835@tab @code{@var{c} = __SCAN (@var{a}, @var{b})} 13836@tab @code{SCAN @var{a},@var{b},@var{c}} 13837@item @code{sw1 __SCUTSS (sw1)} 13838@tab @code{@var{b} = __SCUTSS (@var{a})} 13839@tab @code{SCUTSS @var{a},@var{b}} 13840@item @code{sw1 __SLASS (sw1, sw1)} 13841@tab @code{@var{c} = __SLASS (@var{a}, @var{b})} 13842@tab @code{SLASS @var{a},@var{b},@var{c}} 13843@item @code{void __SMASS (sw1, sw1)} 13844@tab @code{__SMASS (@var{a}, @var{b})} 13845@tab @code{SMASS @var{a},@var{b}} 13846@item @code{void __SMSSS (sw1, sw1)} 13847@tab @code{__SMSSS (@var{a}, @var{b})} 13848@tab @code{SMSSS @var{a},@var{b}} 13849@item @code{void __SMU (sw1, sw1)} 13850@tab @code{__SMU (@var{a}, @var{b})} 13851@tab @code{SMU @var{a},@var{b}} 13852@item @code{sw2 __SMUL (sw1, sw1)} 13853@tab @code{@var{c} = __SMUL (@var{a}, @var{b})} 13854@tab @code{SMUL @var{a},@var{b},@var{c}} 13855@item @code{sw1 __SUBSS (sw1, sw1)} 13856@tab @code{@var{c} = __SUBSS (@var{a}, @var{b})} 13857@tab @code{SUBSS @var{a},@var{b},@var{c}} 13858@item @code{uw2 __UMUL (uw1, uw1)} 13859@tab @code{@var{c} = __UMUL (@var{a}, @var{b})} 13860@tab @code{UMUL @var{a},@var{b},@var{c}} 13861@end multitable 13862 13863@node Directly-mapped Media Functions 13864@subsubsection Directly-Mapped Media Functions 13865 13866The functions listed below map directly to FR-V M-type instructions. 13867 13868@multitable @columnfractions .45 .32 .23 13869@item Function prototype @tab Example usage @tab Assembly output 13870@item @code{uw1 __MABSHS (sw1)} 13871@tab @code{@var{b} = __MABSHS (@var{a})} 13872@tab @code{MABSHS @var{a},@var{b}} 13873@item @code{void __MADDACCS (acc, acc)} 13874@tab @code{__MADDACCS (@var{b}, @var{a})} 13875@tab @code{MADDACCS @var{a},@var{b}} 13876@item @code{sw1 __MADDHSS (sw1, sw1)} 13877@tab @code{@var{c} = __MADDHSS (@var{a}, @var{b})} 13878@tab @code{MADDHSS @var{a},@var{b},@var{c}} 13879@item @code{uw1 __MADDHUS (uw1, uw1)} 13880@tab @code{@var{c} = __MADDHUS (@var{a}, @var{b})} 13881@tab @code{MADDHUS @var{a},@var{b},@var{c}} 13882@item @code{uw1 __MAND (uw1, uw1)} 13883@tab @code{@var{c} = __MAND (@var{a}, @var{b})} 13884@tab @code{MAND @var{a},@var{b},@var{c}} 13885@item @code{void __MASACCS (acc, acc)} 13886@tab @code{__MASACCS (@var{b}, @var{a})} 13887@tab @code{MASACCS @var{a},@var{b}} 13888@item @code{uw1 __MAVEH (uw1, uw1)} 13889@tab @code{@var{c} = __MAVEH (@var{a}, @var{b})} 13890@tab @code{MAVEH @var{a},@var{b},@var{c}} 13891@item @code{uw2 __MBTOH (uw1)} 13892@tab @code{@var{b} = __MBTOH (@var{a})} 13893@tab @code{MBTOH @var{a},@var{b}} 13894@item @code{void __MBTOHE (uw1 *, uw1)} 13895@tab @code{__MBTOHE (&@var{b}, @var{a})} 13896@tab @code{MBTOHE @var{a},@var{b}} 13897@item @code{void __MCLRACC (acc)} 13898@tab @code{__MCLRACC (@var{a})} 13899@tab @code{MCLRACC @var{a}} 13900@item @code{void __MCLRACCA (void)} 13901@tab @code{__MCLRACCA ()} 13902@tab @code{MCLRACCA} 13903@item @code{uw1 __Mcop1 (uw1, uw1)} 13904@tab @code{@var{c} = __Mcop1 (@var{a}, @var{b})} 13905@tab @code{Mcop1 @var{a},@var{b},@var{c}} 13906@item @code{uw1 __Mcop2 (uw1, uw1)} 13907@tab @code{@var{c} = __Mcop2 (@var{a}, @var{b})} 13908@tab @code{Mcop2 @var{a},@var{b},@var{c}} 13909@item @code{uw1 __MCPLHI (uw2, const)} 13910@tab @code{@var{c} = __MCPLHI (@var{a}, @var{b})} 13911@tab @code{MCPLHI @var{a},#@var{b},@var{c}} 13912@item @code{uw1 __MCPLI (uw2, const)} 13913@tab @code{@var{c} = __MCPLI (@var{a}, @var{b})} 13914@tab @code{MCPLI @var{a},#@var{b},@var{c}} 13915@item @code{void __MCPXIS (acc, sw1, sw1)} 13916@tab @code{__MCPXIS (@var{c}, @var{a}, @var{b})} 13917@tab @code{MCPXIS @var{a},@var{b},@var{c}} 13918@item @code{void __MCPXIU (acc, uw1, uw1)} 13919@tab @code{__MCPXIU (@var{c}, @var{a}, @var{b})} 13920@tab @code{MCPXIU @var{a},@var{b},@var{c}} 13921@item @code{void __MCPXRS (acc, sw1, sw1)} 13922@tab @code{__MCPXRS (@var{c}, @var{a}, @var{b})} 13923@tab @code{MCPXRS @var{a},@var{b},@var{c}} 13924@item @code{void __MCPXRU (acc, uw1, uw1)} 13925@tab @code{__MCPXRU (@var{c}, @var{a}, @var{b})} 13926@tab @code{MCPXRU @var{a},@var{b},@var{c}} 13927@item @code{uw1 __MCUT (acc, uw1)} 13928@tab @code{@var{c} = __MCUT (@var{a}, @var{b})} 13929@tab @code{MCUT @var{a},@var{b},@var{c}} 13930@item @code{uw1 __MCUTSS (acc, sw1)} 13931@tab @code{@var{c} = __MCUTSS (@var{a}, @var{b})} 13932@tab @code{MCUTSS @var{a},@var{b},@var{c}} 13933@item @code{void __MDADDACCS (acc, acc)} 13934@tab @code{__MDADDACCS (@var{b}, @var{a})} 13935@tab @code{MDADDACCS @var{a},@var{b}} 13936@item @code{void __MDASACCS (acc, acc)} 13937@tab @code{__MDASACCS (@var{b}, @var{a})} 13938@tab @code{MDASACCS @var{a},@var{b}} 13939@item @code{uw2 __MDCUTSSI (acc, const)} 13940@tab @code{@var{c} = __MDCUTSSI (@var{a}, @var{b})} 13941@tab @code{MDCUTSSI @var{a},#@var{b},@var{c}} 13942@item @code{uw2 __MDPACKH (uw2, uw2)} 13943@tab @code{@var{c} = __MDPACKH (@var{a}, @var{b})} 13944@tab @code{MDPACKH @var{a},@var{b},@var{c}} 13945@item @code{uw2 __MDROTLI (uw2, const)} 13946@tab @code{@var{c} = __MDROTLI (@var{a}, @var{b})} 13947@tab @code{MDROTLI @var{a},#@var{b},@var{c}} 13948@item @code{void __MDSUBACCS (acc, acc)} 13949@tab @code{__MDSUBACCS (@var{b}, @var{a})} 13950@tab @code{MDSUBACCS @var{a},@var{b}} 13951@item @code{void __MDUNPACKH (uw1 *, uw2)} 13952@tab @code{__MDUNPACKH (&@var{b}, @var{a})} 13953@tab @code{MDUNPACKH @var{a},@var{b}} 13954@item @code{uw2 __MEXPDHD (uw1, const)} 13955@tab @code{@var{c} = __MEXPDHD (@var{a}, @var{b})} 13956@tab @code{MEXPDHD @var{a},#@var{b},@var{c}} 13957@item @code{uw1 __MEXPDHW (uw1, const)} 13958@tab @code{@var{c} = __MEXPDHW (@var{a}, @var{b})} 13959@tab @code{MEXPDHW @var{a},#@var{b},@var{c}} 13960@item @code{uw1 __MHDSETH (uw1, const)} 13961@tab @code{@var{c} = __MHDSETH (@var{a}, @var{b})} 13962@tab @code{MHDSETH @var{a},#@var{b},@var{c}} 13963@item @code{sw1 __MHDSETS (const)} 13964@tab @code{@var{b} = __MHDSETS (@var{a})} 13965@tab @code{MHDSETS #@var{a},@var{b}} 13966@item @code{uw1 __MHSETHIH (uw1, const)} 13967@tab @code{@var{b} = __MHSETHIH (@var{b}, @var{a})} 13968@tab @code{MHSETHIH #@var{a},@var{b}} 13969@item @code{sw1 __MHSETHIS (sw1, const)} 13970@tab @code{@var{b} = __MHSETHIS (@var{b}, @var{a})} 13971@tab @code{MHSETHIS #@var{a},@var{b}} 13972@item @code{uw1 __MHSETLOH (uw1, const)} 13973@tab @code{@var{b} = __MHSETLOH (@var{b}, @var{a})} 13974@tab @code{MHSETLOH #@var{a},@var{b}} 13975@item @code{sw1 __MHSETLOS (sw1, const)} 13976@tab @code{@var{b} = __MHSETLOS (@var{b}, @var{a})} 13977@tab @code{MHSETLOS #@var{a},@var{b}} 13978@item @code{uw1 __MHTOB (uw2)} 13979@tab @code{@var{b} = __MHTOB (@var{a})} 13980@tab @code{MHTOB @var{a},@var{b}} 13981@item @code{void __MMACHS (acc, sw1, sw1)} 13982@tab @code{__MMACHS (@var{c}, @var{a}, @var{b})} 13983@tab @code{MMACHS @var{a},@var{b},@var{c}} 13984@item @code{void __MMACHU (acc, uw1, uw1)} 13985@tab @code{__MMACHU (@var{c}, @var{a}, @var{b})} 13986@tab @code{MMACHU @var{a},@var{b},@var{c}} 13987@item @code{void __MMRDHS (acc, sw1, sw1)} 13988@tab @code{__MMRDHS (@var{c}, @var{a}, @var{b})} 13989@tab @code{MMRDHS @var{a},@var{b},@var{c}} 13990@item @code{void __MMRDHU (acc, uw1, uw1)} 13991@tab @code{__MMRDHU (@var{c}, @var{a}, @var{b})} 13992@tab @code{MMRDHU @var{a},@var{b},@var{c}} 13993@item @code{void __MMULHS (acc, sw1, sw1)} 13994@tab @code{__MMULHS (@var{c}, @var{a}, @var{b})} 13995@tab @code{MMULHS @var{a},@var{b},@var{c}} 13996@item @code{void __MMULHU (acc, uw1, uw1)} 13997@tab @code{__MMULHU (@var{c}, @var{a}, @var{b})} 13998@tab @code{MMULHU @var{a},@var{b},@var{c}} 13999@item @code{void __MMULXHS (acc, sw1, sw1)} 14000@tab @code{__MMULXHS (@var{c}, @var{a}, @var{b})} 14001@tab @code{MMULXHS @var{a},@var{b},@var{c}} 14002@item @code{void __MMULXHU (acc, uw1, uw1)} 14003@tab @code{__MMULXHU (@var{c}, @var{a}, @var{b})} 14004@tab @code{MMULXHU @var{a},@var{b},@var{c}} 14005@item @code{uw1 __MNOT (uw1)} 14006@tab @code{@var{b} = __MNOT (@var{a})} 14007@tab @code{MNOT @var{a},@var{b}} 14008@item @code{uw1 __MOR (uw1, uw1)} 14009@tab @code{@var{c} = __MOR (@var{a}, @var{b})} 14010@tab @code{MOR @var{a},@var{b},@var{c}} 14011@item @code{uw1 __MPACKH (uh, uh)} 14012@tab @code{@var{c} = __MPACKH (@var{a}, @var{b})} 14013@tab @code{MPACKH @var{a},@var{b},@var{c}} 14014@item @code{sw2 __MQADDHSS (sw2, sw2)} 14015@tab @code{@var{c} = __MQADDHSS (@var{a}, @var{b})} 14016@tab @code{MQADDHSS @var{a},@var{b},@var{c}} 14017@item @code{uw2 __MQADDHUS (uw2, uw2)} 14018@tab @code{@var{c} = __MQADDHUS (@var{a}, @var{b})} 14019@tab @code{MQADDHUS @var{a},@var{b},@var{c}} 14020@item @code{void __MQCPXIS (acc, sw2, sw2)} 14021@tab @code{__MQCPXIS (@var{c}, @var{a}, @var{b})} 14022@tab @code{MQCPXIS @var{a},@var{b},@var{c}} 14023@item @code{void __MQCPXIU (acc, uw2, uw2)} 14024@tab @code{__MQCPXIU (@var{c}, @var{a}, @var{b})} 14025@tab @code{MQCPXIU @var{a},@var{b},@var{c}} 14026@item @code{void __MQCPXRS (acc, sw2, sw2)} 14027@tab @code{__MQCPXRS (@var{c}, @var{a}, @var{b})} 14028@tab @code{MQCPXRS @var{a},@var{b},@var{c}} 14029@item @code{void __MQCPXRU (acc, uw2, uw2)} 14030@tab @code{__MQCPXRU (@var{c}, @var{a}, @var{b})} 14031@tab @code{MQCPXRU @var{a},@var{b},@var{c}} 14032@item @code{sw2 __MQLCLRHS (sw2, sw2)} 14033@tab @code{@var{c} = __MQLCLRHS (@var{a}, @var{b})} 14034@tab @code{MQLCLRHS @var{a},@var{b},@var{c}} 14035@item @code{sw2 __MQLMTHS (sw2, sw2)} 14036@tab @code{@var{c} = __MQLMTHS (@var{a}, @var{b})} 14037@tab @code{MQLMTHS @var{a},@var{b},@var{c}} 14038@item @code{void __MQMACHS (acc, sw2, sw2)} 14039@tab @code{__MQMACHS (@var{c}, @var{a}, @var{b})} 14040@tab @code{MQMACHS @var{a},@var{b},@var{c}} 14041@item @code{void __MQMACHU (acc, uw2, uw2)} 14042@tab @code{__MQMACHU (@var{c}, @var{a}, @var{b})} 14043@tab @code{MQMACHU @var{a},@var{b},@var{c}} 14044@item @code{void __MQMACXHS (acc, sw2, sw2)} 14045@tab @code{__MQMACXHS (@var{c}, @var{a}, @var{b})} 14046@tab @code{MQMACXHS @var{a},@var{b},@var{c}} 14047@item @code{void __MQMULHS (acc, sw2, sw2)} 14048@tab @code{__MQMULHS (@var{c}, @var{a}, @var{b})} 14049@tab @code{MQMULHS @var{a},@var{b},@var{c}} 14050@item @code{void __MQMULHU (acc, uw2, uw2)} 14051@tab @code{__MQMULHU (@var{c}, @var{a}, @var{b})} 14052@tab @code{MQMULHU @var{a},@var{b},@var{c}} 14053@item @code{void __MQMULXHS (acc, sw2, sw2)} 14054@tab @code{__MQMULXHS (@var{c}, @var{a}, @var{b})} 14055@tab @code{MQMULXHS @var{a},@var{b},@var{c}} 14056@item @code{void __MQMULXHU (acc, uw2, uw2)} 14057@tab @code{__MQMULXHU (@var{c}, @var{a}, @var{b})} 14058@tab @code{MQMULXHU @var{a},@var{b},@var{c}} 14059@item @code{sw2 __MQSATHS (sw2, sw2)} 14060@tab @code{@var{c} = __MQSATHS (@var{a}, @var{b})} 14061@tab @code{MQSATHS @var{a},@var{b},@var{c}} 14062@item @code{uw2 __MQSLLHI (uw2, int)} 14063@tab @code{@var{c} = __MQSLLHI (@var{a}, @var{b})} 14064@tab @code{MQSLLHI @var{a},@var{b},@var{c}} 14065@item @code{sw2 __MQSRAHI (sw2, int)} 14066@tab @code{@var{c} = __MQSRAHI (@var{a}, @var{b})} 14067@tab @code{MQSRAHI @var{a},@var{b},@var{c}} 14068@item @code{sw2 __MQSUBHSS (sw2, sw2)} 14069@tab @code{@var{c} = __MQSUBHSS (@var{a}, @var{b})} 14070@tab @code{MQSUBHSS @var{a},@var{b},@var{c}} 14071@item @code{uw2 __MQSUBHUS (uw2, uw2)} 14072@tab @code{@var{c} = __MQSUBHUS (@var{a}, @var{b})} 14073@tab @code{MQSUBHUS @var{a},@var{b},@var{c}} 14074@item @code{void __MQXMACHS (acc, sw2, sw2)} 14075@tab @code{__MQXMACHS (@var{c}, @var{a}, @var{b})} 14076@tab @code{MQXMACHS @var{a},@var{b},@var{c}} 14077@item @code{void __MQXMACXHS (acc, sw2, sw2)} 14078@tab @code{__MQXMACXHS (@var{c}, @var{a}, @var{b})} 14079@tab @code{MQXMACXHS @var{a},@var{b},@var{c}} 14080@item @code{uw1 __MRDACC (acc)} 14081@tab @code{@var{b} = __MRDACC (@var{a})} 14082@tab @code{MRDACC @var{a},@var{b}} 14083@item @code{uw1 __MRDACCG (acc)} 14084@tab @code{@var{b} = __MRDACCG (@var{a})} 14085@tab @code{MRDACCG @var{a},@var{b}} 14086@item @code{uw1 __MROTLI (uw1, const)} 14087@tab @code{@var{c} = __MROTLI (@var{a}, @var{b})} 14088@tab @code{MROTLI @var{a},#@var{b},@var{c}} 14089@item @code{uw1 __MROTRI (uw1, const)} 14090@tab @code{@var{c} = __MROTRI (@var{a}, @var{b})} 14091@tab @code{MROTRI @var{a},#@var{b},@var{c}} 14092@item @code{sw1 __MSATHS (sw1, sw1)} 14093@tab @code{@var{c} = __MSATHS (@var{a}, @var{b})} 14094@tab @code{MSATHS @var{a},@var{b},@var{c}} 14095@item @code{uw1 __MSATHU (uw1, uw1)} 14096@tab @code{@var{c} = __MSATHU (@var{a}, @var{b})} 14097@tab @code{MSATHU @var{a},@var{b},@var{c}} 14098@item @code{uw1 __MSLLHI (uw1, const)} 14099@tab @code{@var{c} = __MSLLHI (@var{a}, @var{b})} 14100@tab @code{MSLLHI @var{a},#@var{b},@var{c}} 14101@item @code{sw1 __MSRAHI (sw1, const)} 14102@tab @code{@var{c} = __MSRAHI (@var{a}, @var{b})} 14103@tab @code{MSRAHI @var{a},#@var{b},@var{c}} 14104@item @code{uw1 __MSRLHI (uw1, const)} 14105@tab @code{@var{c} = __MSRLHI (@var{a}, @var{b})} 14106@tab @code{MSRLHI @var{a},#@var{b},@var{c}} 14107@item @code{void __MSUBACCS (acc, acc)} 14108@tab @code{__MSUBACCS (@var{b}, @var{a})} 14109@tab @code{MSUBACCS @var{a},@var{b}} 14110@item @code{sw1 __MSUBHSS (sw1, sw1)} 14111@tab @code{@var{c} = __MSUBHSS (@var{a}, @var{b})} 14112@tab @code{MSUBHSS @var{a},@var{b},@var{c}} 14113@item @code{uw1 __MSUBHUS (uw1, uw1)} 14114@tab @code{@var{c} = __MSUBHUS (@var{a}, @var{b})} 14115@tab @code{MSUBHUS @var{a},@var{b},@var{c}} 14116@item @code{void __MTRAP (void)} 14117@tab @code{__MTRAP ()} 14118@tab @code{MTRAP} 14119@item @code{uw2 __MUNPACKH (uw1)} 14120@tab @code{@var{b} = __MUNPACKH (@var{a})} 14121@tab @code{MUNPACKH @var{a},@var{b}} 14122@item @code{uw1 __MWCUT (uw2, uw1)} 14123@tab @code{@var{c} = __MWCUT (@var{a}, @var{b})} 14124@tab @code{MWCUT @var{a},@var{b},@var{c}} 14125@item @code{void __MWTACC (acc, uw1)} 14126@tab @code{__MWTACC (@var{b}, @var{a})} 14127@tab @code{MWTACC @var{a},@var{b}} 14128@item @code{void __MWTACCG (acc, uw1)} 14129@tab @code{__MWTACCG (@var{b}, @var{a})} 14130@tab @code{MWTACCG @var{a},@var{b}} 14131@item @code{uw1 __MXOR (uw1, uw1)} 14132@tab @code{@var{c} = __MXOR (@var{a}, @var{b})} 14133@tab @code{MXOR @var{a},@var{b},@var{c}} 14134@end multitable 14135 14136@node Raw read/write Functions 14137@subsubsection Raw Read/Write Functions 14138 14139This sections describes built-in functions related to read and write 14140instructions to access memory. These functions generate 14141@code{membar} instructions to flush the I/O load and stores where 14142appropriate, as described in Fujitsu's manual described above. 14143 14144@table @code 14145 14146@item unsigned char __builtin_read8 (void *@var{data}) 14147@item unsigned short __builtin_read16 (void *@var{data}) 14148@item unsigned long __builtin_read32 (void *@var{data}) 14149@item unsigned long long __builtin_read64 (void *@var{data}) 14150 14151@item void __builtin_write8 (void *@var{data}, unsigned char @var{datum}) 14152@item void __builtin_write16 (void *@var{data}, unsigned short @var{datum}) 14153@item void __builtin_write32 (void *@var{data}, unsigned long @var{datum}) 14154@item void __builtin_write64 (void *@var{data}, unsigned long long @var{datum}) 14155@end table 14156 14157@node Other Built-in Functions 14158@subsubsection Other Built-in Functions 14159 14160This section describes built-in functions that are not named after 14161a specific FR-V instruction. 14162 14163@table @code 14164@item sw2 __IACCreadll (iacc @var{reg}) 14165Return the full 64-bit value of IACC0@. The @var{reg} argument is reserved 14166for future expansion and must be 0. 14167 14168@item sw1 __IACCreadl (iacc @var{reg}) 14169Return the value of IACC0H if @var{reg} is 0 and IACC0L if @var{reg} is 1. 14170Other values of @var{reg} are rejected as invalid. 14171 14172@item void __IACCsetll (iacc @var{reg}, sw2 @var{x}) 14173Set the full 64-bit value of IACC0 to @var{x}. The @var{reg} argument 14174is reserved for future expansion and must be 0. 14175 14176@item void __IACCsetl (iacc @var{reg}, sw1 @var{x}) 14177Set IACC0H to @var{x} if @var{reg} is 0 and IACC0L to @var{x} if @var{reg} 14178is 1. Other values of @var{reg} are rejected as invalid. 14179 14180@item void __data_prefetch0 (const void *@var{x}) 14181Use the @code{dcpl} instruction to load the contents of address @var{x} 14182into the data cache. 14183 14184@item void __data_prefetch (const void *@var{x}) 14185Use the @code{nldub} instruction to load the contents of address @var{x} 14186into the data cache. The instruction is issued in slot I1@. 14187@end table 14188 14189@node MIPS DSP Built-in Functions 14190@subsection MIPS DSP Built-in Functions 14191 14192The MIPS DSP Application-Specific Extension (ASE) includes new 14193instructions that are designed to improve the performance of DSP and 14194media applications. It provides instructions that operate on packed 141958-bit/16-bit integer data, Q7, Q15 and Q31 fractional data. 14196 14197GCC supports MIPS DSP operations using both the generic 14198vector extensions (@pxref{Vector Extensions}) and a collection of 14199MIPS-specific built-in functions. Both kinds of support are 14200enabled by the @option{-mdsp} command-line option. 14201 14202Revision 2 of the ASE was introduced in the second half of 2006. 14203This revision adds extra instructions to the original ASE, but is 14204otherwise backwards-compatible with it. You can select revision 2 14205using the command-line option @option{-mdspr2}; this option implies 14206@option{-mdsp}. 14207 14208The SCOUNT and POS bits of the DSP control register are global. The 14209WRDSP, EXTPDP, EXTPDPV and MTHLIP instructions modify the SCOUNT and 14210POS bits. During optimization, the compiler does not delete these 14211instructions and it does not delete calls to functions containing 14212these instructions. 14213 14214At present, GCC only provides support for operations on 32-bit 14215vectors. The vector type associated with 8-bit integer data is 14216usually called @code{v4i8}, the vector type associated with Q7 14217is usually called @code{v4q7}, the vector type associated with 16-bit 14218integer data is usually called @code{v2i16}, and the vector type 14219associated with Q15 is usually called @code{v2q15}. They can be 14220defined in C as follows: 14221 14222@smallexample 14223typedef signed char v4i8 __attribute__ ((vector_size(4))); 14224typedef signed char v4q7 __attribute__ ((vector_size(4))); 14225typedef short v2i16 __attribute__ ((vector_size(4))); 14226typedef short v2q15 __attribute__ ((vector_size(4))); 14227@end smallexample 14228 14229@code{v4i8}, @code{v4q7}, @code{v2i16} and @code{v2q15} values are 14230initialized in the same way as aggregates. For example: 14231 14232@smallexample 14233v4i8 a = @{1, 2, 3, 4@}; 14234v4i8 b; 14235b = (v4i8) @{5, 6, 7, 8@}; 14236 14237v2q15 c = @{0x0fcb, 0x3a75@}; 14238v2q15 d; 14239d = (v2q15) @{0.1234 * 0x1.0p15, 0.4567 * 0x1.0p15@}; 14240@end smallexample 14241 14242@emph{Note:} The CPU's endianness determines the order in which values 14243are packed. On little-endian targets, the first value is the least 14244significant and the last value is the most significant. The opposite 14245order applies to big-endian targets. For example, the code above 14246sets the lowest byte of @code{a} to @code{1} on little-endian targets 14247and @code{4} on big-endian targets. 14248 14249@emph{Note:} Q7, Q15 and Q31 values must be initialized with their integer 14250representation. As shown in this example, the integer representation 14251of a Q7 value can be obtained by multiplying the fractional value by 14252@code{0x1.0p7}. The equivalent for Q15 values is to multiply by 14253@code{0x1.0p15}. The equivalent for Q31 values is to multiply by 14254@code{0x1.0p31}. 14255 14256The table below lists the @code{v4i8} and @code{v2q15} operations for which 14257hardware support exists. @code{a} and @code{b} are @code{v4i8} values, 14258and @code{c} and @code{d} are @code{v2q15} values. 14259 14260@multitable @columnfractions .50 .50 14261@item C code @tab MIPS instruction 14262@item @code{a + b} @tab @code{addu.qb} 14263@item @code{c + d} @tab @code{addq.ph} 14264@item @code{a - b} @tab @code{subu.qb} 14265@item @code{c - d} @tab @code{subq.ph} 14266@end multitable 14267 14268The table below lists the @code{v2i16} operation for which 14269hardware support exists for the DSP ASE REV 2. @code{e} and @code{f} are 14270@code{v2i16} values. 14271 14272@multitable @columnfractions .50 .50 14273@item C code @tab MIPS instruction 14274@item @code{e * f} @tab @code{mul.ph} 14275@end multitable 14276 14277It is easier to describe the DSP built-in functions if we first define 14278the following types: 14279 14280@smallexample 14281typedef int q31; 14282typedef int i32; 14283typedef unsigned int ui32; 14284typedef long long a64; 14285@end smallexample 14286 14287@code{q31} and @code{i32} are actually the same as @code{int}, but we 14288use @code{q31} to indicate a Q31 fractional value and @code{i32} to 14289indicate a 32-bit integer value. Similarly, @code{a64} is the same as 14290@code{long long}, but we use @code{a64} to indicate values that are 14291placed in one of the four DSP accumulators (@code{$ac0}, 14292@code{$ac1}, @code{$ac2} or @code{$ac3}). 14293 14294Also, some built-in functions prefer or require immediate numbers as 14295parameters, because the corresponding DSP instructions accept both immediate 14296numbers and register operands, or accept immediate numbers only. The 14297immediate parameters are listed as follows. 14298 14299@smallexample 14300imm0_3: 0 to 3. 14301imm0_7: 0 to 7. 14302imm0_15: 0 to 15. 14303imm0_31: 0 to 31. 14304imm0_63: 0 to 63. 14305imm0_255: 0 to 255. 14306imm_n32_31: -32 to 31. 14307imm_n512_511: -512 to 511. 14308@end smallexample 14309 14310The following built-in functions map directly to a particular MIPS DSP 14311instruction. Please refer to the architecture specification 14312for details on what each instruction does. 14313 14314@smallexample 14315v2q15 __builtin_mips_addq_ph (v2q15, v2q15) 14316v2q15 __builtin_mips_addq_s_ph (v2q15, v2q15) 14317q31 __builtin_mips_addq_s_w (q31, q31) 14318v4i8 __builtin_mips_addu_qb (v4i8, v4i8) 14319v4i8 __builtin_mips_addu_s_qb (v4i8, v4i8) 14320v2q15 __builtin_mips_subq_ph (v2q15, v2q15) 14321v2q15 __builtin_mips_subq_s_ph (v2q15, v2q15) 14322q31 __builtin_mips_subq_s_w (q31, q31) 14323v4i8 __builtin_mips_subu_qb (v4i8, v4i8) 14324v4i8 __builtin_mips_subu_s_qb (v4i8, v4i8) 14325i32 __builtin_mips_addsc (i32, i32) 14326i32 __builtin_mips_addwc (i32, i32) 14327i32 __builtin_mips_modsub (i32, i32) 14328i32 __builtin_mips_raddu_w_qb (v4i8) 14329v2q15 __builtin_mips_absq_s_ph (v2q15) 14330q31 __builtin_mips_absq_s_w (q31) 14331v4i8 __builtin_mips_precrq_qb_ph (v2q15, v2q15) 14332v2q15 __builtin_mips_precrq_ph_w (q31, q31) 14333v2q15 __builtin_mips_precrq_rs_ph_w (q31, q31) 14334v4i8 __builtin_mips_precrqu_s_qb_ph (v2q15, v2q15) 14335q31 __builtin_mips_preceq_w_phl (v2q15) 14336q31 __builtin_mips_preceq_w_phr (v2q15) 14337v2q15 __builtin_mips_precequ_ph_qbl (v4i8) 14338v2q15 __builtin_mips_precequ_ph_qbr (v4i8) 14339v2q15 __builtin_mips_precequ_ph_qbla (v4i8) 14340v2q15 __builtin_mips_precequ_ph_qbra (v4i8) 14341v2q15 __builtin_mips_preceu_ph_qbl (v4i8) 14342v2q15 __builtin_mips_preceu_ph_qbr (v4i8) 14343v2q15 __builtin_mips_preceu_ph_qbla (v4i8) 14344v2q15 __builtin_mips_preceu_ph_qbra (v4i8) 14345v4i8 __builtin_mips_shll_qb (v4i8, imm0_7) 14346v4i8 __builtin_mips_shll_qb (v4i8, i32) 14347v2q15 __builtin_mips_shll_ph (v2q15, imm0_15) 14348v2q15 __builtin_mips_shll_ph (v2q15, i32) 14349v2q15 __builtin_mips_shll_s_ph (v2q15, imm0_15) 14350v2q15 __builtin_mips_shll_s_ph (v2q15, i32) 14351q31 __builtin_mips_shll_s_w (q31, imm0_31) 14352q31 __builtin_mips_shll_s_w (q31, i32) 14353v4i8 __builtin_mips_shrl_qb (v4i8, imm0_7) 14354v4i8 __builtin_mips_shrl_qb (v4i8, i32) 14355v2q15 __builtin_mips_shra_ph (v2q15, imm0_15) 14356v2q15 __builtin_mips_shra_ph (v2q15, i32) 14357v2q15 __builtin_mips_shra_r_ph (v2q15, imm0_15) 14358v2q15 __builtin_mips_shra_r_ph (v2q15, i32) 14359q31 __builtin_mips_shra_r_w (q31, imm0_31) 14360q31 __builtin_mips_shra_r_w (q31, i32) 14361v2q15 __builtin_mips_muleu_s_ph_qbl (v4i8, v2q15) 14362v2q15 __builtin_mips_muleu_s_ph_qbr (v4i8, v2q15) 14363v2q15 __builtin_mips_mulq_rs_ph (v2q15, v2q15) 14364q31 __builtin_mips_muleq_s_w_phl (v2q15, v2q15) 14365q31 __builtin_mips_muleq_s_w_phr (v2q15, v2q15) 14366a64 __builtin_mips_dpau_h_qbl (a64, v4i8, v4i8) 14367a64 __builtin_mips_dpau_h_qbr (a64, v4i8, v4i8) 14368a64 __builtin_mips_dpsu_h_qbl (a64, v4i8, v4i8) 14369a64 __builtin_mips_dpsu_h_qbr (a64, v4i8, v4i8) 14370a64 __builtin_mips_dpaq_s_w_ph (a64, v2q15, v2q15) 14371a64 __builtin_mips_dpaq_sa_l_w (a64, q31, q31) 14372a64 __builtin_mips_dpsq_s_w_ph (a64, v2q15, v2q15) 14373a64 __builtin_mips_dpsq_sa_l_w (a64, q31, q31) 14374a64 __builtin_mips_mulsaq_s_w_ph (a64, v2q15, v2q15) 14375a64 __builtin_mips_maq_s_w_phl (a64, v2q15, v2q15) 14376a64 __builtin_mips_maq_s_w_phr (a64, v2q15, v2q15) 14377a64 __builtin_mips_maq_sa_w_phl (a64, v2q15, v2q15) 14378a64 __builtin_mips_maq_sa_w_phr (a64, v2q15, v2q15) 14379i32 __builtin_mips_bitrev (i32) 14380i32 __builtin_mips_insv (i32, i32) 14381v4i8 __builtin_mips_repl_qb (imm0_255) 14382v4i8 __builtin_mips_repl_qb (i32) 14383v2q15 __builtin_mips_repl_ph (imm_n512_511) 14384v2q15 __builtin_mips_repl_ph (i32) 14385void __builtin_mips_cmpu_eq_qb (v4i8, v4i8) 14386void __builtin_mips_cmpu_lt_qb (v4i8, v4i8) 14387void __builtin_mips_cmpu_le_qb (v4i8, v4i8) 14388i32 __builtin_mips_cmpgu_eq_qb (v4i8, v4i8) 14389i32 __builtin_mips_cmpgu_lt_qb (v4i8, v4i8) 14390i32 __builtin_mips_cmpgu_le_qb (v4i8, v4i8) 14391void __builtin_mips_cmp_eq_ph (v2q15, v2q15) 14392void __builtin_mips_cmp_lt_ph (v2q15, v2q15) 14393void __builtin_mips_cmp_le_ph (v2q15, v2q15) 14394v4i8 __builtin_mips_pick_qb (v4i8, v4i8) 14395v2q15 __builtin_mips_pick_ph (v2q15, v2q15) 14396v2q15 __builtin_mips_packrl_ph (v2q15, v2q15) 14397i32 __builtin_mips_extr_w (a64, imm0_31) 14398i32 __builtin_mips_extr_w (a64, i32) 14399i32 __builtin_mips_extr_r_w (a64, imm0_31) 14400i32 __builtin_mips_extr_s_h (a64, i32) 14401i32 __builtin_mips_extr_rs_w (a64, imm0_31) 14402i32 __builtin_mips_extr_rs_w (a64, i32) 14403i32 __builtin_mips_extr_s_h (a64, imm0_31) 14404i32 __builtin_mips_extr_r_w (a64, i32) 14405i32 __builtin_mips_extp (a64, imm0_31) 14406i32 __builtin_mips_extp (a64, i32) 14407i32 __builtin_mips_extpdp (a64, imm0_31) 14408i32 __builtin_mips_extpdp (a64, i32) 14409a64 __builtin_mips_shilo (a64, imm_n32_31) 14410a64 __builtin_mips_shilo (a64, i32) 14411a64 __builtin_mips_mthlip (a64, i32) 14412void __builtin_mips_wrdsp (i32, imm0_63) 14413i32 __builtin_mips_rddsp (imm0_63) 14414i32 __builtin_mips_lbux (void *, i32) 14415i32 __builtin_mips_lhx (void *, i32) 14416i32 __builtin_mips_lwx (void *, i32) 14417a64 __builtin_mips_ldx (void *, i32) [MIPS64 only] 14418i32 __builtin_mips_bposge32 (void) 14419a64 __builtin_mips_madd (a64, i32, i32); 14420a64 __builtin_mips_maddu (a64, ui32, ui32); 14421a64 __builtin_mips_msub (a64, i32, i32); 14422a64 __builtin_mips_msubu (a64, ui32, ui32); 14423a64 __builtin_mips_mult (i32, i32); 14424a64 __builtin_mips_multu (ui32, ui32); 14425@end smallexample 14426 14427The following built-in functions map directly to a particular MIPS DSP REV 2 14428instruction. Please refer to the architecture specification 14429for details on what each instruction does. 14430 14431@smallexample 14432v4q7 __builtin_mips_absq_s_qb (v4q7); 14433v2i16 __builtin_mips_addu_ph (v2i16, v2i16); 14434v2i16 __builtin_mips_addu_s_ph (v2i16, v2i16); 14435v4i8 __builtin_mips_adduh_qb (v4i8, v4i8); 14436v4i8 __builtin_mips_adduh_r_qb (v4i8, v4i8); 14437i32 __builtin_mips_append (i32, i32, imm0_31); 14438i32 __builtin_mips_balign (i32, i32, imm0_3); 14439i32 __builtin_mips_cmpgdu_eq_qb (v4i8, v4i8); 14440i32 __builtin_mips_cmpgdu_lt_qb (v4i8, v4i8); 14441i32 __builtin_mips_cmpgdu_le_qb (v4i8, v4i8); 14442a64 __builtin_mips_dpa_w_ph (a64, v2i16, v2i16); 14443a64 __builtin_mips_dps_w_ph (a64, v2i16, v2i16); 14444v2i16 __builtin_mips_mul_ph (v2i16, v2i16); 14445v2i16 __builtin_mips_mul_s_ph (v2i16, v2i16); 14446q31 __builtin_mips_mulq_rs_w (q31, q31); 14447v2q15 __builtin_mips_mulq_s_ph (v2q15, v2q15); 14448q31 __builtin_mips_mulq_s_w (q31, q31); 14449a64 __builtin_mips_mulsa_w_ph (a64, v2i16, v2i16); 14450v4i8 __builtin_mips_precr_qb_ph (v2i16, v2i16); 14451v2i16 __builtin_mips_precr_sra_ph_w (i32, i32, imm0_31); 14452v2i16 __builtin_mips_precr_sra_r_ph_w (i32, i32, imm0_31); 14453i32 __builtin_mips_prepend (i32, i32, imm0_31); 14454v4i8 __builtin_mips_shra_qb (v4i8, imm0_7); 14455v4i8 __builtin_mips_shra_r_qb (v4i8, imm0_7); 14456v4i8 __builtin_mips_shra_qb (v4i8, i32); 14457v4i8 __builtin_mips_shra_r_qb (v4i8, i32); 14458v2i16 __builtin_mips_shrl_ph (v2i16, imm0_15); 14459v2i16 __builtin_mips_shrl_ph (v2i16, i32); 14460v2i16 __builtin_mips_subu_ph (v2i16, v2i16); 14461v2i16 __builtin_mips_subu_s_ph (v2i16, v2i16); 14462v4i8 __builtin_mips_subuh_qb (v4i8, v4i8); 14463v4i8 __builtin_mips_subuh_r_qb (v4i8, v4i8); 14464v2q15 __builtin_mips_addqh_ph (v2q15, v2q15); 14465v2q15 __builtin_mips_addqh_r_ph (v2q15, v2q15); 14466q31 __builtin_mips_addqh_w (q31, q31); 14467q31 __builtin_mips_addqh_r_w (q31, q31); 14468v2q15 __builtin_mips_subqh_ph (v2q15, v2q15); 14469v2q15 __builtin_mips_subqh_r_ph (v2q15, v2q15); 14470q31 __builtin_mips_subqh_w (q31, q31); 14471q31 __builtin_mips_subqh_r_w (q31, q31); 14472a64 __builtin_mips_dpax_w_ph (a64, v2i16, v2i16); 14473a64 __builtin_mips_dpsx_w_ph (a64, v2i16, v2i16); 14474a64 __builtin_mips_dpaqx_s_w_ph (a64, v2q15, v2q15); 14475a64 __builtin_mips_dpaqx_sa_w_ph (a64, v2q15, v2q15); 14476a64 __builtin_mips_dpsqx_s_w_ph (a64, v2q15, v2q15); 14477a64 __builtin_mips_dpsqx_sa_w_ph (a64, v2q15, v2q15); 14478@end smallexample 14479 14480 14481@node MIPS Paired-Single Support 14482@subsection MIPS Paired-Single Support 14483 14484The MIPS64 architecture includes a number of instructions that 14485operate on pairs of single-precision floating-point values. 14486Each pair is packed into a 64-bit floating-point register, 14487with one element being designated the ``upper half'' and 14488the other being designated the ``lower half''. 14489 14490GCC supports paired-single operations using both the generic 14491vector extensions (@pxref{Vector Extensions}) and a collection of 14492MIPS-specific built-in functions. Both kinds of support are 14493enabled by the @option{-mpaired-single} command-line option. 14494 14495The vector type associated with paired-single values is usually 14496called @code{v2sf}. It can be defined in C as follows: 14497 14498@smallexample 14499typedef float v2sf __attribute__ ((vector_size (8))); 14500@end smallexample 14501 14502@code{v2sf} values are initialized in the same way as aggregates. 14503For example: 14504 14505@smallexample 14506v2sf a = @{1.5, 9.1@}; 14507v2sf b; 14508float e, f; 14509b = (v2sf) @{e, f@}; 14510@end smallexample 14511 14512@emph{Note:} The CPU's endianness determines which value is stored in 14513the upper half of a register and which value is stored in the lower half. 14514On little-endian targets, the first value is the lower one and the second 14515value is the upper one. The opposite order applies to big-endian targets. 14516For example, the code above sets the lower half of @code{a} to 14517@code{1.5} on little-endian targets and @code{9.1} on big-endian targets. 14518 14519@node MIPS Loongson Built-in Functions 14520@subsection MIPS Loongson Built-in Functions 14521 14522GCC provides intrinsics to access the SIMD instructions provided by the 14523ST Microelectronics Loongson-2E and -2F processors. These intrinsics, 14524available after inclusion of the @code{loongson.h} header file, 14525operate on the following 64-bit vector types: 14526 14527@itemize 14528@item @code{uint8x8_t}, a vector of eight unsigned 8-bit integers; 14529@item @code{uint16x4_t}, a vector of four unsigned 16-bit integers; 14530@item @code{uint32x2_t}, a vector of two unsigned 32-bit integers; 14531@item @code{int8x8_t}, a vector of eight signed 8-bit integers; 14532@item @code{int16x4_t}, a vector of four signed 16-bit integers; 14533@item @code{int32x2_t}, a vector of two signed 32-bit integers. 14534@end itemize 14535 14536The intrinsics provided are listed below; each is named after the 14537machine instruction to which it corresponds, with suffixes added as 14538appropriate to distinguish intrinsics that expand to the same machine 14539instruction yet have different argument types. Refer to the architecture 14540documentation for a description of the functionality of each 14541instruction. 14542 14543@smallexample 14544int16x4_t packsswh (int32x2_t s, int32x2_t t); 14545int8x8_t packsshb (int16x4_t s, int16x4_t t); 14546uint8x8_t packushb (uint16x4_t s, uint16x4_t t); 14547uint32x2_t paddw_u (uint32x2_t s, uint32x2_t t); 14548uint16x4_t paddh_u (uint16x4_t s, uint16x4_t t); 14549uint8x8_t paddb_u (uint8x8_t s, uint8x8_t t); 14550int32x2_t paddw_s (int32x2_t s, int32x2_t t); 14551int16x4_t paddh_s (int16x4_t s, int16x4_t t); 14552int8x8_t paddb_s (int8x8_t s, int8x8_t t); 14553uint64_t paddd_u (uint64_t s, uint64_t t); 14554int64_t paddd_s (int64_t s, int64_t t); 14555int16x4_t paddsh (int16x4_t s, int16x4_t t); 14556int8x8_t paddsb (int8x8_t s, int8x8_t t); 14557uint16x4_t paddush (uint16x4_t s, uint16x4_t t); 14558uint8x8_t paddusb (uint8x8_t s, uint8x8_t t); 14559uint64_t pandn_ud (uint64_t s, uint64_t t); 14560uint32x2_t pandn_uw (uint32x2_t s, uint32x2_t t); 14561uint16x4_t pandn_uh (uint16x4_t s, uint16x4_t t); 14562uint8x8_t pandn_ub (uint8x8_t s, uint8x8_t t); 14563int64_t pandn_sd (int64_t s, int64_t t); 14564int32x2_t pandn_sw (int32x2_t s, int32x2_t t); 14565int16x4_t pandn_sh (int16x4_t s, int16x4_t t); 14566int8x8_t pandn_sb (int8x8_t s, int8x8_t t); 14567uint16x4_t pavgh (uint16x4_t s, uint16x4_t t); 14568uint8x8_t pavgb (uint8x8_t s, uint8x8_t t); 14569uint32x2_t pcmpeqw_u (uint32x2_t s, uint32x2_t t); 14570uint16x4_t pcmpeqh_u (uint16x4_t s, uint16x4_t t); 14571uint8x8_t pcmpeqb_u (uint8x8_t s, uint8x8_t t); 14572int32x2_t pcmpeqw_s (int32x2_t s, int32x2_t t); 14573int16x4_t pcmpeqh_s (int16x4_t s, int16x4_t t); 14574int8x8_t pcmpeqb_s (int8x8_t s, int8x8_t t); 14575uint32x2_t pcmpgtw_u (uint32x2_t s, uint32x2_t t); 14576uint16x4_t pcmpgth_u (uint16x4_t s, uint16x4_t t); 14577uint8x8_t pcmpgtb_u (uint8x8_t s, uint8x8_t t); 14578int32x2_t pcmpgtw_s (int32x2_t s, int32x2_t t); 14579int16x4_t pcmpgth_s (int16x4_t s, int16x4_t t); 14580int8x8_t pcmpgtb_s (int8x8_t s, int8x8_t t); 14581uint16x4_t pextrh_u (uint16x4_t s, int field); 14582int16x4_t pextrh_s (int16x4_t s, int field); 14583uint16x4_t pinsrh_0_u (uint16x4_t s, uint16x4_t t); 14584uint16x4_t pinsrh_1_u (uint16x4_t s, uint16x4_t t); 14585uint16x4_t pinsrh_2_u (uint16x4_t s, uint16x4_t t); 14586uint16x4_t pinsrh_3_u (uint16x4_t s, uint16x4_t t); 14587int16x4_t pinsrh_0_s (int16x4_t s, int16x4_t t); 14588int16x4_t pinsrh_1_s (int16x4_t s, int16x4_t t); 14589int16x4_t pinsrh_2_s (int16x4_t s, int16x4_t t); 14590int16x4_t pinsrh_3_s (int16x4_t s, int16x4_t t); 14591int32x2_t pmaddhw (int16x4_t s, int16x4_t t); 14592int16x4_t pmaxsh (int16x4_t s, int16x4_t t); 14593uint8x8_t pmaxub (uint8x8_t s, uint8x8_t t); 14594int16x4_t pminsh (int16x4_t s, int16x4_t t); 14595uint8x8_t pminub (uint8x8_t s, uint8x8_t t); 14596uint8x8_t pmovmskb_u (uint8x8_t s); 14597int8x8_t pmovmskb_s (int8x8_t s); 14598uint16x4_t pmulhuh (uint16x4_t s, uint16x4_t t); 14599int16x4_t pmulhh (int16x4_t s, int16x4_t t); 14600int16x4_t pmullh (int16x4_t s, int16x4_t t); 14601int64_t pmuluw (uint32x2_t s, uint32x2_t t); 14602uint8x8_t pasubub (uint8x8_t s, uint8x8_t t); 14603uint16x4_t biadd (uint8x8_t s); 14604uint16x4_t psadbh (uint8x8_t s, uint8x8_t t); 14605uint16x4_t pshufh_u (uint16x4_t dest, uint16x4_t s, uint8_t order); 14606int16x4_t pshufh_s (int16x4_t dest, int16x4_t s, uint8_t order); 14607uint16x4_t psllh_u (uint16x4_t s, uint8_t amount); 14608int16x4_t psllh_s (int16x4_t s, uint8_t amount); 14609uint32x2_t psllw_u (uint32x2_t s, uint8_t amount); 14610int32x2_t psllw_s (int32x2_t s, uint8_t amount); 14611uint16x4_t psrlh_u (uint16x4_t s, uint8_t amount); 14612int16x4_t psrlh_s (int16x4_t s, uint8_t amount); 14613uint32x2_t psrlw_u (uint32x2_t s, uint8_t amount); 14614int32x2_t psrlw_s (int32x2_t s, uint8_t amount); 14615uint16x4_t psrah_u (uint16x4_t s, uint8_t amount); 14616int16x4_t psrah_s (int16x4_t s, uint8_t amount); 14617uint32x2_t psraw_u (uint32x2_t s, uint8_t amount); 14618int32x2_t psraw_s (int32x2_t s, uint8_t amount); 14619uint32x2_t psubw_u (uint32x2_t s, uint32x2_t t); 14620uint16x4_t psubh_u (uint16x4_t s, uint16x4_t t); 14621uint8x8_t psubb_u (uint8x8_t s, uint8x8_t t); 14622int32x2_t psubw_s (int32x2_t s, int32x2_t t); 14623int16x4_t psubh_s (int16x4_t s, int16x4_t t); 14624int8x8_t psubb_s (int8x8_t s, int8x8_t t); 14625uint64_t psubd_u (uint64_t s, uint64_t t); 14626int64_t psubd_s (int64_t s, int64_t t); 14627int16x4_t psubsh (int16x4_t s, int16x4_t t); 14628int8x8_t psubsb (int8x8_t s, int8x8_t t); 14629uint16x4_t psubush (uint16x4_t s, uint16x4_t t); 14630uint8x8_t psubusb (uint8x8_t s, uint8x8_t t); 14631uint32x2_t punpckhwd_u (uint32x2_t s, uint32x2_t t); 14632uint16x4_t punpckhhw_u (uint16x4_t s, uint16x4_t t); 14633uint8x8_t punpckhbh_u (uint8x8_t s, uint8x8_t t); 14634int32x2_t punpckhwd_s (int32x2_t s, int32x2_t t); 14635int16x4_t punpckhhw_s (int16x4_t s, int16x4_t t); 14636int8x8_t punpckhbh_s (int8x8_t s, int8x8_t t); 14637uint32x2_t punpcklwd_u (uint32x2_t s, uint32x2_t t); 14638uint16x4_t punpcklhw_u (uint16x4_t s, uint16x4_t t); 14639uint8x8_t punpcklbh_u (uint8x8_t s, uint8x8_t t); 14640int32x2_t punpcklwd_s (int32x2_t s, int32x2_t t); 14641int16x4_t punpcklhw_s (int16x4_t s, int16x4_t t); 14642int8x8_t punpcklbh_s (int8x8_t s, int8x8_t t); 14643@end smallexample 14644 14645@menu 14646* Paired-Single Arithmetic:: 14647* Paired-Single Built-in Functions:: 14648* MIPS-3D Built-in Functions:: 14649@end menu 14650 14651@node Paired-Single Arithmetic 14652@subsubsection Paired-Single Arithmetic 14653 14654The table below lists the @code{v2sf} operations for which hardware 14655support exists. @code{a}, @code{b} and @code{c} are @code{v2sf} 14656values and @code{x} is an integral value. 14657 14658@multitable @columnfractions .50 .50 14659@item C code @tab MIPS instruction 14660@item @code{a + b} @tab @code{add.ps} 14661@item @code{a - b} @tab @code{sub.ps} 14662@item @code{-a} @tab @code{neg.ps} 14663@item @code{a * b} @tab @code{mul.ps} 14664@item @code{a * b + c} @tab @code{madd.ps} 14665@item @code{a * b - c} @tab @code{msub.ps} 14666@item @code{-(a * b + c)} @tab @code{nmadd.ps} 14667@item @code{-(a * b - c)} @tab @code{nmsub.ps} 14668@item @code{x ? a : b} @tab @code{movn.ps}/@code{movz.ps} 14669@end multitable 14670 14671Note that the multiply-accumulate instructions can be disabled 14672using the command-line option @code{-mno-fused-madd}. 14673 14674@node Paired-Single Built-in Functions 14675@subsubsection Paired-Single Built-in Functions 14676 14677The following paired-single functions map directly to a particular 14678MIPS instruction. Please refer to the architecture specification 14679for details on what each instruction does. 14680 14681@table @code 14682@item v2sf __builtin_mips_pll_ps (v2sf, v2sf) 14683Pair lower lower (@code{pll.ps}). 14684 14685@item v2sf __builtin_mips_pul_ps (v2sf, v2sf) 14686Pair upper lower (@code{pul.ps}). 14687 14688@item v2sf __builtin_mips_plu_ps (v2sf, v2sf) 14689Pair lower upper (@code{plu.ps}). 14690 14691@item v2sf __builtin_mips_puu_ps (v2sf, v2sf) 14692Pair upper upper (@code{puu.ps}). 14693 14694@item v2sf __builtin_mips_cvt_ps_s (float, float) 14695Convert pair to paired single (@code{cvt.ps.s}). 14696 14697@item float __builtin_mips_cvt_s_pl (v2sf) 14698Convert pair lower to single (@code{cvt.s.pl}). 14699 14700@item float __builtin_mips_cvt_s_pu (v2sf) 14701Convert pair upper to single (@code{cvt.s.pu}). 14702 14703@item v2sf __builtin_mips_abs_ps (v2sf) 14704Absolute value (@code{abs.ps}). 14705 14706@item v2sf __builtin_mips_alnv_ps (v2sf, v2sf, int) 14707Align variable (@code{alnv.ps}). 14708 14709@emph{Note:} The value of the third parameter must be 0 or 4 14710modulo 8, otherwise the result is unpredictable. Please read the 14711instruction description for details. 14712@end table 14713 14714The following multi-instruction functions are also available. 14715In each case, @var{cond} can be any of the 16 floating-point conditions: 14716@code{f}, @code{un}, @code{eq}, @code{ueq}, @code{olt}, @code{ult}, 14717@code{ole}, @code{ule}, @code{sf}, @code{ngle}, @code{seq}, @code{ngl}, 14718@code{lt}, @code{nge}, @code{le} or @code{ngt}. 14719 14720@table @code 14721@item v2sf __builtin_mips_movt_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d}) 14722@itemx v2sf __builtin_mips_movf_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d}) 14723Conditional move based on floating-point comparison (@code{c.@var{cond}.ps}, 14724@code{movt.ps}/@code{movf.ps}). 14725 14726The @code{movt} functions return the value @var{x} computed by: 14727 14728@smallexample 14729c.@var{cond}.ps @var{cc},@var{a},@var{b} 14730mov.ps @var{x},@var{c} 14731movt.ps @var{x},@var{d},@var{cc} 14732@end smallexample 14733 14734The @code{movf} functions are similar but use @code{movf.ps} instead 14735of @code{movt.ps}. 14736 14737@item int __builtin_mips_upper_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}) 14738@itemx int __builtin_mips_lower_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}) 14739Comparison of two paired-single values (@code{c.@var{cond}.ps}, 14740@code{bc1t}/@code{bc1f}). 14741 14742These functions compare @var{a} and @var{b} using @code{c.@var{cond}.ps} 14743and return either the upper or lower half of the result. For example: 14744 14745@smallexample 14746v2sf a, b; 14747if (__builtin_mips_upper_c_eq_ps (a, b)) 14748 upper_halves_are_equal (); 14749else 14750 upper_halves_are_unequal (); 14751 14752if (__builtin_mips_lower_c_eq_ps (a, b)) 14753 lower_halves_are_equal (); 14754else 14755 lower_halves_are_unequal (); 14756@end smallexample 14757@end table 14758 14759@node MIPS-3D Built-in Functions 14760@subsubsection MIPS-3D Built-in Functions 14761 14762The MIPS-3D Application-Specific Extension (ASE) includes additional 14763paired-single instructions that are designed to improve the performance 14764of 3D graphics operations. Support for these instructions is controlled 14765by the @option{-mips3d} command-line option. 14766 14767The functions listed below map directly to a particular MIPS-3D 14768instruction. Please refer to the architecture specification for 14769more details on what each instruction does. 14770 14771@table @code 14772@item v2sf __builtin_mips_addr_ps (v2sf, v2sf) 14773Reduction add (@code{addr.ps}). 14774 14775@item v2sf __builtin_mips_mulr_ps (v2sf, v2sf) 14776Reduction multiply (@code{mulr.ps}). 14777 14778@item v2sf __builtin_mips_cvt_pw_ps (v2sf) 14779Convert paired single to paired word (@code{cvt.pw.ps}). 14780 14781@item v2sf __builtin_mips_cvt_ps_pw (v2sf) 14782Convert paired word to paired single (@code{cvt.ps.pw}). 14783 14784@item float __builtin_mips_recip1_s (float) 14785@itemx double __builtin_mips_recip1_d (double) 14786@itemx v2sf __builtin_mips_recip1_ps (v2sf) 14787Reduced-precision reciprocal (sequence step 1) (@code{recip1.@var{fmt}}). 14788 14789@item float __builtin_mips_recip2_s (float, float) 14790@itemx double __builtin_mips_recip2_d (double, double) 14791@itemx v2sf __builtin_mips_recip2_ps (v2sf, v2sf) 14792Reduced-precision reciprocal (sequence step 2) (@code{recip2.@var{fmt}}). 14793 14794@item float __builtin_mips_rsqrt1_s (float) 14795@itemx double __builtin_mips_rsqrt1_d (double) 14796@itemx v2sf __builtin_mips_rsqrt1_ps (v2sf) 14797Reduced-precision reciprocal square root (sequence step 1) 14798(@code{rsqrt1.@var{fmt}}). 14799 14800@item float __builtin_mips_rsqrt2_s (float, float) 14801@itemx double __builtin_mips_rsqrt2_d (double, double) 14802@itemx v2sf __builtin_mips_rsqrt2_ps (v2sf, v2sf) 14803Reduced-precision reciprocal square root (sequence step 2) 14804(@code{rsqrt2.@var{fmt}}). 14805@end table 14806 14807The following multi-instruction functions are also available. 14808In each case, @var{cond} can be any of the 16 floating-point conditions: 14809@code{f}, @code{un}, @code{eq}, @code{ueq}, @code{olt}, @code{ult}, 14810@code{ole}, @code{ule}, @code{sf}, @code{ngle}, @code{seq}, 14811@code{ngl}, @code{lt}, @code{nge}, @code{le} or @code{ngt}. 14812 14813@table @code 14814@item int __builtin_mips_cabs_@var{cond}_s (float @var{a}, float @var{b}) 14815@itemx int __builtin_mips_cabs_@var{cond}_d (double @var{a}, double @var{b}) 14816Absolute comparison of two scalar values (@code{cabs.@var{cond}.@var{fmt}}, 14817@code{bc1t}/@code{bc1f}). 14818 14819These functions compare @var{a} and @var{b} using @code{cabs.@var{cond}.s} 14820or @code{cabs.@var{cond}.d} and return the result as a boolean value. 14821For example: 14822 14823@smallexample 14824float a, b; 14825if (__builtin_mips_cabs_eq_s (a, b)) 14826 true (); 14827else 14828 false (); 14829@end smallexample 14830 14831@item int __builtin_mips_upper_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}) 14832@itemx int __builtin_mips_lower_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}) 14833Absolute comparison of two paired-single values (@code{cabs.@var{cond}.ps}, 14834@code{bc1t}/@code{bc1f}). 14835 14836These functions compare @var{a} and @var{b} using @code{cabs.@var{cond}.ps} 14837and return either the upper or lower half of the result. For example: 14838 14839@smallexample 14840v2sf a, b; 14841if (__builtin_mips_upper_cabs_eq_ps (a, b)) 14842 upper_halves_are_equal (); 14843else 14844 upper_halves_are_unequal (); 14845 14846if (__builtin_mips_lower_cabs_eq_ps (a, b)) 14847 lower_halves_are_equal (); 14848else 14849 lower_halves_are_unequal (); 14850@end smallexample 14851 14852@item v2sf __builtin_mips_movt_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d}) 14853@itemx v2sf __builtin_mips_movf_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d}) 14854Conditional move based on absolute comparison (@code{cabs.@var{cond}.ps}, 14855@code{movt.ps}/@code{movf.ps}). 14856 14857The @code{movt} functions return the value @var{x} computed by: 14858 14859@smallexample 14860cabs.@var{cond}.ps @var{cc},@var{a},@var{b} 14861mov.ps @var{x},@var{c} 14862movt.ps @var{x},@var{d},@var{cc} 14863@end smallexample 14864 14865The @code{movf} functions are similar but use @code{movf.ps} instead 14866of @code{movt.ps}. 14867 14868@item int __builtin_mips_any_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}) 14869@itemx int __builtin_mips_all_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}) 14870@itemx int __builtin_mips_any_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}) 14871@itemx int __builtin_mips_all_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}) 14872Comparison of two paired-single values 14873(@code{c.@var{cond}.ps}/@code{cabs.@var{cond}.ps}, 14874@code{bc1any2t}/@code{bc1any2f}). 14875 14876These functions compare @var{a} and @var{b} using @code{c.@var{cond}.ps} 14877or @code{cabs.@var{cond}.ps}. The @code{any} forms return true if either 14878result is true and the @code{all} forms return true if both results are true. 14879For example: 14880 14881@smallexample 14882v2sf a, b; 14883if (__builtin_mips_any_c_eq_ps (a, b)) 14884 one_is_true (); 14885else 14886 both_are_false (); 14887 14888if (__builtin_mips_all_c_eq_ps (a, b)) 14889 both_are_true (); 14890else 14891 one_is_false (); 14892@end smallexample 14893 14894@item int __builtin_mips_any_c_@var{cond}_4s (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d}) 14895@itemx int __builtin_mips_all_c_@var{cond}_4s (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d}) 14896@itemx int __builtin_mips_any_cabs_@var{cond}_4s (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d}) 14897@itemx int __builtin_mips_all_cabs_@var{cond}_4s (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d}) 14898Comparison of four paired-single values 14899(@code{c.@var{cond}.ps}/@code{cabs.@var{cond}.ps}, 14900@code{bc1any4t}/@code{bc1any4f}). 14901 14902These functions use @code{c.@var{cond}.ps} or @code{cabs.@var{cond}.ps} 14903to compare @var{a} with @var{b} and to compare @var{c} with @var{d}. 14904The @code{any} forms return true if any of the four results are true 14905and the @code{all} forms return true if all four results are true. 14906For example: 14907 14908@smallexample 14909v2sf a, b, c, d; 14910if (__builtin_mips_any_c_eq_4s (a, b, c, d)) 14911 some_are_true (); 14912else 14913 all_are_false (); 14914 14915if (__builtin_mips_all_c_eq_4s (a, b, c, d)) 14916 all_are_true (); 14917else 14918 some_are_false (); 14919@end smallexample 14920@end table 14921 14922@node MIPS SIMD Architecture (MSA) Support 14923@subsection MIPS SIMD Architecture (MSA) Support 14924 14925@menu 14926* MIPS SIMD Architecture Built-in Functions:: 14927@end menu 14928 14929GCC provides intrinsics to access the SIMD instructions provided by the 14930MSA MIPS SIMD Architecture. The interface is made available by including 14931@code{<msa.h>} and using @option{-mmsa -mhard-float -mfp64 -mnan=2008}. 14932For each @code{__builtin_msa_*}, there is a shortened name of the intrinsic, 14933@code{__msa_*}. 14934 14935MSA implements 128-bit wide vector registers, operating on 8-, 16-, 32- and 1493664-bit integer, 16- and 32-bit fixed-point, or 32- and 64-bit floating point 14937data elements. The following vectors typedefs are included in @code{msa.h}: 14938@itemize 14939@item @code{v16i8}, a vector of sixteen signed 8-bit integers; 14940@item @code{v16u8}, a vector of sixteen unsigned 8-bit integers; 14941@item @code{v8i16}, a vector of eight signed 16-bit integers; 14942@item @code{v8u16}, a vector of eight unsigned 16-bit integers; 14943@item @code{v4i32}, a vector of four signed 32-bit integers; 14944@item @code{v4u32}, a vector of four unsigned 32-bit integers; 14945@item @code{v2i64}, a vector of two signed 64-bit integers; 14946@item @code{v2u64}, a vector of two unsigned 64-bit integers; 14947@item @code{v4f32}, a vector of four 32-bit floats; 14948@item @code{v2f64}, a vector of two 64-bit doubles. 14949@end itemize 14950 14951Instructions and corresponding built-ins may have additional restrictions and/or 14952input/output values manipulated: 14953@itemize 14954@item @code{imm0_1}, an integer literal in range 0 to 1; 14955@item @code{imm0_3}, an integer literal in range 0 to 3; 14956@item @code{imm0_7}, an integer literal in range 0 to 7; 14957@item @code{imm0_15}, an integer literal in range 0 to 15; 14958@item @code{imm0_31}, an integer literal in range 0 to 31; 14959@item @code{imm0_63}, an integer literal in range 0 to 63; 14960@item @code{imm0_255}, an integer literal in range 0 to 255; 14961@item @code{imm_n16_15}, an integer literal in range -16 to 15; 14962@item @code{imm_n512_511}, an integer literal in range -512 to 511; 14963@item @code{imm_n1024_1022}, an integer literal in range -512 to 511 left 14964shifted by 1 bit, i.e., -1024, -1022, @dots{}, 1020, 1022; 14965@item @code{imm_n2048_2044}, an integer literal in range -512 to 511 left 14966shifted by 2 bits, i.e., -2048, -2044, @dots{}, 2040, 2044; 14967@item @code{imm_n4096_4088}, an integer literal in range -512 to 511 left 14968shifted by 3 bits, i.e., -4096, -4088, @dots{}, 4080, 4088; 14969@item @code{imm1_4}, an integer literal in range 1 to 4; 14970@item @code{i32, i64, u32, u64, f32, f64}, defined as follows: 14971@end itemize 14972 14973@smallexample 14974@{ 14975typedef int i32; 14976#if __LONG_MAX__ == __LONG_LONG_MAX__ 14977typedef long i64; 14978#else 14979typedef long long i64; 14980#endif 14981 14982typedef unsigned int u32; 14983#if __LONG_MAX__ == __LONG_LONG_MAX__ 14984typedef unsigned long u64; 14985#else 14986typedef unsigned long long u64; 14987#endif 14988 14989typedef double f64; 14990typedef float f32; 14991@} 14992@end smallexample 14993 14994@node MIPS SIMD Architecture Built-in Functions 14995@subsubsection MIPS SIMD Architecture Built-in Functions 14996 14997The intrinsics provided are listed below; each is named after the 14998machine instruction. 14999 15000@smallexample 15001v16i8 __builtin_msa_add_a_b (v16i8, v16i8); 15002v8i16 __builtin_msa_add_a_h (v8i16, v8i16); 15003v4i32 __builtin_msa_add_a_w (v4i32, v4i32); 15004v2i64 __builtin_msa_add_a_d (v2i64, v2i64); 15005 15006v16i8 __builtin_msa_adds_a_b (v16i8, v16i8); 15007v8i16 __builtin_msa_adds_a_h (v8i16, v8i16); 15008v4i32 __builtin_msa_adds_a_w (v4i32, v4i32); 15009v2i64 __builtin_msa_adds_a_d (v2i64, v2i64); 15010 15011v16i8 __builtin_msa_adds_s_b (v16i8, v16i8); 15012v8i16 __builtin_msa_adds_s_h (v8i16, v8i16); 15013v4i32 __builtin_msa_adds_s_w (v4i32, v4i32); 15014v2i64 __builtin_msa_adds_s_d (v2i64, v2i64); 15015 15016v16u8 __builtin_msa_adds_u_b (v16u8, v16u8); 15017v8u16 __builtin_msa_adds_u_h (v8u16, v8u16); 15018v4u32 __builtin_msa_adds_u_w (v4u32, v4u32); 15019v2u64 __builtin_msa_adds_u_d (v2u64, v2u64); 15020 15021v16i8 __builtin_msa_addv_b (v16i8, v16i8); 15022v8i16 __builtin_msa_addv_h (v8i16, v8i16); 15023v4i32 __builtin_msa_addv_w (v4i32, v4i32); 15024v2i64 __builtin_msa_addv_d (v2i64, v2i64); 15025 15026v16i8 __builtin_msa_addvi_b (v16i8, imm0_31); 15027v8i16 __builtin_msa_addvi_h (v8i16, imm0_31); 15028v4i32 __builtin_msa_addvi_w (v4i32, imm0_31); 15029v2i64 __builtin_msa_addvi_d (v2i64, imm0_31); 15030 15031v16u8 __builtin_msa_and_v (v16u8, v16u8); 15032 15033v16u8 __builtin_msa_andi_b (v16u8, imm0_255); 15034 15035v16i8 __builtin_msa_asub_s_b (v16i8, v16i8); 15036v8i16 __builtin_msa_asub_s_h (v8i16, v8i16); 15037v4i32 __builtin_msa_asub_s_w (v4i32, v4i32); 15038v2i64 __builtin_msa_asub_s_d (v2i64, v2i64); 15039 15040v16u8 __builtin_msa_asub_u_b (v16u8, v16u8); 15041v8u16 __builtin_msa_asub_u_h (v8u16, v8u16); 15042v4u32 __builtin_msa_asub_u_w (v4u32, v4u32); 15043v2u64 __builtin_msa_asub_u_d (v2u64, v2u64); 15044 15045v16i8 __builtin_msa_ave_s_b (v16i8, v16i8); 15046v8i16 __builtin_msa_ave_s_h (v8i16, v8i16); 15047v4i32 __builtin_msa_ave_s_w (v4i32, v4i32); 15048v2i64 __builtin_msa_ave_s_d (v2i64, v2i64); 15049 15050v16u8 __builtin_msa_ave_u_b (v16u8, v16u8); 15051v8u16 __builtin_msa_ave_u_h (v8u16, v8u16); 15052v4u32 __builtin_msa_ave_u_w (v4u32, v4u32); 15053v2u64 __builtin_msa_ave_u_d (v2u64, v2u64); 15054 15055v16i8 __builtin_msa_aver_s_b (v16i8, v16i8); 15056v8i16 __builtin_msa_aver_s_h (v8i16, v8i16); 15057v4i32 __builtin_msa_aver_s_w (v4i32, v4i32); 15058v2i64 __builtin_msa_aver_s_d (v2i64, v2i64); 15059 15060v16u8 __builtin_msa_aver_u_b (v16u8, v16u8); 15061v8u16 __builtin_msa_aver_u_h (v8u16, v8u16); 15062v4u32 __builtin_msa_aver_u_w (v4u32, v4u32); 15063v2u64 __builtin_msa_aver_u_d (v2u64, v2u64); 15064 15065v16u8 __builtin_msa_bclr_b (v16u8, v16u8); 15066v8u16 __builtin_msa_bclr_h (v8u16, v8u16); 15067v4u32 __builtin_msa_bclr_w (v4u32, v4u32); 15068v2u64 __builtin_msa_bclr_d (v2u64, v2u64); 15069 15070v16u8 __builtin_msa_bclri_b (v16u8, imm0_7); 15071v8u16 __builtin_msa_bclri_h (v8u16, imm0_15); 15072v4u32 __builtin_msa_bclri_w (v4u32, imm0_31); 15073v2u64 __builtin_msa_bclri_d (v2u64, imm0_63); 15074 15075v16u8 __builtin_msa_binsl_b (v16u8, v16u8, v16u8); 15076v8u16 __builtin_msa_binsl_h (v8u16, v8u16, v8u16); 15077v4u32 __builtin_msa_binsl_w (v4u32, v4u32, v4u32); 15078v2u64 __builtin_msa_binsl_d (v2u64, v2u64, v2u64); 15079 15080v16u8 __builtin_msa_binsli_b (v16u8, v16u8, imm0_7); 15081v8u16 __builtin_msa_binsli_h (v8u16, v8u16, imm0_15); 15082v4u32 __builtin_msa_binsli_w (v4u32, v4u32, imm0_31); 15083v2u64 __builtin_msa_binsli_d (v2u64, v2u64, imm0_63); 15084 15085v16u8 __builtin_msa_binsr_b (v16u8, v16u8, v16u8); 15086v8u16 __builtin_msa_binsr_h (v8u16, v8u16, v8u16); 15087v4u32 __builtin_msa_binsr_w (v4u32, v4u32, v4u32); 15088v2u64 __builtin_msa_binsr_d (v2u64, v2u64, v2u64); 15089 15090v16u8 __builtin_msa_binsri_b (v16u8, v16u8, imm0_7); 15091v8u16 __builtin_msa_binsri_h (v8u16, v8u16, imm0_15); 15092v4u32 __builtin_msa_binsri_w (v4u32, v4u32, imm0_31); 15093v2u64 __builtin_msa_binsri_d (v2u64, v2u64, imm0_63); 15094 15095v16u8 __builtin_msa_bmnz_v (v16u8, v16u8, v16u8); 15096 15097v16u8 __builtin_msa_bmnzi_b (v16u8, v16u8, imm0_255); 15098 15099v16u8 __builtin_msa_bmz_v (v16u8, v16u8, v16u8); 15100 15101v16u8 __builtin_msa_bmzi_b (v16u8, v16u8, imm0_255); 15102 15103v16u8 __builtin_msa_bneg_b (v16u8, v16u8); 15104v8u16 __builtin_msa_bneg_h (v8u16, v8u16); 15105v4u32 __builtin_msa_bneg_w (v4u32, v4u32); 15106v2u64 __builtin_msa_bneg_d (v2u64, v2u64); 15107 15108v16u8 __builtin_msa_bnegi_b (v16u8, imm0_7); 15109v8u16 __builtin_msa_bnegi_h (v8u16, imm0_15); 15110v4u32 __builtin_msa_bnegi_w (v4u32, imm0_31); 15111v2u64 __builtin_msa_bnegi_d (v2u64, imm0_63); 15112 15113i32 __builtin_msa_bnz_b (v16u8); 15114i32 __builtin_msa_bnz_h (v8u16); 15115i32 __builtin_msa_bnz_w (v4u32); 15116i32 __builtin_msa_bnz_d (v2u64); 15117 15118i32 __builtin_msa_bnz_v (v16u8); 15119 15120v16u8 __builtin_msa_bsel_v (v16u8, v16u8, v16u8); 15121 15122v16u8 __builtin_msa_bseli_b (v16u8, v16u8, imm0_255); 15123 15124v16u8 __builtin_msa_bset_b (v16u8, v16u8); 15125v8u16 __builtin_msa_bset_h (v8u16, v8u16); 15126v4u32 __builtin_msa_bset_w (v4u32, v4u32); 15127v2u64 __builtin_msa_bset_d (v2u64, v2u64); 15128 15129v16u8 __builtin_msa_bseti_b (v16u8, imm0_7); 15130v8u16 __builtin_msa_bseti_h (v8u16, imm0_15); 15131v4u32 __builtin_msa_bseti_w (v4u32, imm0_31); 15132v2u64 __builtin_msa_bseti_d (v2u64, imm0_63); 15133 15134i32 __builtin_msa_bz_b (v16u8); 15135i32 __builtin_msa_bz_h (v8u16); 15136i32 __builtin_msa_bz_w (v4u32); 15137i32 __builtin_msa_bz_d (v2u64); 15138 15139i32 __builtin_msa_bz_v (v16u8); 15140 15141v16i8 __builtin_msa_ceq_b (v16i8, v16i8); 15142v8i16 __builtin_msa_ceq_h (v8i16, v8i16); 15143v4i32 __builtin_msa_ceq_w (v4i32, v4i32); 15144v2i64 __builtin_msa_ceq_d (v2i64, v2i64); 15145 15146v16i8 __builtin_msa_ceqi_b (v16i8, imm_n16_15); 15147v8i16 __builtin_msa_ceqi_h (v8i16, imm_n16_15); 15148v4i32 __builtin_msa_ceqi_w (v4i32, imm_n16_15); 15149v2i64 __builtin_msa_ceqi_d (v2i64, imm_n16_15); 15150 15151i32 __builtin_msa_cfcmsa (imm0_31); 15152 15153v16i8 __builtin_msa_cle_s_b (v16i8, v16i8); 15154v8i16 __builtin_msa_cle_s_h (v8i16, v8i16); 15155v4i32 __builtin_msa_cle_s_w (v4i32, v4i32); 15156v2i64 __builtin_msa_cle_s_d (v2i64, v2i64); 15157 15158v16i8 __builtin_msa_cle_u_b (v16u8, v16u8); 15159v8i16 __builtin_msa_cle_u_h (v8u16, v8u16); 15160v4i32 __builtin_msa_cle_u_w (v4u32, v4u32); 15161v2i64 __builtin_msa_cle_u_d (v2u64, v2u64); 15162 15163v16i8 __builtin_msa_clei_s_b (v16i8, imm_n16_15); 15164v8i16 __builtin_msa_clei_s_h (v8i16, imm_n16_15); 15165v4i32 __builtin_msa_clei_s_w (v4i32, imm_n16_15); 15166v2i64 __builtin_msa_clei_s_d (v2i64, imm_n16_15); 15167 15168v16i8 __builtin_msa_clei_u_b (v16u8, imm0_31); 15169v8i16 __builtin_msa_clei_u_h (v8u16, imm0_31); 15170v4i32 __builtin_msa_clei_u_w (v4u32, imm0_31); 15171v2i64 __builtin_msa_clei_u_d (v2u64, imm0_31); 15172 15173v16i8 __builtin_msa_clt_s_b (v16i8, v16i8); 15174v8i16 __builtin_msa_clt_s_h (v8i16, v8i16); 15175v4i32 __builtin_msa_clt_s_w (v4i32, v4i32); 15176v2i64 __builtin_msa_clt_s_d (v2i64, v2i64); 15177 15178v16i8 __builtin_msa_clt_u_b (v16u8, v16u8); 15179v8i16 __builtin_msa_clt_u_h (v8u16, v8u16); 15180v4i32 __builtin_msa_clt_u_w (v4u32, v4u32); 15181v2i64 __builtin_msa_clt_u_d (v2u64, v2u64); 15182 15183v16i8 __builtin_msa_clti_s_b (v16i8, imm_n16_15); 15184v8i16 __builtin_msa_clti_s_h (v8i16, imm_n16_15); 15185v4i32 __builtin_msa_clti_s_w (v4i32, imm_n16_15); 15186v2i64 __builtin_msa_clti_s_d (v2i64, imm_n16_15); 15187 15188v16i8 __builtin_msa_clti_u_b (v16u8, imm0_31); 15189v8i16 __builtin_msa_clti_u_h (v8u16, imm0_31); 15190v4i32 __builtin_msa_clti_u_w (v4u32, imm0_31); 15191v2i64 __builtin_msa_clti_u_d (v2u64, imm0_31); 15192 15193i32 __builtin_msa_copy_s_b (v16i8, imm0_15); 15194i32 __builtin_msa_copy_s_h (v8i16, imm0_7); 15195i32 __builtin_msa_copy_s_w (v4i32, imm0_3); 15196i64 __builtin_msa_copy_s_d (v2i64, imm0_1); 15197 15198u32 __builtin_msa_copy_u_b (v16i8, imm0_15); 15199u32 __builtin_msa_copy_u_h (v8i16, imm0_7); 15200u32 __builtin_msa_copy_u_w (v4i32, imm0_3); 15201u64 __builtin_msa_copy_u_d (v2i64, imm0_1); 15202 15203void __builtin_msa_ctcmsa (imm0_31, i32); 15204 15205v16i8 __builtin_msa_div_s_b (v16i8, v16i8); 15206v8i16 __builtin_msa_div_s_h (v8i16, v8i16); 15207v4i32 __builtin_msa_div_s_w (v4i32, v4i32); 15208v2i64 __builtin_msa_div_s_d (v2i64, v2i64); 15209 15210v16u8 __builtin_msa_div_u_b (v16u8, v16u8); 15211v8u16 __builtin_msa_div_u_h (v8u16, v8u16); 15212v4u32 __builtin_msa_div_u_w (v4u32, v4u32); 15213v2u64 __builtin_msa_div_u_d (v2u64, v2u64); 15214 15215v8i16 __builtin_msa_dotp_s_h (v16i8, v16i8); 15216v4i32 __builtin_msa_dotp_s_w (v8i16, v8i16); 15217v2i64 __builtin_msa_dotp_s_d (v4i32, v4i32); 15218 15219v8u16 __builtin_msa_dotp_u_h (v16u8, v16u8); 15220v4u32 __builtin_msa_dotp_u_w (v8u16, v8u16); 15221v2u64 __builtin_msa_dotp_u_d (v4u32, v4u32); 15222 15223v8i16 __builtin_msa_dpadd_s_h (v8i16, v16i8, v16i8); 15224v4i32 __builtin_msa_dpadd_s_w (v4i32, v8i16, v8i16); 15225v2i64 __builtin_msa_dpadd_s_d (v2i64, v4i32, v4i32); 15226 15227v8u16 __builtin_msa_dpadd_u_h (v8u16, v16u8, v16u8); 15228v4u32 __builtin_msa_dpadd_u_w (v4u32, v8u16, v8u16); 15229v2u64 __builtin_msa_dpadd_u_d (v2u64, v4u32, v4u32); 15230 15231v8i16 __builtin_msa_dpsub_s_h (v8i16, v16i8, v16i8); 15232v4i32 __builtin_msa_dpsub_s_w (v4i32, v8i16, v8i16); 15233v2i64 __builtin_msa_dpsub_s_d (v2i64, v4i32, v4i32); 15234 15235v8i16 __builtin_msa_dpsub_u_h (v8i16, v16u8, v16u8); 15236v4i32 __builtin_msa_dpsub_u_w (v4i32, v8u16, v8u16); 15237v2i64 __builtin_msa_dpsub_u_d (v2i64, v4u32, v4u32); 15238 15239v4f32 __builtin_msa_fadd_w (v4f32, v4f32); 15240v2f64 __builtin_msa_fadd_d (v2f64, v2f64); 15241 15242v4i32 __builtin_msa_fcaf_w (v4f32, v4f32); 15243v2i64 __builtin_msa_fcaf_d (v2f64, v2f64); 15244 15245v4i32 __builtin_msa_fceq_w (v4f32, v4f32); 15246v2i64 __builtin_msa_fceq_d (v2f64, v2f64); 15247 15248v4i32 __builtin_msa_fclass_w (v4f32); 15249v2i64 __builtin_msa_fclass_d (v2f64); 15250 15251v4i32 __builtin_msa_fcle_w (v4f32, v4f32); 15252v2i64 __builtin_msa_fcle_d (v2f64, v2f64); 15253 15254v4i32 __builtin_msa_fclt_w (v4f32, v4f32); 15255v2i64 __builtin_msa_fclt_d (v2f64, v2f64); 15256 15257v4i32 __builtin_msa_fcne_w (v4f32, v4f32); 15258v2i64 __builtin_msa_fcne_d (v2f64, v2f64); 15259 15260v4i32 __builtin_msa_fcor_w (v4f32, v4f32); 15261v2i64 __builtin_msa_fcor_d (v2f64, v2f64); 15262 15263v4i32 __builtin_msa_fcueq_w (v4f32, v4f32); 15264v2i64 __builtin_msa_fcueq_d (v2f64, v2f64); 15265 15266v4i32 __builtin_msa_fcule_w (v4f32, v4f32); 15267v2i64 __builtin_msa_fcule_d (v2f64, v2f64); 15268 15269v4i32 __builtin_msa_fcult_w (v4f32, v4f32); 15270v2i64 __builtin_msa_fcult_d (v2f64, v2f64); 15271 15272v4i32 __builtin_msa_fcun_w (v4f32, v4f32); 15273v2i64 __builtin_msa_fcun_d (v2f64, v2f64); 15274 15275v4i32 __builtin_msa_fcune_w (v4f32, v4f32); 15276v2i64 __builtin_msa_fcune_d (v2f64, v2f64); 15277 15278v4f32 __builtin_msa_fdiv_w (v4f32, v4f32); 15279v2f64 __builtin_msa_fdiv_d (v2f64, v2f64); 15280 15281v8i16 __builtin_msa_fexdo_h (v4f32, v4f32); 15282v4f32 __builtin_msa_fexdo_w (v2f64, v2f64); 15283 15284v4f32 __builtin_msa_fexp2_w (v4f32, v4i32); 15285v2f64 __builtin_msa_fexp2_d (v2f64, v2i64); 15286 15287v4f32 __builtin_msa_fexupl_w (v8i16); 15288v2f64 __builtin_msa_fexupl_d (v4f32); 15289 15290v4f32 __builtin_msa_fexupr_w (v8i16); 15291v2f64 __builtin_msa_fexupr_d (v4f32); 15292 15293v4f32 __builtin_msa_ffint_s_w (v4i32); 15294v2f64 __builtin_msa_ffint_s_d (v2i64); 15295 15296v4f32 __builtin_msa_ffint_u_w (v4u32); 15297v2f64 __builtin_msa_ffint_u_d (v2u64); 15298 15299v4f32 __builtin_msa_ffql_w (v8i16); 15300v2f64 __builtin_msa_ffql_d (v4i32); 15301 15302v4f32 __builtin_msa_ffqr_w (v8i16); 15303v2f64 __builtin_msa_ffqr_d (v4i32); 15304 15305v16i8 __builtin_msa_fill_b (i32); 15306v8i16 __builtin_msa_fill_h (i32); 15307v4i32 __builtin_msa_fill_w (i32); 15308v2i64 __builtin_msa_fill_d (i64); 15309 15310v4f32 __builtin_msa_flog2_w (v4f32); 15311v2f64 __builtin_msa_flog2_d (v2f64); 15312 15313v4f32 __builtin_msa_fmadd_w (v4f32, v4f32, v4f32); 15314v2f64 __builtin_msa_fmadd_d (v2f64, v2f64, v2f64); 15315 15316v4f32 __builtin_msa_fmax_w (v4f32, v4f32); 15317v2f64 __builtin_msa_fmax_d (v2f64, v2f64); 15318 15319v4f32 __builtin_msa_fmax_a_w (v4f32, v4f32); 15320v2f64 __builtin_msa_fmax_a_d (v2f64, v2f64); 15321 15322v4f32 __builtin_msa_fmin_w (v4f32, v4f32); 15323v2f64 __builtin_msa_fmin_d (v2f64, v2f64); 15324 15325v4f32 __builtin_msa_fmin_a_w (v4f32, v4f32); 15326v2f64 __builtin_msa_fmin_a_d (v2f64, v2f64); 15327 15328v4f32 __builtin_msa_fmsub_w (v4f32, v4f32, v4f32); 15329v2f64 __builtin_msa_fmsub_d (v2f64, v2f64, v2f64); 15330 15331v4f32 __builtin_msa_fmul_w (v4f32, v4f32); 15332v2f64 __builtin_msa_fmul_d (v2f64, v2f64); 15333 15334v4f32 __builtin_msa_frint_w (v4f32); 15335v2f64 __builtin_msa_frint_d (v2f64); 15336 15337v4f32 __builtin_msa_frcp_w (v4f32); 15338v2f64 __builtin_msa_frcp_d (v2f64); 15339 15340v4f32 __builtin_msa_frsqrt_w (v4f32); 15341v2f64 __builtin_msa_frsqrt_d (v2f64); 15342 15343v4i32 __builtin_msa_fsaf_w (v4f32, v4f32); 15344v2i64 __builtin_msa_fsaf_d (v2f64, v2f64); 15345 15346v4i32 __builtin_msa_fseq_w (v4f32, v4f32); 15347v2i64 __builtin_msa_fseq_d (v2f64, v2f64); 15348 15349v4i32 __builtin_msa_fsle_w (v4f32, v4f32); 15350v2i64 __builtin_msa_fsle_d (v2f64, v2f64); 15351 15352v4i32 __builtin_msa_fslt_w (v4f32, v4f32); 15353v2i64 __builtin_msa_fslt_d (v2f64, v2f64); 15354 15355v4i32 __builtin_msa_fsne_w (v4f32, v4f32); 15356v2i64 __builtin_msa_fsne_d (v2f64, v2f64); 15357 15358v4i32 __builtin_msa_fsor_w (v4f32, v4f32); 15359v2i64 __builtin_msa_fsor_d (v2f64, v2f64); 15360 15361v4f32 __builtin_msa_fsqrt_w (v4f32); 15362v2f64 __builtin_msa_fsqrt_d (v2f64); 15363 15364v4f32 __builtin_msa_fsub_w (v4f32, v4f32); 15365v2f64 __builtin_msa_fsub_d (v2f64, v2f64); 15366 15367v4i32 __builtin_msa_fsueq_w (v4f32, v4f32); 15368v2i64 __builtin_msa_fsueq_d (v2f64, v2f64); 15369 15370v4i32 __builtin_msa_fsule_w (v4f32, v4f32); 15371v2i64 __builtin_msa_fsule_d (v2f64, v2f64); 15372 15373v4i32 __builtin_msa_fsult_w (v4f32, v4f32); 15374v2i64 __builtin_msa_fsult_d (v2f64, v2f64); 15375 15376v4i32 __builtin_msa_fsun_w (v4f32, v4f32); 15377v2i64 __builtin_msa_fsun_d (v2f64, v2f64); 15378 15379v4i32 __builtin_msa_fsune_w (v4f32, v4f32); 15380v2i64 __builtin_msa_fsune_d (v2f64, v2f64); 15381 15382v4i32 __builtin_msa_ftint_s_w (v4f32); 15383v2i64 __builtin_msa_ftint_s_d (v2f64); 15384 15385v4u32 __builtin_msa_ftint_u_w (v4f32); 15386v2u64 __builtin_msa_ftint_u_d (v2f64); 15387 15388v8i16 __builtin_msa_ftq_h (v4f32, v4f32); 15389v4i32 __builtin_msa_ftq_w (v2f64, v2f64); 15390 15391v4i32 __builtin_msa_ftrunc_s_w (v4f32); 15392v2i64 __builtin_msa_ftrunc_s_d (v2f64); 15393 15394v4u32 __builtin_msa_ftrunc_u_w (v4f32); 15395v2u64 __builtin_msa_ftrunc_u_d (v2f64); 15396 15397v8i16 __builtin_msa_hadd_s_h (v16i8, v16i8); 15398v4i32 __builtin_msa_hadd_s_w (v8i16, v8i16); 15399v2i64 __builtin_msa_hadd_s_d (v4i32, v4i32); 15400 15401v8u16 __builtin_msa_hadd_u_h (v16u8, v16u8); 15402v4u32 __builtin_msa_hadd_u_w (v8u16, v8u16); 15403v2u64 __builtin_msa_hadd_u_d (v4u32, v4u32); 15404 15405v8i16 __builtin_msa_hsub_s_h (v16i8, v16i8); 15406v4i32 __builtin_msa_hsub_s_w (v8i16, v8i16); 15407v2i64 __builtin_msa_hsub_s_d (v4i32, v4i32); 15408 15409v8i16 __builtin_msa_hsub_u_h (v16u8, v16u8); 15410v4i32 __builtin_msa_hsub_u_w (v8u16, v8u16); 15411v2i64 __builtin_msa_hsub_u_d (v4u32, v4u32); 15412 15413v16i8 __builtin_msa_ilvev_b (v16i8, v16i8); 15414v8i16 __builtin_msa_ilvev_h (v8i16, v8i16); 15415v4i32 __builtin_msa_ilvev_w (v4i32, v4i32); 15416v2i64 __builtin_msa_ilvev_d (v2i64, v2i64); 15417 15418v16i8 __builtin_msa_ilvl_b (v16i8, v16i8); 15419v8i16 __builtin_msa_ilvl_h (v8i16, v8i16); 15420v4i32 __builtin_msa_ilvl_w (v4i32, v4i32); 15421v2i64 __builtin_msa_ilvl_d (v2i64, v2i64); 15422 15423v16i8 __builtin_msa_ilvod_b (v16i8, v16i8); 15424v8i16 __builtin_msa_ilvod_h (v8i16, v8i16); 15425v4i32 __builtin_msa_ilvod_w (v4i32, v4i32); 15426v2i64 __builtin_msa_ilvod_d (v2i64, v2i64); 15427 15428v16i8 __builtin_msa_ilvr_b (v16i8, v16i8); 15429v8i16 __builtin_msa_ilvr_h (v8i16, v8i16); 15430v4i32 __builtin_msa_ilvr_w (v4i32, v4i32); 15431v2i64 __builtin_msa_ilvr_d (v2i64, v2i64); 15432 15433v16i8 __builtin_msa_insert_b (v16i8, imm0_15, i32); 15434v8i16 __builtin_msa_insert_h (v8i16, imm0_7, i32); 15435v4i32 __builtin_msa_insert_w (v4i32, imm0_3, i32); 15436v2i64 __builtin_msa_insert_d (v2i64, imm0_1, i64); 15437 15438v16i8 __builtin_msa_insve_b (v16i8, imm0_15, v16i8); 15439v8i16 __builtin_msa_insve_h (v8i16, imm0_7, v8i16); 15440v4i32 __builtin_msa_insve_w (v4i32, imm0_3, v4i32); 15441v2i64 __builtin_msa_insve_d (v2i64, imm0_1, v2i64); 15442 15443v16i8 __builtin_msa_ld_b (void *, imm_n512_511); 15444v8i16 __builtin_msa_ld_h (void *, imm_n1024_1022); 15445v4i32 __builtin_msa_ld_w (void *, imm_n2048_2044); 15446v2i64 __builtin_msa_ld_d (void *, imm_n4096_4088); 15447 15448v16i8 __builtin_msa_ldi_b (imm_n512_511); 15449v8i16 __builtin_msa_ldi_h (imm_n512_511); 15450v4i32 __builtin_msa_ldi_w (imm_n512_511); 15451v2i64 __builtin_msa_ldi_d (imm_n512_511); 15452 15453v8i16 __builtin_msa_madd_q_h (v8i16, v8i16, v8i16); 15454v4i32 __builtin_msa_madd_q_w (v4i32, v4i32, v4i32); 15455 15456v8i16 __builtin_msa_maddr_q_h (v8i16, v8i16, v8i16); 15457v4i32 __builtin_msa_maddr_q_w (v4i32, v4i32, v4i32); 15458 15459v16i8 __builtin_msa_maddv_b (v16i8, v16i8, v16i8); 15460v8i16 __builtin_msa_maddv_h (v8i16, v8i16, v8i16); 15461v4i32 __builtin_msa_maddv_w (v4i32, v4i32, v4i32); 15462v2i64 __builtin_msa_maddv_d (v2i64, v2i64, v2i64); 15463 15464v16i8 __builtin_msa_max_a_b (v16i8, v16i8); 15465v8i16 __builtin_msa_max_a_h (v8i16, v8i16); 15466v4i32 __builtin_msa_max_a_w (v4i32, v4i32); 15467v2i64 __builtin_msa_max_a_d (v2i64, v2i64); 15468 15469v16i8 __builtin_msa_max_s_b (v16i8, v16i8); 15470v8i16 __builtin_msa_max_s_h (v8i16, v8i16); 15471v4i32 __builtin_msa_max_s_w (v4i32, v4i32); 15472v2i64 __builtin_msa_max_s_d (v2i64, v2i64); 15473 15474v16u8 __builtin_msa_max_u_b (v16u8, v16u8); 15475v8u16 __builtin_msa_max_u_h (v8u16, v8u16); 15476v4u32 __builtin_msa_max_u_w (v4u32, v4u32); 15477v2u64 __builtin_msa_max_u_d (v2u64, v2u64); 15478 15479v16i8 __builtin_msa_maxi_s_b (v16i8, imm_n16_15); 15480v8i16 __builtin_msa_maxi_s_h (v8i16, imm_n16_15); 15481v4i32 __builtin_msa_maxi_s_w (v4i32, imm_n16_15); 15482v2i64 __builtin_msa_maxi_s_d (v2i64, imm_n16_15); 15483 15484v16u8 __builtin_msa_maxi_u_b (v16u8, imm0_31); 15485v8u16 __builtin_msa_maxi_u_h (v8u16, imm0_31); 15486v4u32 __builtin_msa_maxi_u_w (v4u32, imm0_31); 15487v2u64 __builtin_msa_maxi_u_d (v2u64, imm0_31); 15488 15489v16i8 __builtin_msa_min_a_b (v16i8, v16i8); 15490v8i16 __builtin_msa_min_a_h (v8i16, v8i16); 15491v4i32 __builtin_msa_min_a_w (v4i32, v4i32); 15492v2i64 __builtin_msa_min_a_d (v2i64, v2i64); 15493 15494v16i8 __builtin_msa_min_s_b (v16i8, v16i8); 15495v8i16 __builtin_msa_min_s_h (v8i16, v8i16); 15496v4i32 __builtin_msa_min_s_w (v4i32, v4i32); 15497v2i64 __builtin_msa_min_s_d (v2i64, v2i64); 15498 15499v16u8 __builtin_msa_min_u_b (v16u8, v16u8); 15500v8u16 __builtin_msa_min_u_h (v8u16, v8u16); 15501v4u32 __builtin_msa_min_u_w (v4u32, v4u32); 15502v2u64 __builtin_msa_min_u_d (v2u64, v2u64); 15503 15504v16i8 __builtin_msa_mini_s_b (v16i8, imm_n16_15); 15505v8i16 __builtin_msa_mini_s_h (v8i16, imm_n16_15); 15506v4i32 __builtin_msa_mini_s_w (v4i32, imm_n16_15); 15507v2i64 __builtin_msa_mini_s_d (v2i64, imm_n16_15); 15508 15509v16u8 __builtin_msa_mini_u_b (v16u8, imm0_31); 15510v8u16 __builtin_msa_mini_u_h (v8u16, imm0_31); 15511v4u32 __builtin_msa_mini_u_w (v4u32, imm0_31); 15512v2u64 __builtin_msa_mini_u_d (v2u64, imm0_31); 15513 15514v16i8 __builtin_msa_mod_s_b (v16i8, v16i8); 15515v8i16 __builtin_msa_mod_s_h (v8i16, v8i16); 15516v4i32 __builtin_msa_mod_s_w (v4i32, v4i32); 15517v2i64 __builtin_msa_mod_s_d (v2i64, v2i64); 15518 15519v16u8 __builtin_msa_mod_u_b (v16u8, v16u8); 15520v8u16 __builtin_msa_mod_u_h (v8u16, v8u16); 15521v4u32 __builtin_msa_mod_u_w (v4u32, v4u32); 15522v2u64 __builtin_msa_mod_u_d (v2u64, v2u64); 15523 15524v16i8 __builtin_msa_move_v (v16i8); 15525 15526v8i16 __builtin_msa_msub_q_h (v8i16, v8i16, v8i16); 15527v4i32 __builtin_msa_msub_q_w (v4i32, v4i32, v4i32); 15528 15529v8i16 __builtin_msa_msubr_q_h (v8i16, v8i16, v8i16); 15530v4i32 __builtin_msa_msubr_q_w (v4i32, v4i32, v4i32); 15531 15532v16i8 __builtin_msa_msubv_b (v16i8, v16i8, v16i8); 15533v8i16 __builtin_msa_msubv_h (v8i16, v8i16, v8i16); 15534v4i32 __builtin_msa_msubv_w (v4i32, v4i32, v4i32); 15535v2i64 __builtin_msa_msubv_d (v2i64, v2i64, v2i64); 15536 15537v8i16 __builtin_msa_mul_q_h (v8i16, v8i16); 15538v4i32 __builtin_msa_mul_q_w (v4i32, v4i32); 15539 15540v8i16 __builtin_msa_mulr_q_h (v8i16, v8i16); 15541v4i32 __builtin_msa_mulr_q_w (v4i32, v4i32); 15542 15543v16i8 __builtin_msa_mulv_b (v16i8, v16i8); 15544v8i16 __builtin_msa_mulv_h (v8i16, v8i16); 15545v4i32 __builtin_msa_mulv_w (v4i32, v4i32); 15546v2i64 __builtin_msa_mulv_d (v2i64, v2i64); 15547 15548v16i8 __builtin_msa_nloc_b (v16i8); 15549v8i16 __builtin_msa_nloc_h (v8i16); 15550v4i32 __builtin_msa_nloc_w (v4i32); 15551v2i64 __builtin_msa_nloc_d (v2i64); 15552 15553v16i8 __builtin_msa_nlzc_b (v16i8); 15554v8i16 __builtin_msa_nlzc_h (v8i16); 15555v4i32 __builtin_msa_nlzc_w (v4i32); 15556v2i64 __builtin_msa_nlzc_d (v2i64); 15557 15558v16u8 __builtin_msa_nor_v (v16u8, v16u8); 15559 15560v16u8 __builtin_msa_nori_b (v16u8, imm0_255); 15561 15562v16u8 __builtin_msa_or_v (v16u8, v16u8); 15563 15564v16u8 __builtin_msa_ori_b (v16u8, imm0_255); 15565 15566v16i8 __builtin_msa_pckev_b (v16i8, v16i8); 15567v8i16 __builtin_msa_pckev_h (v8i16, v8i16); 15568v4i32 __builtin_msa_pckev_w (v4i32, v4i32); 15569v2i64 __builtin_msa_pckev_d (v2i64, v2i64); 15570 15571v16i8 __builtin_msa_pckod_b (v16i8, v16i8); 15572v8i16 __builtin_msa_pckod_h (v8i16, v8i16); 15573v4i32 __builtin_msa_pckod_w (v4i32, v4i32); 15574v2i64 __builtin_msa_pckod_d (v2i64, v2i64); 15575 15576v16i8 __builtin_msa_pcnt_b (v16i8); 15577v8i16 __builtin_msa_pcnt_h (v8i16); 15578v4i32 __builtin_msa_pcnt_w (v4i32); 15579v2i64 __builtin_msa_pcnt_d (v2i64); 15580 15581v16i8 __builtin_msa_sat_s_b (v16i8, imm0_7); 15582v8i16 __builtin_msa_sat_s_h (v8i16, imm0_15); 15583v4i32 __builtin_msa_sat_s_w (v4i32, imm0_31); 15584v2i64 __builtin_msa_sat_s_d (v2i64, imm0_63); 15585 15586v16u8 __builtin_msa_sat_u_b (v16u8, imm0_7); 15587v8u16 __builtin_msa_sat_u_h (v8u16, imm0_15); 15588v4u32 __builtin_msa_sat_u_w (v4u32, imm0_31); 15589v2u64 __builtin_msa_sat_u_d (v2u64, imm0_63); 15590 15591v16i8 __builtin_msa_shf_b (v16i8, imm0_255); 15592v8i16 __builtin_msa_shf_h (v8i16, imm0_255); 15593v4i32 __builtin_msa_shf_w (v4i32, imm0_255); 15594 15595v16i8 __builtin_msa_sld_b (v16i8, v16i8, i32); 15596v8i16 __builtin_msa_sld_h (v8i16, v8i16, i32); 15597v4i32 __builtin_msa_sld_w (v4i32, v4i32, i32); 15598v2i64 __builtin_msa_sld_d (v2i64, v2i64, i32); 15599 15600v16i8 __builtin_msa_sldi_b (v16i8, v16i8, imm0_15); 15601v8i16 __builtin_msa_sldi_h (v8i16, v8i16, imm0_7); 15602v4i32 __builtin_msa_sldi_w (v4i32, v4i32, imm0_3); 15603v2i64 __builtin_msa_sldi_d (v2i64, v2i64, imm0_1); 15604 15605v16i8 __builtin_msa_sll_b (v16i8, v16i8); 15606v8i16 __builtin_msa_sll_h (v8i16, v8i16); 15607v4i32 __builtin_msa_sll_w (v4i32, v4i32); 15608v2i64 __builtin_msa_sll_d (v2i64, v2i64); 15609 15610v16i8 __builtin_msa_slli_b (v16i8, imm0_7); 15611v8i16 __builtin_msa_slli_h (v8i16, imm0_15); 15612v4i32 __builtin_msa_slli_w (v4i32, imm0_31); 15613v2i64 __builtin_msa_slli_d (v2i64, imm0_63); 15614 15615v16i8 __builtin_msa_splat_b (v16i8, i32); 15616v8i16 __builtin_msa_splat_h (v8i16, i32); 15617v4i32 __builtin_msa_splat_w (v4i32, i32); 15618v2i64 __builtin_msa_splat_d (v2i64, i32); 15619 15620v16i8 __builtin_msa_splati_b (v16i8, imm0_15); 15621v8i16 __builtin_msa_splati_h (v8i16, imm0_7); 15622v4i32 __builtin_msa_splati_w (v4i32, imm0_3); 15623v2i64 __builtin_msa_splati_d (v2i64, imm0_1); 15624 15625v16i8 __builtin_msa_sra_b (v16i8, v16i8); 15626v8i16 __builtin_msa_sra_h (v8i16, v8i16); 15627v4i32 __builtin_msa_sra_w (v4i32, v4i32); 15628v2i64 __builtin_msa_sra_d (v2i64, v2i64); 15629 15630v16i8 __builtin_msa_srai_b (v16i8, imm0_7); 15631v8i16 __builtin_msa_srai_h (v8i16, imm0_15); 15632v4i32 __builtin_msa_srai_w (v4i32, imm0_31); 15633v2i64 __builtin_msa_srai_d (v2i64, imm0_63); 15634 15635v16i8 __builtin_msa_srar_b (v16i8, v16i8); 15636v8i16 __builtin_msa_srar_h (v8i16, v8i16); 15637v4i32 __builtin_msa_srar_w (v4i32, v4i32); 15638v2i64 __builtin_msa_srar_d (v2i64, v2i64); 15639 15640v16i8 __builtin_msa_srari_b (v16i8, imm0_7); 15641v8i16 __builtin_msa_srari_h (v8i16, imm0_15); 15642v4i32 __builtin_msa_srari_w (v4i32, imm0_31); 15643v2i64 __builtin_msa_srari_d (v2i64, imm0_63); 15644 15645v16i8 __builtin_msa_srl_b (v16i8, v16i8); 15646v8i16 __builtin_msa_srl_h (v8i16, v8i16); 15647v4i32 __builtin_msa_srl_w (v4i32, v4i32); 15648v2i64 __builtin_msa_srl_d (v2i64, v2i64); 15649 15650v16i8 __builtin_msa_srli_b (v16i8, imm0_7); 15651v8i16 __builtin_msa_srli_h (v8i16, imm0_15); 15652v4i32 __builtin_msa_srli_w (v4i32, imm0_31); 15653v2i64 __builtin_msa_srli_d (v2i64, imm0_63); 15654 15655v16i8 __builtin_msa_srlr_b (v16i8, v16i8); 15656v8i16 __builtin_msa_srlr_h (v8i16, v8i16); 15657v4i32 __builtin_msa_srlr_w (v4i32, v4i32); 15658v2i64 __builtin_msa_srlr_d (v2i64, v2i64); 15659 15660v16i8 __builtin_msa_srlri_b (v16i8, imm0_7); 15661v8i16 __builtin_msa_srlri_h (v8i16, imm0_15); 15662v4i32 __builtin_msa_srlri_w (v4i32, imm0_31); 15663v2i64 __builtin_msa_srlri_d (v2i64, imm0_63); 15664 15665void __builtin_msa_st_b (v16i8, void *, imm_n512_511); 15666void __builtin_msa_st_h (v8i16, void *, imm_n1024_1022); 15667void __builtin_msa_st_w (v4i32, void *, imm_n2048_2044); 15668void __builtin_msa_st_d (v2i64, void *, imm_n4096_4088); 15669 15670v16i8 __builtin_msa_subs_s_b (v16i8, v16i8); 15671v8i16 __builtin_msa_subs_s_h (v8i16, v8i16); 15672v4i32 __builtin_msa_subs_s_w (v4i32, v4i32); 15673v2i64 __builtin_msa_subs_s_d (v2i64, v2i64); 15674 15675v16u8 __builtin_msa_subs_u_b (v16u8, v16u8); 15676v8u16 __builtin_msa_subs_u_h (v8u16, v8u16); 15677v4u32 __builtin_msa_subs_u_w (v4u32, v4u32); 15678v2u64 __builtin_msa_subs_u_d (v2u64, v2u64); 15679 15680v16u8 __builtin_msa_subsus_u_b (v16u8, v16i8); 15681v8u16 __builtin_msa_subsus_u_h (v8u16, v8i16); 15682v4u32 __builtin_msa_subsus_u_w (v4u32, v4i32); 15683v2u64 __builtin_msa_subsus_u_d (v2u64, v2i64); 15684 15685v16i8 __builtin_msa_subsuu_s_b (v16u8, v16u8); 15686v8i16 __builtin_msa_subsuu_s_h (v8u16, v8u16); 15687v4i32 __builtin_msa_subsuu_s_w (v4u32, v4u32); 15688v2i64 __builtin_msa_subsuu_s_d (v2u64, v2u64); 15689 15690v16i8 __builtin_msa_subv_b (v16i8, v16i8); 15691v8i16 __builtin_msa_subv_h (v8i16, v8i16); 15692v4i32 __builtin_msa_subv_w (v4i32, v4i32); 15693v2i64 __builtin_msa_subv_d (v2i64, v2i64); 15694 15695v16i8 __builtin_msa_subvi_b (v16i8, imm0_31); 15696v8i16 __builtin_msa_subvi_h (v8i16, imm0_31); 15697v4i32 __builtin_msa_subvi_w (v4i32, imm0_31); 15698v2i64 __builtin_msa_subvi_d (v2i64, imm0_31); 15699 15700v16i8 __builtin_msa_vshf_b (v16i8, v16i8, v16i8); 15701v8i16 __builtin_msa_vshf_h (v8i16, v8i16, v8i16); 15702v4i32 __builtin_msa_vshf_w (v4i32, v4i32, v4i32); 15703v2i64 __builtin_msa_vshf_d (v2i64, v2i64, v2i64); 15704 15705v16u8 __builtin_msa_xor_v (v16u8, v16u8); 15706 15707v16u8 __builtin_msa_xori_b (v16u8, imm0_255); 15708@end smallexample 15709 15710@node Other MIPS Built-in Functions 15711@subsection Other MIPS Built-in Functions 15712 15713GCC provides other MIPS-specific built-in functions: 15714 15715@table @code 15716@item void __builtin_mips_cache (int @var{op}, const volatile void *@var{addr}) 15717Insert a @samp{cache} instruction with operands @var{op} and @var{addr}. 15718GCC defines the preprocessor macro @code{___GCC_HAVE_BUILTIN_MIPS_CACHE} 15719when this function is available. 15720 15721@item unsigned int __builtin_mips_get_fcsr (void) 15722@itemx void __builtin_mips_set_fcsr (unsigned int @var{value}) 15723Get and set the contents of the floating-point control and status register 15724(FPU control register 31). These functions are only available in hard-float 15725code but can be called in both MIPS16 and non-MIPS16 contexts. 15726 15727@code{__builtin_mips_set_fcsr} can be used to change any bit of the 15728register except the condition codes, which GCC assumes are preserved. 15729@end table 15730 15731@node MSP430 Built-in Functions 15732@subsection MSP430 Built-in Functions 15733 15734GCC provides a couple of special builtin functions to aid in the 15735writing of interrupt handlers in C. 15736 15737@table @code 15738@item __bic_SR_register_on_exit (int @var{mask}) 15739This clears the indicated bits in the saved copy of the status register 15740currently residing on the stack. This only works inside interrupt 15741handlers and the changes to the status register will only take affect 15742once the handler returns. 15743 15744@item __bis_SR_register_on_exit (int @var{mask}) 15745This sets the indicated bits in the saved copy of the status register 15746currently residing on the stack. This only works inside interrupt 15747handlers and the changes to the status register will only take affect 15748once the handler returns. 15749 15750@item __delay_cycles (long long @var{cycles}) 15751This inserts an instruction sequence that takes exactly @var{cycles} 15752cycles (between 0 and about 17E9) to complete. The inserted sequence 15753may use jumps, loops, or no-ops, and does not interfere with any other 15754instructions. Note that @var{cycles} must be a compile-time constant 15755integer - that is, you must pass a number, not a variable that may be 15756optimized to a constant later. The number of cycles delayed by this 15757builtin is exact. 15758@end table 15759 15760@node NDS32 Built-in Functions 15761@subsection NDS32 Built-in Functions 15762 15763These built-in functions are available for the NDS32 target: 15764 15765@deftypefn {Built-in Function} void __builtin_nds32_isync (int *@var{addr}) 15766Insert an ISYNC instruction into the instruction stream where 15767@var{addr} is an instruction address for serialization. 15768@end deftypefn 15769 15770@deftypefn {Built-in Function} void __builtin_nds32_isb (void) 15771Insert an ISB instruction into the instruction stream. 15772@end deftypefn 15773 15774@deftypefn {Built-in Function} int __builtin_nds32_mfsr (int @var{sr}) 15775Return the content of a system register which is mapped by @var{sr}. 15776@end deftypefn 15777 15778@deftypefn {Built-in Function} int __builtin_nds32_mfusr (int @var{usr}) 15779Return the content of a user space register which is mapped by @var{usr}. 15780@end deftypefn 15781 15782@deftypefn {Built-in Function} void __builtin_nds32_mtsr (int @var{value}, int @var{sr}) 15783Move the @var{value} to a system register which is mapped by @var{sr}. 15784@end deftypefn 15785 15786@deftypefn {Built-in Function} void __builtin_nds32_mtusr (int @var{value}, int @var{usr}) 15787Move the @var{value} to a user space register which is mapped by @var{usr}. 15788@end deftypefn 15789 15790@deftypefn {Built-in Function} void __builtin_nds32_setgie_en (void) 15791Enable global interrupt. 15792@end deftypefn 15793 15794@deftypefn {Built-in Function} void __builtin_nds32_setgie_dis (void) 15795Disable global interrupt. 15796@end deftypefn 15797 15798@node picoChip Built-in Functions 15799@subsection picoChip Built-in Functions 15800 15801GCC provides an interface to selected machine instructions from the 15802picoChip instruction set. 15803 15804@table @code 15805@item int __builtin_sbc (int @var{value}) 15806Sign bit count. Return the number of consecutive bits in @var{value} 15807that have the same value as the sign bit. The result is the number of 15808leading sign bits minus one, giving the number of redundant sign bits in 15809@var{value}. 15810 15811@item int __builtin_byteswap (int @var{value}) 15812Byte swap. Return the result of swapping the upper and lower bytes of 15813@var{value}. 15814 15815@item int __builtin_brev (int @var{value}) 15816Bit reversal. Return the result of reversing the bits in 15817@var{value}. Bit 15 is swapped with bit 0, bit 14 is swapped with bit 1, 15818and so on. 15819 15820@item int __builtin_adds (int @var{x}, int @var{y}) 15821Saturating addition. Return the result of adding @var{x} and @var{y}, 15822storing the value 32767 if the result overflows. 15823 15824@item int __builtin_subs (int @var{x}, int @var{y}) 15825Saturating subtraction. Return the result of subtracting @var{y} from 15826@var{x}, storing the value @minus{}32768 if the result overflows. 15827 15828@item void __builtin_halt (void) 15829Halt. The processor stops execution. This built-in is useful for 15830implementing assertions. 15831 15832@end table 15833 15834@node PowerPC Built-in Functions 15835@subsection PowerPC Built-in Functions 15836 15837The following built-in functions are always available and can be used to 15838check the PowerPC target platform type: 15839 15840@deftypefn {Built-in Function} void __builtin_cpu_init (void) 15841This function is a @code{nop} on the PowerPC platform and is included solely 15842to maintain API compatibility with the x86 builtins. 15843@end deftypefn 15844 15845@deftypefn {Built-in Function} int __builtin_cpu_is (const char *@var{cpuname}) 15846This function returns a value of @code{1} if the run-time CPU is of type 15847@var{cpuname} and returns @code{0} otherwise 15848 15849The @code{__builtin_cpu_is} function requires GLIBC 2.23 or newer 15850which exports the hardware capability bits. GCC defines the macro 15851@code{__BUILTIN_CPU_SUPPORTS__} if the @code{__builtin_cpu_supports} 15852built-in function is fully supported. 15853 15854If GCC was configured to use a GLIBC before 2.23, the built-in 15855function @code{__builtin_cpu_is} always returns a 0 and the compiler 15856issues a warning. 15857 15858The following CPU names can be detected: 15859 15860@table @samp 15861@item power9 15862IBM POWER9 Server CPU. 15863@item power8 15864IBM POWER8 Server CPU. 15865@item power7 15866IBM POWER7 Server CPU. 15867@item power6x 15868IBM POWER6 Server CPU (RAW mode). 15869@item power6 15870IBM POWER6 Server CPU (Architected mode). 15871@item power5+ 15872IBM POWER5+ Server CPU. 15873@item power5 15874IBM POWER5 Server CPU. 15875@item ppc970 15876IBM 970 Server CPU (ie, Apple G5). 15877@item power4 15878IBM POWER4 Server CPU. 15879@item ppca2 15880IBM A2 64-bit Embedded CPU 15881@item ppc476 15882IBM PowerPC 476FP 32-bit Embedded CPU. 15883@item ppc464 15884IBM PowerPC 464 32-bit Embedded CPU. 15885@item ppc440 15886PowerPC 440 32-bit Embedded CPU. 15887@item ppc405 15888PowerPC 405 32-bit Embedded CPU. 15889@item ppc-cell-be 15890IBM PowerPC Cell Broadband Engine Architecture CPU. 15891@end table 15892 15893Here is an example: 15894@smallexample 15895#ifdef __BUILTIN_CPU_SUPPORTS__ 15896 if (__builtin_cpu_is ("power8")) 15897 @{ 15898 do_power8 (); // POWER8 specific implementation. 15899 @} 15900 else 15901#endif 15902 @{ 15903 do_generic (); // Generic implementation. 15904 @} 15905@end smallexample 15906@end deftypefn 15907 15908@deftypefn {Built-in Function} int __builtin_cpu_supports (const char *@var{feature}) 15909This function returns a value of @code{1} if the run-time CPU supports the HWCAP 15910feature @var{feature} and returns @code{0} otherwise. 15911 15912The @code{__builtin_cpu_supports} function requires GLIBC 2.23 or 15913newer which exports the hardware capability bits. GCC defines the 15914macro @code{__BUILTIN_CPU_SUPPORTS__} if the 15915@code{__builtin_cpu_supports} built-in function is fully supported. 15916 15917If GCC was configured to use a GLIBC before 2.23, the built-in 15918function @code{__builtin_cpu_suports} always returns a 0 and the 15919compiler issues a warning. 15920 15921The following features can be 15922detected: 15923 15924@table @samp 15925@item 4xxmac 159264xx CPU has a Multiply Accumulator. 15927@item altivec 15928CPU has a SIMD/Vector Unit. 15929@item arch_2_05 15930CPU supports ISA 2.05 (eg, POWER6) 15931@item arch_2_06 15932CPU supports ISA 2.06 (eg, POWER7) 15933@item arch_2_07 15934CPU supports ISA 2.07 (eg, POWER8) 15935@item arch_3_00 15936CPU supports ISA 3.0 (eg, POWER9) 15937@item archpmu 15938CPU supports the set of compatible performance monitoring events. 15939@item booke 15940CPU supports the Embedded ISA category. 15941@item cellbe 15942CPU has a CELL broadband engine. 15943@item dfp 15944CPU has a decimal floating point unit. 15945@item dscr 15946CPU supports the data stream control register. 15947@item ebb 15948CPU supports event base branching. 15949@item efpdouble 15950CPU has a SPE double precision floating point unit. 15951@item efpsingle 15952CPU has a SPE single precision floating point unit. 15953@item fpu 15954CPU has a floating point unit. 15955@item htm 15956CPU has hardware transaction memory instructions. 15957@item htm-nosc 15958Kernel aborts hardware transactions when a syscall is made. 15959@item ic_snoop 15960CPU supports icache snooping capabilities. 15961@item ieee128 15962CPU supports 128-bit IEEE binary floating point instructions. 15963@item isel 15964CPU supports the integer select instruction. 15965@item mmu 15966CPU has a memory management unit. 15967@item notb 15968CPU does not have a timebase (eg, 601 and 403gx). 15969@item pa6t 15970CPU supports the PA Semi 6T CORE ISA. 15971@item power4 15972CPU supports ISA 2.00 (eg, POWER4) 15973@item power5 15974CPU supports ISA 2.02 (eg, POWER5) 15975@item power5+ 15976CPU supports ISA 2.03 (eg, POWER5+) 15977@item power6x 15978CPU supports ISA 2.05 (eg, POWER6) extended opcodes mffgpr and mftgpr. 15979@item ppc32 15980CPU supports 32-bit mode execution. 15981@item ppc601 15982CPU supports the old POWER ISA (eg, 601) 15983@item ppc64 15984CPU supports 64-bit mode execution. 15985@item ppcle 15986CPU supports a little-endian mode that uses address swizzling. 15987@item smt 15988CPU support simultaneous multi-threading. 15989@item spe 15990CPU has a signal processing extension unit. 15991@item tar 15992CPU supports the target address register. 15993@item true_le 15994CPU supports true little-endian mode. 15995@item ucache 15996CPU has unified I/D cache. 15997@item vcrypto 15998CPU supports the vector cryptography instructions. 15999@item vsx 16000CPU supports the vector-scalar extension. 16001@end table 16002 16003Here is an example: 16004@smallexample 16005#ifdef __BUILTIN_CPU_SUPPORTS__ 16006 if (__builtin_cpu_supports ("fpu")) 16007 @{ 16008 asm("fadd %0,%1,%2" : "=d"(dst) : "d"(src1), "d"(src2)); 16009 @} 16010 else 16011#endif 16012 @{ 16013 dst = __fadd (src1, src2); // Software FP addition function. 16014 @} 16015@end smallexample 16016@end deftypefn 16017 16018These built-in functions are available for the PowerPC family of 16019processors: 16020@smallexample 16021float __builtin_recipdivf (float, float); 16022float __builtin_rsqrtf (float); 16023double __builtin_recipdiv (double, double); 16024double __builtin_rsqrt (double); 16025uint64_t __builtin_ppc_get_timebase (); 16026unsigned long __builtin_ppc_mftb (); 16027double __builtin_unpack_longdouble (long double, int); 16028long double __builtin_pack_longdouble (double, double); 16029__ibm128 __builtin_unpack_ibm128 (__ibm128, int); 16030__ibm128 __builtin_pack_ibm128 (double, double); 16031@end smallexample 16032 16033The @code{vec_rsqrt}, @code{__builtin_rsqrt}, and 16034@code{__builtin_rsqrtf} functions generate multiple instructions to 16035implement the reciprocal sqrt functionality using reciprocal sqrt 16036estimate instructions. 16037 16038The @code{__builtin_recipdiv}, and @code{__builtin_recipdivf} 16039functions generate multiple instructions to implement division using 16040the reciprocal estimate instructions. 16041 16042The @code{__builtin_ppc_get_timebase} and @code{__builtin_ppc_mftb} 16043functions generate instructions to read the Time Base Register. The 16044@code{__builtin_ppc_get_timebase} function may generate multiple 16045instructions and always returns the 64 bits of the Time Base Register. 16046The @code{__builtin_ppc_mftb} function always generates one instruction and 16047returns the Time Base Register value as an unsigned long, throwing away 16048the most significant word on 32-bit environments. 16049 16050The @code{__builtin_unpack_longdouble} function takes a 16051@code{long double} argument and a compile time constant of 0 or 1. If 16052the constant is 0, the first @code{double} within the 16053@code{long double} is returned, otherwise the second @code{double} 16054is returned. The @code{__builtin_unpack_longdouble} function is only 16055availble if @code{long double} uses the IBM extended double 16056representation. 16057 16058The @code{__builtin_pack_longdouble} function takes two @code{double} 16059arguments and returns a @code{long double} value that combines the two 16060arguments. The @code{__builtin_pack_longdouble} function is only 16061availble if @code{long double} uses the IBM extended double 16062representation. 16063 16064The @code{__builtin_unpack_ibm128} function takes a @code{__ibm128} 16065argument and a compile time constant of 0 or 1. If the constant is 0, 16066the first @code{double} within the @code{__ibm128} is returned, 16067otherwise the second @code{double} is returned. 16068 16069The @code{__builtin_pack_ibm128} function takes two @code{double} 16070arguments and returns a @code{__ibm128} value that combines the two 16071arguments. 16072 16073Additional built-in functions are available for the 64-bit PowerPC 16074family of processors, for efficient use of 128-bit floating point 16075(@code{__float128}) values. 16076 16077Previous versions of GCC supported some 'q' builtins for IEEE 128-bit 16078floating point. These functions are now mapped into the equivalent 16079'f128' builtin functions. 16080 16081@smallexample 16082__builtin_fabsq is mapped into __builtin_fabsf128 16083__builtin_copysignq is mapped into __builtin_copysignf128 16084__builtin_infq is mapped into __builtin_inff128 16085__builtin_huge_valq is mapped into __builtin_huge_valf128 16086__builtin_nanq is mapped into __builtin_nanf128 16087__builtin_nansq is mapped into __builtin_nansf128 16088@end smallexample 16089 16090The following built-in functions are available on Linux 64-bit systems 16091that use the ISA 3.0 instruction set. 16092 16093@table @code 16094@item __float128 __builtin_sqrtf128 (__float128) 16095Perform a 128-bit IEEE floating point square root operation. 16096@findex __builtin_sqrtf128 16097 16098@item __float128 __builtin_fmaf128 (__float128, __float128, __float128) 16099Perform a 128-bit IEEE floating point fused multiply and add operation. 16100@findex __builtin_fmaf128 16101 16102@item __float128 __builtin_addf128_round_to_odd (__float128, __float128) 16103Perform a 128-bit IEEE floating point add using round to odd as the 16104rounding mode. 16105@findex __builtin_addf128_round_to_odd 16106 16107@item __float128 __builtin_subf128_round_to_odd (__float128, __float128) 16108Perform a 128-bit IEEE floating point subtract using round to odd as 16109the rounding mode. 16110@findex __builtin_subf128_round_to_odd 16111 16112@item __float128 __builtin_mulf128_round_to_odd (__float128, __float128) 16113Perform a 128-bit IEEE floating point multiply using round to odd as 16114the rounding mode. 16115@findex __builtin_mulf128_round_to_odd 16116 16117@item __float128 __builtin_divf128_round_to_odd (__float128, __float128) 16118Perform a 128-bit IEEE floating point divide using round to odd as 16119the rounding mode. 16120@findex __builtin_divf128_round_to_odd 16121 16122@item __float128 __builtin_sqrtf128_round_to_odd (__float128) 16123Perform a 128-bit IEEE floating point square root using round to odd 16124as the rounding mode. 16125@findex __builtin_sqrtf128_round_to_odd 16126 16127@item __float128 __builtin_fmaf128 (__float128, __float128, __float128) 16128Perform a 128-bit IEEE floating point fused multiply and add operation 16129using round to odd as the rounding mode. 16130@findex __builtin_fmaf128_round_to_odd 16131 16132@item double __builtin_truncf128_round_to_odd (__float128) 16133Convert a 128-bit IEEE floating point value to @code{double} using 16134round to odd as the rounding mode. 16135@findex __builtin_truncf128_round_to_odd 16136@end table 16137 16138The following built-in functions are available for the PowerPC family 16139of processors, starting with ISA 2.05 or later (@option{-mcpu=power6} 16140or @option{-mcmpb}): 16141@smallexample 16142unsigned long long __builtin_cmpb (unsigned long long int, unsigned long long int); 16143unsigned int __builtin_cmpb (unsigned int, unsigned int); 16144@end smallexample 16145 16146The @code{__builtin_cmpb} function 16147performs a byte-wise compare on the contents of its two arguments, 16148returning the result of the byte-wise comparison as the returned 16149value. For each byte comparison, the corresponding byte of the return 16150value holds 0xff if the input bytes are equal and 0 if the input bytes 16151are not equal. If either of the arguments to this built-in function 16152is wider than 32 bits, the function call expands into the form that 16153expects @code{unsigned long long int} arguments 16154which is only available on 64-bit targets. 16155 16156The following built-in functions are available for the PowerPC family 16157of processors, starting with ISA 2.06 or later (@option{-mcpu=power7} 16158or @option{-mpopcntd}): 16159@smallexample 16160long __builtin_bpermd (long, long); 16161int __builtin_divwe (int, int); 16162unsigned int __builtin_divweu (unsigned int, unsigned int); 16163long __builtin_divde (long, long); 16164unsigned long __builtin_divdeu (unsigned long, unsigned long); 16165unsigned int cdtbcd (unsigned int); 16166unsigned int cbcdtd (unsigned int); 16167unsigned int addg6s (unsigned int, unsigned int); 16168void __builtin_rs6000_speculation_barrier (void); 16169@end smallexample 16170 16171The @code{__builtin_divde} and @code{__builtin_divdeu} functions 16172require a 64-bit environment supporting ISA 2.06 or later. 16173 16174The following built-in functions are available for the PowerPC family 16175of processors, starting with ISA 3.0 or later (@option{-mcpu=power9}): 16176@smallexample 16177long long __builtin_darn (void); 16178long long __builtin_darn_raw (void); 16179int __builtin_darn_32 (void); 16180 16181unsigned int scalar_extract_exp (double source); 16182unsigned long long int scalar_extract_exp (__ieee128 source); 16183 16184unsigned long long int scalar_extract_sig (double source); 16185unsigned __int128 scalar_extract_sig (__ieee128 source); 16186 16187double 16188scalar_insert_exp (unsigned long long int significand, unsigned long long int exponent); 16189double 16190scalar_insert_exp (double significand, unsigned long long int exponent); 16191 16192ieee_128 16193scalar_insert_exp (unsigned __int128 significand, unsigned long long int exponent); 16194ieee_128 16195scalar_insert_exp (ieee_128 significand, unsigned long long int exponent); 16196 16197int scalar_cmp_exp_gt (double arg1, double arg2); 16198int scalar_cmp_exp_lt (double arg1, double arg2); 16199int scalar_cmp_exp_eq (double arg1, double arg2); 16200int scalar_cmp_exp_unordered (double arg1, double arg2); 16201 16202bool scalar_test_data_class (float source, const int condition); 16203bool scalar_test_data_class (double source, const int condition); 16204bool scalar_test_data_class (__ieee128 source, const int condition); 16205 16206bool scalar_test_neg (float source); 16207bool scalar_test_neg (double source); 16208bool scalar_test_neg (__ieee128 source); 16209 16210int __builtin_byte_in_set (unsigned char u, unsigned long long set); 16211int __builtin_byte_in_range (unsigned char u, unsigned int range); 16212int __builtin_byte_in_either_range (unsigned char u, unsigned int ranges); 16213 16214int __builtin_dfp_dtstsfi_lt (unsigned int comparison, _Decimal64 value); 16215int __builtin_dfp_dtstsfi_lt (unsigned int comparison, _Decimal128 value); 16216int __builtin_dfp_dtstsfi_lt_dd (unsigned int comparison, _Decimal64 value); 16217int __builtin_dfp_dtstsfi_lt_td (unsigned int comparison, _Decimal128 value); 16218 16219int __builtin_dfp_dtstsfi_gt (unsigned int comparison, _Decimal64 value); 16220int __builtin_dfp_dtstsfi_gt (unsigned int comparison, _Decimal128 value); 16221int __builtin_dfp_dtstsfi_gt_dd (unsigned int comparison, _Decimal64 value); 16222int __builtin_dfp_dtstsfi_gt_td (unsigned int comparison, _Decimal128 value); 16223 16224int __builtin_dfp_dtstsfi_eq (unsigned int comparison, _Decimal64 value); 16225int __builtin_dfp_dtstsfi_eq (unsigned int comparison, _Decimal128 value); 16226int __builtin_dfp_dtstsfi_eq_dd (unsigned int comparison, _Decimal64 value); 16227int __builtin_dfp_dtstsfi_eq_td (unsigned int comparison, _Decimal128 value); 16228 16229int __builtin_dfp_dtstsfi_ov (unsigned int comparison, _Decimal64 value); 16230int __builtin_dfp_dtstsfi_ov (unsigned int comparison, _Decimal128 value); 16231int __builtin_dfp_dtstsfi_ov_dd (unsigned int comparison, _Decimal64 value); 16232int __builtin_dfp_dtstsfi_ov_td (unsigned int comparison, _Decimal128 value); 16233@end smallexample 16234 16235The @code{__builtin_darn} and @code{__builtin_darn_raw} 16236functions require a 1623764-bit environment supporting ISA 3.0 or later. 16238The @code{__builtin_darn} function provides a 64-bit conditioned 16239random number. The @code{__builtin_darn_raw} function provides a 1624064-bit raw random number. The @code{__builtin_darn_32} function 16241provides a 32-bit random number. 16242 16243The @code{scalar_extract_exp} and @code{scalar_extract_sig} 16244functions require a 64-bit environment supporting ISA 3.0 or later. 16245The @code{scalar_extract_exp} and @code{scalar_extract_sig} built-in 16246functions return the significand and the biased exponent value 16247respectively of their @code{source} arguments. 16248When supplied with a 64-bit @code{source} argument, the 16249result returned by @code{scalar_extract_sig} has 16250the @code{0x0010000000000000} bit set if the 16251function's @code{source} argument is in normalized form. 16252Otherwise, this bit is set to 0. 16253When supplied with a 128-bit @code{source} argument, the 16254@code{0x00010000000000000000000000000000} bit of the result is 16255treated similarly. 16256Note that the sign of the significand is not represented in the result 16257returned from the @code{scalar_extract_sig} function. Use the 16258@code{scalar_test_neg} function to test the sign of its @code{double} 16259argument. 16260 16261The @code{scalar_insert_exp} 16262functions require a 64-bit environment supporting ISA 3.0 or later. 16263When supplied with a 64-bit first argument, the 16264@code{scalar_insert_exp} built-in function returns a double-precision 16265floating point value that is constructed by assembling the values of its 16266@code{significand} and @code{exponent} arguments. The sign of the 16267result is copied from the most significant bit of the 16268@code{significand} argument. The significand and exponent components 16269of the result are composed of the least significant 11 bits of the 16270@code{exponent} argument and the least significant 52 bits of the 16271@code{significand} argument respectively. 16272 16273When supplied with a 128-bit first argument, the 16274@code{scalar_insert_exp} built-in function returns a quad-precision 16275ieee floating point value. The sign bit of the result is copied from 16276the most significant bit of the @code{significand} argument. 16277The significand and exponent components of the result are composed of 16278the least significant 15 bits of the @code{exponent} argument and the 16279least significant 112 bits of the @code{significand} argument respectively. 16280 16281The @code{scalar_cmp_exp_gt}, @code{scalar_cmp_exp_lt}, 16282@code{scalar_cmp_exp_eq}, and @code{scalar_cmp_exp_unordered} built-in 16283functions return a non-zero value if @code{arg1} is greater than, less 16284than, equal to, or not comparable to @code{arg2} respectively. The 16285arguments are not comparable if one or the other equals NaN (not a 16286number). 16287 16288The @code{scalar_test_data_class} built-in function returns 1 16289if any of the condition tests enabled by the value of the 16290@code{condition} variable are true, and 0 otherwise. The 16291@code{condition} argument must be a compile-time constant integer with 16292value not exceeding 127. The 16293@code{condition} argument is encoded as a bitmask with each bit 16294enabling the testing of a different condition, as characterized by the 16295following: 16296@smallexample 162970x40 Test for NaN 162980x20 Test for +Infinity 162990x10 Test for -Infinity 163000x08 Test for +Zero 163010x04 Test for -Zero 163020x02 Test for +Denormal 163030x01 Test for -Denormal 16304@end smallexample 16305 16306The @code{scalar_test_neg} built-in function returns 1 if its 16307@code{source} argument holds a negative value, 0 otherwise. 16308 16309The @code{__builtin_byte_in_set} function requires a 1631064-bit environment supporting ISA 3.0 or later. This function returns 16311a non-zero value if and only if its @code{u} argument exactly equals one of 16312the eight bytes contained within its 64-bit @code{set} argument. 16313 16314The @code{__builtin_byte_in_range} and 16315@code{__builtin_byte_in_either_range} require an environment 16316supporting ISA 3.0 or later. For these two functions, the 16317@code{range} argument is encoded as 4 bytes, organized as 16318@code{hi_1:lo_1:hi_2:lo_2}. 16319The @code{__builtin_byte_in_range} function returns a 16320non-zero value if and only if its @code{u} argument is within the 16321range bounded between @code{lo_2} and @code{hi_2} inclusive. 16322The @code{__builtin_byte_in_either_range} function returns non-zero if 16323and only if its @code{u} argument is within either the range bounded 16324between @code{lo_1} and @code{hi_1} inclusive or the range bounded 16325between @code{lo_2} and @code{hi_2} inclusive. 16326 16327The @code{__builtin_dfp_dtstsfi_lt} function returns a non-zero value 16328if and only if the number of signficant digits of its @code{value} argument 16329is less than its @code{comparison} argument. The 16330@code{__builtin_dfp_dtstsfi_lt_dd} and 16331@code{__builtin_dfp_dtstsfi_lt_td} functions behave similarly, but 16332require that the type of the @code{value} argument be 16333@code{__Decimal64} and @code{__Decimal128} respectively. 16334 16335The @code{__builtin_dfp_dtstsfi_gt} function returns a non-zero value 16336if and only if the number of signficant digits of its @code{value} argument 16337is greater than its @code{comparison} argument. The 16338@code{__builtin_dfp_dtstsfi_gt_dd} and 16339@code{__builtin_dfp_dtstsfi_gt_td} functions behave similarly, but 16340require that the type of the @code{value} argument be 16341@code{__Decimal64} and @code{__Decimal128} respectively. 16342 16343The @code{__builtin_dfp_dtstsfi_eq} function returns a non-zero value 16344if and only if the number of signficant digits of its @code{value} argument 16345equals its @code{comparison} argument. The 16346@code{__builtin_dfp_dtstsfi_eq_dd} and 16347@code{__builtin_dfp_dtstsfi_eq_td} functions behave similarly, but 16348require that the type of the @code{value} argument be 16349@code{__Decimal64} and @code{__Decimal128} respectively. 16350 16351The @code{__builtin_dfp_dtstsfi_ov} function returns a non-zero value 16352if and only if its @code{value} argument has an undefined number of 16353significant digits, such as when @code{value} is an encoding of @code{NaN}. 16354The @code{__builtin_dfp_dtstsfi_ov_dd} and 16355@code{__builtin_dfp_dtstsfi_ov_td} functions behave similarly, but 16356require that the type of the @code{value} argument be 16357@code{__Decimal64} and @code{__Decimal128} respectively. 16358 16359The following built-in functions are also available for the PowerPC family 16360of processors, starting with ISA 3.0 or later 16361(@option{-mcpu=power9}). These string functions are described 16362separately in order to group the descriptions closer to the function 16363prototypes: 16364@smallexample 16365int vec_all_nez (vector signed char, vector signed char); 16366int vec_all_nez (vector unsigned char, vector unsigned char); 16367int vec_all_nez (vector signed short, vector signed short); 16368int vec_all_nez (vector unsigned short, vector unsigned short); 16369int vec_all_nez (vector signed int, vector signed int); 16370int vec_all_nez (vector unsigned int, vector unsigned int); 16371 16372int vec_any_eqz (vector signed char, vector signed char); 16373int vec_any_eqz (vector unsigned char, vector unsigned char); 16374int vec_any_eqz (vector signed short, vector signed short); 16375int vec_any_eqz (vector unsigned short, vector unsigned short); 16376int vec_any_eqz (vector signed int, vector signed int); 16377int vec_any_eqz (vector unsigned int, vector unsigned int); 16378 16379vector bool char vec_cmpnez (vector signed char arg1, vector signed char arg2); 16380vector bool char vec_cmpnez (vector unsigned char arg1, vector unsigned char arg2); 16381vector bool short vec_cmpnez (vector signed short arg1, vector signed short arg2); 16382vector bool short vec_cmpnez (vector unsigned short arg1, vector unsigned short arg2); 16383vector bool int vec_cmpnez (vector signed int arg1, vector signed int arg2); 16384vector bool int vec_cmpnez (vector unsigned int, vector unsigned int); 16385 16386vector signed char vec_cnttz (vector signed char); 16387vector unsigned char vec_cnttz (vector unsigned char); 16388vector signed short vec_cnttz (vector signed short); 16389vector unsigned short vec_cnttz (vector unsigned short); 16390vector signed int vec_cnttz (vector signed int); 16391vector unsigned int vec_cnttz (vector unsigned int); 16392vector signed long long vec_cnttz (vector signed long long); 16393vector unsigned long long vec_cnttz (vector unsigned long long); 16394 16395signed int vec_cntlz_lsbb (vector signed char); 16396signed int vec_cntlz_lsbb (vector unsigned char); 16397 16398signed int vec_cnttz_lsbb (vector signed char); 16399signed int vec_cnttz_lsbb (vector unsigned char); 16400 16401unsigned int vec_first_match_index (vector signed char, vector signed char); 16402unsigned int vec_first_match_index (vector unsigned char, 16403 vector unsigned char); 16404unsigned int vec_first_match_index (vector signed int, vector signed int); 16405unsigned int vec_first_match_index (vector unsigned int, vector unsigned int); 16406unsigned int vec_first_match_index (vector signed short, vector signed short); 16407unsigned int vec_first_match_index (vector unsigned short, 16408 vector unsigned short); 16409unsigned int vec_first_match_or_eos_index (vector signed char, 16410 vector signed char); 16411unsigned int vec_first_match_or_eos_index (vector unsigned char, 16412 vector unsigned char); 16413unsigned int vec_first_match_or_eos_index (vector signed int, 16414 vector signed int); 16415unsigned int vec_first_match_or_eos_index (vector unsigned int, 16416 vector unsigned int); 16417unsigned int vec_first_match_or_eos_index (vector signed short, 16418 vector signed short); 16419unsigned int vec_first_match_or_eos_index (vector unsigned short, 16420 vector unsigned short); 16421unsigned int vec_first_mismatch_index (vector signed char, 16422 vector signed char); 16423unsigned int vec_first_mismatch_index (vector unsigned char, 16424 vector unsigned char); 16425unsigned int vec_first_mismatch_index (vector signed int, 16426 vector signed int); 16427unsigned int vec_first_mismatch_index (vector unsigned int, 16428 vector unsigned int); 16429unsigned int vec_first_mismatch_index (vector signed short, 16430 vector signed short); 16431unsigned int vec_first_mismatch_index (vector unsigned short, 16432 vector unsigned short); 16433unsigned int vec_first_mismatch_or_eos_index (vector signed char, 16434 vector signed char); 16435unsigned int vec_first_mismatch_or_eos_index (vector unsigned char, 16436 vector unsigned char); 16437unsigned int vec_first_mismatch_or_eos_index (vector signed int, 16438 vector signed int); 16439unsigned int vec_first_mismatch_or_eos_index (vector unsigned int, 16440 vector unsigned int); 16441unsigned int vec_first_mismatch_or_eos_index (vector signed short, 16442 vector signed short); 16443unsigned int vec_first_mismatch_or_eos_index (vector unsigned short, 16444 vector unsigned short); 16445 16446vector unsigned short vec_pack_to_short_fp32 (vector float, vector float); 16447 16448vector signed char vec_xl_be (signed long long, signed char *); 16449vector unsigned char vec_xl_be (signed long long, unsigned char *); 16450vector signed int vec_xl_be (signed long long, signed int *); 16451vector unsigned int vec_xl_be (signed long long, unsigned int *); 16452vector signed __int128 vec_xl_be (signed long long, signed __int128 *); 16453vector unsigned __int128 vec_xl_be (signed long long, unsigned __int128 *); 16454vector signed long long vec_xl_be (signed long long, signed long long *); 16455vector unsigned long long vec_xl_be (signed long long, unsigned long long *); 16456vector signed short vec_xl_be (signed long long, signed short *); 16457vector unsigned short vec_xl_be (signed long long, unsigned short *); 16458vector double vec_xl_be (signed long long, double *); 16459vector float vec_xl_be (signed long long, float *); 16460 16461vector signed char vec_xl_len (signed char *addr, size_t len); 16462vector unsigned char vec_xl_len (unsigned char *addr, size_t len); 16463vector signed int vec_xl_len (signed int *addr, size_t len); 16464vector unsigned int vec_xl_len (unsigned int *addr, size_t len); 16465vector signed __int128 vec_xl_len (signed __int128 *addr, size_t len); 16466vector unsigned __int128 vec_xl_len (unsigned __int128 *addr, size_t len); 16467vector signed long long vec_xl_len (signed long long *addr, size_t len); 16468vector unsigned long long vec_xl_len (unsigned long long *addr, size_t len); 16469vector signed short vec_xl_len (signed short *addr, size_t len); 16470vector unsigned short vec_xl_len (unsigned short *addr, size_t len); 16471vector double vec_xl_len (double *addr, size_t len); 16472vector float vec_xl_len (float *addr, size_t len); 16473 16474vector unsigned char vec_xl_len_r (unsigned char *addr, size_t len); 16475 16476void vec_xst_len (vector signed char data, signed char *addr, size_t len); 16477void vec_xst_len (vector unsigned char data, unsigned char *addr, size_t len); 16478void vec_xst_len (vector signed int data, signed int *addr, size_t len); 16479void vec_xst_len (vector unsigned int data, unsigned int *addr, size_t len); 16480void vec_xst_len (vector unsigned __int128 data, unsigned __int128 *addr, size_t len); 16481void vec_xst_len (vector signed long long data, signed long long *addr, size_t len); 16482void vec_xst_len (vector unsigned long long data, unsigned long long *addr, size_t len); 16483void vec_xst_len (vector signed short data, signed short *addr, size_t len); 16484void vec_xst_len (vector unsigned short data, unsigned short *addr, size_t len); 16485void vec_xst_len (vector signed __int128 data, signed __int128 *addr, size_t len); 16486void vec_xst_len (vector double data, double *addr, size_t len); 16487void vec_xst_len (vector float data, float *addr, size_t len); 16488 16489void vec_xst_len_r (vector unsigned char data, unsigned char *addr, size_t len); 16490 16491signed char vec_xlx (unsigned int index, vector signed char data); 16492unsigned char vec_xlx (unsigned int index, vector unsigned char data); 16493signed short vec_xlx (unsigned int index, vector signed short data); 16494unsigned short vec_xlx (unsigned int index, vector unsigned short data); 16495signed int vec_xlx (unsigned int index, vector signed int data); 16496unsigned int vec_xlx (unsigned int index, vector unsigned int data); 16497float vec_xlx (unsigned int index, vector float data); 16498 16499signed char vec_xrx (unsigned int index, vector signed char data); 16500unsigned char vec_xrx (unsigned int index, vector unsigned char data); 16501signed short vec_xrx (unsigned int index, vector signed short data); 16502unsigned short vec_xrx (unsigned int index, vector unsigned short data); 16503signed int vec_xrx (unsigned int index, vector signed int data); 16504unsigned int vec_xrx (unsigned int index, vector unsigned int data); 16505float vec_xrx (unsigned int index, vector float data); 16506@end smallexample 16507 16508The @code{vec_all_nez}, @code{vec_any_eqz}, and @code{vec_cmpnez} 16509perform pairwise comparisons between the elements at the same 16510positions within their two vector arguments. 16511The @code{vec_all_nez} function returns a 16512non-zero value if and only if all pairwise comparisons are not 16513equal and no element of either vector argument contains a zero. 16514The @code{vec_any_eqz} function returns a 16515non-zero value if and only if at least one pairwise comparison is equal 16516or if at least one element of either vector argument contains a zero. 16517The @code{vec_cmpnez} function returns a vector of the same type as 16518its two arguments, within which each element consists of all ones to 16519denote that either the corresponding elements of the incoming arguments are 16520not equal or that at least one of the corresponding elements contains 16521zero. Otherwise, the element of the returned vector contains all zeros. 16522 16523The @code{vec_cntlz_lsbb} function returns the count of the number of 16524consecutive leading byte elements (starting from position 0 within the 16525supplied vector argument) for which the least-significant bit 16526equals zero. The @code{vec_cnttz_lsbb} function returns the count of 16527the number of consecutive trailing byte elements (starting from 16528position 15 and counting backwards within the supplied vector 16529argument) for which the least-significant bit equals zero. 16530 16531The @code{vec_xl_len} and @code{vec_xst_len} functions require a 1653264-bit environment supporting ISA 3.0 or later. The @code{vec_xl_len} 16533function loads a variable length vector from memory. The 16534@code{vec_xst_len} function stores a variable length vector to memory. 16535With both the @code{vec_xl_len} and @code{vec_xst_len} functions, the 16536@code{addr} argument represents the memory address to or from which 16537data will be transferred, and the 16538@code{len} argument represents the number of bytes to be 16539transferred, as computed by the C expression @code{min((len & 0xff), 16)}. 16540If this expression's value is not a multiple of the vector element's 16541size, the behavior of this function is undefined. 16542In the case that the underlying computer is configured to run in 16543big-endian mode, the data transfer moves bytes 0 to @code{(len - 1)} of 16544the corresponding vector. In little-endian mode, the data transfer 16545moves bytes @code{(16 - len)} to @code{15} of the corresponding 16546vector. For the load function, any bytes of the result vector that 16547are not loaded from memory are set to zero. 16548The value of the @code{addr} argument need not be aligned on a 16549multiple of the vector's element size. 16550 16551The @code{vec_xlx} and @code{vec_xrx} functions extract the single 16552element selected by the @code{index} argument from the vector 16553represented by the @code{data} argument. The @code{index} argument 16554always specifies a byte offset, regardless of the size of the vector 16555element. With @code{vec_xlx}, @code{index} is the offset of the first 16556byte of the element to be extracted. With @code{vec_xrx}, @code{index} 16557represents the last byte of the element to be extracted, measured 16558from the right end of the vector. In other words, the last byte of 16559the element to be extracted is found at position @code{(15 - index)}. 16560There is no requirement that @code{index} be a multiple of the vector 16561element size. However, if the size of the vector element added to 16562@code{index} is greater than 15, the content of the returned value is 16563undefined. 16564 16565The following built-in functions are available for the PowerPC family 16566of processors when hardware decimal floating point 16567(@option{-mhard-dfp}) is available: 16568@smallexample 16569long long __builtin_dxex (_Decimal64); 16570long long __builtin_dxexq (_Decimal128); 16571_Decimal64 __builtin_ddedpd (int, _Decimal64); 16572_Decimal128 __builtin_ddedpdq (int, _Decimal128); 16573_Decimal64 __builtin_denbcd (int, _Decimal64); 16574_Decimal128 __builtin_denbcdq (int, _Decimal128); 16575_Decimal64 __builtin_diex (long long, _Decimal64); 16576_Decimal128 _builtin_diexq (long long, _Decimal128); 16577_Decimal64 __builtin_dscli (_Decimal64, int); 16578_Decimal128 __builtin_dscliq (_Decimal128, int); 16579_Decimal64 __builtin_dscri (_Decimal64, int); 16580_Decimal128 __builtin_dscriq (_Decimal128, int); 16581unsigned long long __builtin_unpack_dec128 (_Decimal128, int); 16582_Decimal128 __builtin_pack_dec128 (unsigned long long, unsigned long long); 16583@end smallexample 16584 16585The following built-in functions are available for the PowerPC family 16586of processors when the Vector Scalar (vsx) instruction set is 16587available: 16588@smallexample 16589unsigned long long __builtin_unpack_vector_int128 (vector __int128_t, int); 16590vector __int128_t __builtin_pack_vector_int128 (unsigned long long, 16591 unsigned long long); 16592@end smallexample 16593 16594@node PowerPC AltiVec/VSX Built-in Functions 16595@subsection PowerPC AltiVec Built-in Functions 16596 16597GCC provides an interface for the PowerPC family of processors to access 16598the AltiVec operations described in Motorola's AltiVec Programming 16599Interface Manual. The interface is made available by including 16600@code{<altivec.h>} and using @option{-maltivec} and 16601@option{-mabi=altivec}. The interface supports the following vector 16602types. 16603 16604@smallexample 16605vector unsigned char 16606vector signed char 16607vector bool char 16608 16609vector unsigned short 16610vector signed short 16611vector bool short 16612vector pixel 16613 16614vector unsigned int 16615vector signed int 16616vector bool int 16617vector float 16618@end smallexample 16619 16620If @option{-mvsx} is used the following additional vector types are 16621implemented. 16622 16623@smallexample 16624vector unsigned long 16625vector signed long 16626vector double 16627@end smallexample 16628 16629The long types are only implemented for 64-bit code generation, and 16630the long type is only used in the floating point/integer conversion 16631instructions. 16632 16633GCC's implementation of the high-level language interface available from 16634C and C++ code differs from Motorola's documentation in several ways. 16635 16636@itemize @bullet 16637 16638@item 16639A vector constant is a list of constant expressions within curly braces. 16640 16641@item 16642A vector initializer requires no cast if the vector constant is of the 16643same type as the variable it is initializing. 16644 16645@item 16646If @code{signed} or @code{unsigned} is omitted, the signedness of the 16647vector type is the default signedness of the base type. The default 16648varies depending on the operating system, so a portable program should 16649always specify the signedness. 16650 16651@item 16652Compiling with @option{-maltivec} adds keywords @code{__vector}, 16653@code{vector}, @code{__pixel}, @code{pixel}, @code{__bool} and 16654@code{bool}. When compiling ISO C, the context-sensitive substitution 16655of the keywords @code{vector}, @code{pixel} and @code{bool} is 16656disabled. To use them, you must include @code{<altivec.h>} instead. 16657 16658@item 16659GCC allows using a @code{typedef} name as the type specifier for a 16660vector type, but only under the following circumstances: 16661 16662@itemize @bullet 16663 16664@item 16665When using @code{__vector} instead of @code{vector}; for example, 16666 16667@smallexample 16668typedef signed short int16; 16669__vector int16 data; 16670@end smallexample 16671 16672@item 16673When using @code{vector} in keyword-and-predefine mode; for example, 16674 16675@smallexample 16676typedef signed short int16; 16677vector int16 data; 16678@end smallexample 16679 16680Note that keyword-and-predefine mode is enabled by disabling GNU 16681extensions (e.g., by using @code{-std=c11}) and including 16682@code{<altivec.h>}. 16683@end itemize 16684 16685@item 16686For C, overloaded functions are implemented with macros so the following 16687does not work: 16688 16689@smallexample 16690 vec_add ((vector signed int)@{1, 2, 3, 4@}, foo); 16691@end smallexample 16692 16693@noindent 16694Since @code{vec_add} is a macro, the vector constant in the example 16695is treated as four separate arguments. Wrap the entire argument in 16696parentheses for this to work. 16697@end itemize 16698 16699@emph{Note:} Only the @code{<altivec.h>} interface is supported. 16700Internally, GCC uses built-in functions to achieve the functionality in 16701the aforementioned header file, but they are not supported and are 16702subject to change without notice. 16703 16704GCC complies with the OpenPOWER 64-Bit ELF V2 ABI Specification, 16705which may be found at 16706@uref{http://openpowerfoundation.org/wp-content/uploads/resources/leabi-prd/content/index.html}. 16707Appendix A of this document lists the vector API interfaces that must be 16708provided by compliant compilers. Programmers should preferentially use 16709the interfaces described therein. However, historically GCC has provided 16710additional interfaces for access to vector instructions. These are 16711briefly described below. 16712 16713The following interfaces are supported for the generic and specific 16714AltiVec operations and the AltiVec predicates. In cases where there 16715is a direct mapping between generic and specific operations, only the 16716generic names are shown here, although the specific operations can also 16717be used. 16718 16719Arguments that are documented as @code{const int} require literal 16720integral values within the range required for that operation. 16721 16722@smallexample 16723vector signed char vec_abs (vector signed char); 16724vector signed short vec_abs (vector signed short); 16725vector signed int vec_abs (vector signed int); 16726vector float vec_abs (vector float); 16727 16728vector signed char vec_abss (vector signed char); 16729vector signed short vec_abss (vector signed short); 16730vector signed int vec_abss (vector signed int); 16731 16732vector signed char vec_add (vector bool char, vector signed char); 16733vector signed char vec_add (vector signed char, vector bool char); 16734vector signed char vec_add (vector signed char, vector signed char); 16735vector unsigned char vec_add (vector bool char, vector unsigned char); 16736vector unsigned char vec_add (vector unsigned char, vector bool char); 16737vector unsigned char vec_add (vector unsigned char, 16738 vector unsigned char); 16739vector signed short vec_add (vector bool short, vector signed short); 16740vector signed short vec_add (vector signed short, vector bool short); 16741vector signed short vec_add (vector signed short, vector signed short); 16742vector unsigned short vec_add (vector bool short, 16743 vector unsigned short); 16744vector unsigned short vec_add (vector unsigned short, 16745 vector bool short); 16746vector unsigned short vec_add (vector unsigned short, 16747 vector unsigned short); 16748vector signed int vec_add (vector bool int, vector signed int); 16749vector signed int vec_add (vector signed int, vector bool int); 16750vector signed int vec_add (vector signed int, vector signed int); 16751vector unsigned int vec_add (vector bool int, vector unsigned int); 16752vector unsigned int vec_add (vector unsigned int, vector bool int); 16753vector unsigned int vec_add (vector unsigned int, vector unsigned int); 16754vector float vec_add (vector float, vector float); 16755 16756vector float vec_vaddfp (vector float, vector float); 16757 16758vector signed int vec_vadduwm (vector bool int, vector signed int); 16759vector signed int vec_vadduwm (vector signed int, vector bool int); 16760vector signed int vec_vadduwm (vector signed int, vector signed int); 16761vector unsigned int vec_vadduwm (vector bool int, vector unsigned int); 16762vector unsigned int vec_vadduwm (vector unsigned int, vector bool int); 16763vector unsigned int vec_vadduwm (vector unsigned int, 16764 vector unsigned int); 16765 16766vector signed short vec_vadduhm (vector bool short, 16767 vector signed short); 16768vector signed short vec_vadduhm (vector signed short, 16769 vector bool short); 16770vector signed short vec_vadduhm (vector signed short, 16771 vector signed short); 16772vector unsigned short vec_vadduhm (vector bool short, 16773 vector unsigned short); 16774vector unsigned short vec_vadduhm (vector unsigned short, 16775 vector bool short); 16776vector unsigned short vec_vadduhm (vector unsigned short, 16777 vector unsigned short); 16778 16779vector signed char vec_vaddubm (vector bool char, vector signed char); 16780vector signed char vec_vaddubm (vector signed char, vector bool char); 16781vector signed char vec_vaddubm (vector signed char, vector signed char); 16782vector unsigned char vec_vaddubm (vector bool char, 16783 vector unsigned char); 16784vector unsigned char vec_vaddubm (vector unsigned char, 16785 vector bool char); 16786vector unsigned char vec_vaddubm (vector unsigned char, 16787 vector unsigned char); 16788 16789vector unsigned int vec_addc (vector unsigned int, vector unsigned int); 16790 16791vector unsigned char vec_adds (vector bool char, vector unsigned char); 16792vector unsigned char vec_adds (vector unsigned char, vector bool char); 16793vector unsigned char vec_adds (vector unsigned char, 16794 vector unsigned char); 16795vector signed char vec_adds (vector bool char, vector signed char); 16796vector signed char vec_adds (vector signed char, vector bool char); 16797vector signed char vec_adds (vector signed char, vector signed char); 16798vector unsigned short vec_adds (vector bool short, 16799 vector unsigned short); 16800vector unsigned short vec_adds (vector unsigned short, 16801 vector bool short); 16802vector unsigned short vec_adds (vector unsigned short, 16803 vector unsigned short); 16804vector signed short vec_adds (vector bool short, vector signed short); 16805vector signed short vec_adds (vector signed short, vector bool short); 16806vector signed short vec_adds (vector signed short, vector signed short); 16807vector unsigned int vec_adds (vector bool int, vector unsigned int); 16808vector unsigned int vec_adds (vector unsigned int, vector bool int); 16809vector unsigned int vec_adds (vector unsigned int, vector unsigned int); 16810vector signed int vec_adds (vector bool int, vector signed int); 16811vector signed int vec_adds (vector signed int, vector bool int); 16812vector signed int vec_adds (vector signed int, vector signed int); 16813 16814vector signed int vec_vaddsws (vector bool int, vector signed int); 16815vector signed int vec_vaddsws (vector signed int, vector bool int); 16816vector signed int vec_vaddsws (vector signed int, vector signed int); 16817 16818vector unsigned int vec_vadduws (vector bool int, vector unsigned int); 16819vector unsigned int vec_vadduws (vector unsigned int, vector bool int); 16820vector unsigned int vec_vadduws (vector unsigned int, 16821 vector unsigned int); 16822 16823vector signed short vec_vaddshs (vector bool short, 16824 vector signed short); 16825vector signed short vec_vaddshs (vector signed short, 16826 vector bool short); 16827vector signed short vec_vaddshs (vector signed short, 16828 vector signed short); 16829 16830vector unsigned short vec_vadduhs (vector bool short, 16831 vector unsigned short); 16832vector unsigned short vec_vadduhs (vector unsigned short, 16833 vector bool short); 16834vector unsigned short vec_vadduhs (vector unsigned short, 16835 vector unsigned short); 16836 16837vector signed char vec_vaddsbs (vector bool char, vector signed char); 16838vector signed char vec_vaddsbs (vector signed char, vector bool char); 16839vector signed char vec_vaddsbs (vector signed char, vector signed char); 16840 16841vector unsigned char vec_vaddubs (vector bool char, 16842 vector unsigned char); 16843vector unsigned char vec_vaddubs (vector unsigned char, 16844 vector bool char); 16845vector unsigned char vec_vaddubs (vector unsigned char, 16846 vector unsigned char); 16847 16848vector float vec_and (vector float, vector float); 16849vector float vec_and (vector float, vector bool int); 16850vector float vec_and (vector bool int, vector float); 16851vector bool long long vec_and (vector bool long long int, 16852 vector bool long long); 16853vector bool int vec_and (vector bool int, vector bool int); 16854vector signed int vec_and (vector bool int, vector signed int); 16855vector signed int vec_and (vector signed int, vector bool int); 16856vector signed int vec_and (vector signed int, vector signed int); 16857vector unsigned int vec_and (vector bool int, vector unsigned int); 16858vector unsigned int vec_and (vector unsigned int, vector bool int); 16859vector unsigned int vec_and (vector unsigned int, vector unsigned int); 16860vector bool short vec_and (vector bool short, vector bool short); 16861vector signed short vec_and (vector bool short, vector signed short); 16862vector signed short vec_and (vector signed short, vector bool short); 16863vector signed short vec_and (vector signed short, vector signed short); 16864vector unsigned short vec_and (vector bool short, 16865 vector unsigned short); 16866vector unsigned short vec_and (vector unsigned short, 16867 vector bool short); 16868vector unsigned short vec_and (vector unsigned short, 16869 vector unsigned short); 16870vector signed char vec_and (vector bool char, vector signed char); 16871vector bool char vec_and (vector bool char, vector bool char); 16872vector signed char vec_and (vector signed char, vector bool char); 16873vector signed char vec_and (vector signed char, vector signed char); 16874vector unsigned char vec_and (vector bool char, vector unsigned char); 16875vector unsigned char vec_and (vector unsigned char, vector bool char); 16876vector unsigned char vec_and (vector unsigned char, 16877 vector unsigned char); 16878 16879vector float vec_andc (vector float, vector float); 16880vector float vec_andc (vector float, vector bool int); 16881vector float vec_andc (vector bool int, vector float); 16882vector bool int vec_andc (vector bool int, vector bool int); 16883vector signed int vec_andc (vector bool int, vector signed int); 16884vector signed int vec_andc (vector signed int, vector bool int); 16885vector signed int vec_andc (vector signed int, vector signed int); 16886vector unsigned int vec_andc (vector bool int, vector unsigned int); 16887vector unsigned int vec_andc (vector unsigned int, vector bool int); 16888vector unsigned int vec_andc (vector unsigned int, vector unsigned int); 16889vector bool short vec_andc (vector bool short, vector bool short); 16890vector signed short vec_andc (vector bool short, vector signed short); 16891vector signed short vec_andc (vector signed short, vector bool short); 16892vector signed short vec_andc (vector signed short, vector signed short); 16893vector unsigned short vec_andc (vector bool short, 16894 vector unsigned short); 16895vector unsigned short vec_andc (vector unsigned short, 16896 vector bool short); 16897vector unsigned short vec_andc (vector unsigned short, 16898 vector unsigned short); 16899vector signed char vec_andc (vector bool char, vector signed char); 16900vector bool char vec_andc (vector bool char, vector bool char); 16901vector signed char vec_andc (vector signed char, vector bool char); 16902vector signed char vec_andc (vector signed char, vector signed char); 16903vector unsigned char vec_andc (vector bool char, vector unsigned char); 16904vector unsigned char vec_andc (vector unsigned char, vector bool char); 16905vector unsigned char vec_andc (vector unsigned char, 16906 vector unsigned char); 16907 16908vector unsigned char vec_avg (vector unsigned char, 16909 vector unsigned char); 16910vector signed char vec_avg (vector signed char, vector signed char); 16911vector unsigned short vec_avg (vector unsigned short, 16912 vector unsigned short); 16913vector signed short vec_avg (vector signed short, vector signed short); 16914vector unsigned int vec_avg (vector unsigned int, vector unsigned int); 16915vector signed int vec_avg (vector signed int, vector signed int); 16916 16917vector signed int vec_vavgsw (vector signed int, vector signed int); 16918 16919vector unsigned int vec_vavguw (vector unsigned int, 16920 vector unsigned int); 16921 16922vector signed short vec_vavgsh (vector signed short, 16923 vector signed short); 16924 16925vector unsigned short vec_vavguh (vector unsigned short, 16926 vector unsigned short); 16927 16928vector signed char vec_vavgsb (vector signed char, vector signed char); 16929 16930vector unsigned char vec_vavgub (vector unsigned char, 16931 vector unsigned char); 16932 16933vector float vec_copysign (vector float); 16934 16935vector float vec_ceil (vector float); 16936 16937vector signed int vec_cmpb (vector float, vector float); 16938 16939vector bool char vec_cmpeq (vector bool char, vector bool char); 16940vector bool short vec_cmpeq (vector bool short, vector bool short); 16941vector bool int vec_cmpeq (vector bool int, vector bool int); 16942vector bool char vec_cmpeq (vector signed char, vector signed char); 16943vector bool char vec_cmpeq (vector unsigned char, vector unsigned char); 16944vector bool short vec_cmpeq (vector signed short, vector signed short); 16945vector bool short vec_cmpeq (vector unsigned short, 16946 vector unsigned short); 16947vector bool int vec_cmpeq (vector signed int, vector signed int); 16948vector bool int vec_cmpeq (vector unsigned int, vector unsigned int); 16949vector bool int vec_cmpeq (vector float, vector float); 16950 16951vector bool int vec_vcmpeqfp (vector float, vector float); 16952 16953vector bool int vec_vcmpequw (vector signed int, vector signed int); 16954vector bool int vec_vcmpequw (vector unsigned int, vector unsigned int); 16955 16956vector bool short vec_vcmpequh (vector signed short, 16957 vector signed short); 16958vector bool short vec_vcmpequh (vector unsigned short, 16959 vector unsigned short); 16960 16961vector bool char vec_vcmpequb (vector signed char, vector signed char); 16962vector bool char vec_vcmpequb (vector unsigned char, 16963 vector unsigned char); 16964 16965vector bool int vec_cmpge (vector float, vector float); 16966 16967vector bool char vec_cmpgt (vector unsigned char, vector unsigned char); 16968vector bool char vec_cmpgt (vector signed char, vector signed char); 16969vector bool short vec_cmpgt (vector unsigned short, 16970 vector unsigned short); 16971vector bool short vec_cmpgt (vector signed short, vector signed short); 16972vector bool int vec_cmpgt (vector unsigned int, vector unsigned int); 16973vector bool int vec_cmpgt (vector signed int, vector signed int); 16974vector bool int vec_cmpgt (vector float, vector float); 16975 16976vector bool int vec_vcmpgtfp (vector float, vector float); 16977 16978vector bool int vec_vcmpgtsw (vector signed int, vector signed int); 16979 16980vector bool int vec_vcmpgtuw (vector unsigned int, vector unsigned int); 16981 16982vector bool short vec_vcmpgtsh (vector signed short, 16983 vector signed short); 16984 16985vector bool short vec_vcmpgtuh (vector unsigned short, 16986 vector unsigned short); 16987 16988vector bool char vec_vcmpgtsb (vector signed char, vector signed char); 16989 16990vector bool char vec_vcmpgtub (vector unsigned char, 16991 vector unsigned char); 16992 16993vector bool int vec_cmple (vector float, vector float); 16994 16995vector bool char vec_cmplt (vector unsigned char, vector unsigned char); 16996vector bool char vec_cmplt (vector signed char, vector signed char); 16997vector bool short vec_cmplt (vector unsigned short, 16998 vector unsigned short); 16999vector bool short vec_cmplt (vector signed short, vector signed short); 17000vector bool int vec_cmplt (vector unsigned int, vector unsigned int); 17001vector bool int vec_cmplt (vector signed int, vector signed int); 17002vector bool int vec_cmplt (vector float, vector float); 17003 17004vector float vec_cpsgn (vector float, vector float); 17005 17006vector float vec_ctf (vector unsigned int, const int); 17007vector float vec_ctf (vector signed int, const int); 17008vector double vec_ctf (vector unsigned long, const int); 17009vector double vec_ctf (vector signed long, const int); 17010 17011vector float vec_vcfsx (vector signed int, const int); 17012 17013vector float vec_vcfux (vector unsigned int, const int); 17014 17015vector signed int vec_cts (vector float, const int); 17016vector signed long vec_cts (vector double, const int); 17017 17018vector unsigned int vec_ctu (vector float, const int); 17019vector unsigned long vec_ctu (vector double, const int); 17020 17021vector double vec_doublee (vector float); 17022vector double vec_doublee (vector signed int); 17023vector double vec_doublee (vector unsigned int); 17024 17025vector double vec_doubleo (vector float); 17026vector double vec_doubleo (vector signed int); 17027vector double vec_doubleo (vector unsigned int); 17028 17029vector double vec_doubleh (vector float); 17030vector double vec_doubleh (vector signed int); 17031vector double vec_doubleh (vector unsigned int); 17032 17033vector double vec_doublel (vector float); 17034vector double vec_doublel (vector signed int); 17035vector double vec_doublel (vector unsigned int); 17036 17037void vec_dss (const int); 17038 17039void vec_dssall (void); 17040 17041void vec_dst (const vector unsigned char *, int, const int); 17042void vec_dst (const vector signed char *, int, const int); 17043void vec_dst (const vector bool char *, int, const int); 17044void vec_dst (const vector unsigned short *, int, const int); 17045void vec_dst (const vector signed short *, int, const int); 17046void vec_dst (const vector bool short *, int, const int); 17047void vec_dst (const vector pixel *, int, const int); 17048void vec_dst (const vector unsigned int *, int, const int); 17049void vec_dst (const vector signed int *, int, const int); 17050void vec_dst (const vector bool int *, int, const int); 17051void vec_dst (const vector float *, int, const int); 17052void vec_dst (const unsigned char *, int, const int); 17053void vec_dst (const signed char *, int, const int); 17054void vec_dst (const unsigned short *, int, const int); 17055void vec_dst (const short *, int, const int); 17056void vec_dst (const unsigned int *, int, const int); 17057void vec_dst (const int *, int, const int); 17058void vec_dst (const unsigned long *, int, const int); 17059void vec_dst (const long *, int, const int); 17060void vec_dst (const float *, int, const int); 17061 17062void vec_dstst (const vector unsigned char *, int, const int); 17063void vec_dstst (const vector signed char *, int, const int); 17064void vec_dstst (const vector bool char *, int, const int); 17065void vec_dstst (const vector unsigned short *, int, const int); 17066void vec_dstst (const vector signed short *, int, const int); 17067void vec_dstst (const vector bool short *, int, const int); 17068void vec_dstst (const vector pixel *, int, const int); 17069void vec_dstst (const vector unsigned int *, int, const int); 17070void vec_dstst (const vector signed int *, int, const int); 17071void vec_dstst (const vector bool int *, int, const int); 17072void vec_dstst (const vector float *, int, const int); 17073void vec_dstst (const unsigned char *, int, const int); 17074void vec_dstst (const signed char *, int, const int); 17075void vec_dstst (const unsigned short *, int, const int); 17076void vec_dstst (const short *, int, const int); 17077void vec_dstst (const unsigned int *, int, const int); 17078void vec_dstst (const int *, int, const int); 17079void vec_dstst (const unsigned long *, int, const int); 17080void vec_dstst (const long *, int, const int); 17081void vec_dstst (const float *, int, const int); 17082 17083void vec_dststt (const vector unsigned char *, int, const int); 17084void vec_dststt (const vector signed char *, int, const int); 17085void vec_dststt (const vector bool char *, int, const int); 17086void vec_dststt (const vector unsigned short *, int, const int); 17087void vec_dststt (const vector signed short *, int, const int); 17088void vec_dststt (const vector bool short *, int, const int); 17089void vec_dststt (const vector pixel *, int, const int); 17090void vec_dststt (const vector unsigned int *, int, const int); 17091void vec_dststt (const vector signed int *, int, const int); 17092void vec_dststt (const vector bool int *, int, const int); 17093void vec_dststt (const vector float *, int, const int); 17094void vec_dststt (const unsigned char *, int, const int); 17095void vec_dststt (const signed char *, int, const int); 17096void vec_dststt (const unsigned short *, int, const int); 17097void vec_dststt (const short *, int, const int); 17098void vec_dststt (const unsigned int *, int, const int); 17099void vec_dststt (const int *, int, const int); 17100void vec_dststt (const unsigned long *, int, const int); 17101void vec_dststt (const long *, int, const int); 17102void vec_dststt (const float *, int, const int); 17103 17104void vec_dstt (const vector unsigned char *, int, const int); 17105void vec_dstt (const vector signed char *, int, const int); 17106void vec_dstt (const vector bool char *, int, const int); 17107void vec_dstt (const vector unsigned short *, int, const int); 17108void vec_dstt (const vector signed short *, int, const int); 17109void vec_dstt (const vector bool short *, int, const int); 17110void vec_dstt (const vector pixel *, int, const int); 17111void vec_dstt (const vector unsigned int *, int, const int); 17112void vec_dstt (const vector signed int *, int, const int); 17113void vec_dstt (const vector bool int *, int, const int); 17114void vec_dstt (const vector float *, int, const int); 17115void vec_dstt (const unsigned char *, int, const int); 17116void vec_dstt (const signed char *, int, const int); 17117void vec_dstt (const unsigned short *, int, const int); 17118void vec_dstt (const short *, int, const int); 17119void vec_dstt (const unsigned int *, int, const int); 17120void vec_dstt (const int *, int, const int); 17121void vec_dstt (const unsigned long *, int, const int); 17122void vec_dstt (const long *, int, const int); 17123void vec_dstt (const float *, int, const int); 17124 17125vector float vec_expte (vector float); 17126 17127vector float vec_floor (vector float); 17128 17129vector float vec_float (vector signed int); 17130vector float vec_float (vector unsigned int); 17131 17132vector float vec_float2 (vector signed long long, vector signed long long); 17133vector float vec_float2 (vector unsigned long long, vector signed long long); 17134 17135vector float vec_floate (vector double); 17136vector float vec_floate (vector signed long long); 17137vector float vec_floate (vector unsigned long long); 17138 17139vector float vec_floato (vector double); 17140vector float vec_floato (vector signed long long); 17141vector float vec_floato (vector unsigned long long); 17142 17143vector float vec_ld (int, const vector float *); 17144vector float vec_ld (int, const float *); 17145vector bool int vec_ld (int, const vector bool int *); 17146vector signed int vec_ld (int, const vector signed int *); 17147vector signed int vec_ld (int, const int *); 17148vector signed int vec_ld (int, const long *); 17149vector unsigned int vec_ld (int, const vector unsigned int *); 17150vector unsigned int vec_ld (int, const unsigned int *); 17151vector unsigned int vec_ld (int, const unsigned long *); 17152vector bool short vec_ld (int, const vector bool short *); 17153vector pixel vec_ld (int, const vector pixel *); 17154vector signed short vec_ld (int, const vector signed short *); 17155vector signed short vec_ld (int, const short *); 17156vector unsigned short vec_ld (int, const vector unsigned short *); 17157vector unsigned short vec_ld (int, const unsigned short *); 17158vector bool char vec_ld (int, const vector bool char *); 17159vector signed char vec_ld (int, const vector signed char *); 17160vector signed char vec_ld (int, const signed char *); 17161vector unsigned char vec_ld (int, const vector unsigned char *); 17162vector unsigned char vec_ld (int, const unsigned char *); 17163 17164vector signed char vec_lde (int, const signed char *); 17165vector unsigned char vec_lde (int, const unsigned char *); 17166vector signed short vec_lde (int, const short *); 17167vector unsigned short vec_lde (int, const unsigned short *); 17168vector float vec_lde (int, const float *); 17169vector signed int vec_lde (int, const int *); 17170vector unsigned int vec_lde (int, const unsigned int *); 17171vector signed int vec_lde (int, const long *); 17172vector unsigned int vec_lde (int, const unsigned long *); 17173 17174vector float vec_lvewx (int, float *); 17175vector signed int vec_lvewx (int, int *); 17176vector unsigned int vec_lvewx (int, unsigned int *); 17177vector signed int vec_lvewx (int, long *); 17178vector unsigned int vec_lvewx (int, unsigned long *); 17179 17180vector signed short vec_lvehx (int, short *); 17181vector unsigned short vec_lvehx (int, unsigned short *); 17182 17183vector signed char vec_lvebx (int, char *); 17184vector unsigned char vec_lvebx (int, unsigned char *); 17185 17186vector float vec_ldl (int, const vector float *); 17187vector float vec_ldl (int, const float *); 17188vector bool int vec_ldl (int, const vector bool int *); 17189vector signed int vec_ldl (int, const vector signed int *); 17190vector signed int vec_ldl (int, const int *); 17191vector signed int vec_ldl (int, const long *); 17192vector unsigned int vec_ldl (int, const vector unsigned int *); 17193vector unsigned int vec_ldl (int, const unsigned int *); 17194vector unsigned int vec_ldl (int, const unsigned long *); 17195vector bool short vec_ldl (int, const vector bool short *); 17196vector pixel vec_ldl (int, const vector pixel *); 17197vector signed short vec_ldl (int, const vector signed short *); 17198vector signed short vec_ldl (int, const short *); 17199vector unsigned short vec_ldl (int, const vector unsigned short *); 17200vector unsigned short vec_ldl (int, const unsigned short *); 17201vector bool char vec_ldl (int, const vector bool char *); 17202vector signed char vec_ldl (int, const vector signed char *); 17203vector signed char vec_ldl (int, const signed char *); 17204vector unsigned char vec_ldl (int, const vector unsigned char *); 17205vector unsigned char vec_ldl (int, const unsigned char *); 17206 17207vector float vec_loge (vector float); 17208 17209vector unsigned char vec_lvsl (int, const volatile unsigned char *); 17210vector unsigned char vec_lvsl (int, const volatile signed char *); 17211vector unsigned char vec_lvsl (int, const volatile unsigned short *); 17212vector unsigned char vec_lvsl (int, const volatile short *); 17213vector unsigned char vec_lvsl (int, const volatile unsigned int *); 17214vector unsigned char vec_lvsl (int, const volatile int *); 17215vector unsigned char vec_lvsl (int, const volatile unsigned long *); 17216vector unsigned char vec_lvsl (int, const volatile long *); 17217vector unsigned char vec_lvsl (int, const volatile float *); 17218 17219vector unsigned char vec_lvsr (int, const volatile unsigned char *); 17220vector unsigned char vec_lvsr (int, const volatile signed char *); 17221vector unsigned char vec_lvsr (int, const volatile unsigned short *); 17222vector unsigned char vec_lvsr (int, const volatile short *); 17223vector unsigned char vec_lvsr (int, const volatile unsigned int *); 17224vector unsigned char vec_lvsr (int, const volatile int *); 17225vector unsigned char vec_lvsr (int, const volatile unsigned long *); 17226vector unsigned char vec_lvsr (int, const volatile long *); 17227vector unsigned char vec_lvsr (int, const volatile float *); 17228 17229vector float vec_madd (vector float, vector float, vector float); 17230 17231vector signed short vec_madds (vector signed short, 17232 vector signed short, 17233 vector signed short); 17234 17235vector unsigned char vec_max (vector bool char, vector unsigned char); 17236vector unsigned char vec_max (vector unsigned char, vector bool char); 17237vector unsigned char vec_max (vector unsigned char, 17238 vector unsigned char); 17239vector signed char vec_max (vector bool char, vector signed char); 17240vector signed char vec_max (vector signed char, vector bool char); 17241vector signed char vec_max (vector signed char, vector signed char); 17242vector unsigned short vec_max (vector bool short, 17243 vector unsigned short); 17244vector unsigned short vec_max (vector unsigned short, 17245 vector bool short); 17246vector unsigned short vec_max (vector unsigned short, 17247 vector unsigned short); 17248vector signed short vec_max (vector bool short, vector signed short); 17249vector signed short vec_max (vector signed short, vector bool short); 17250vector signed short vec_max (vector signed short, vector signed short); 17251vector unsigned int vec_max (vector bool int, vector unsigned int); 17252vector unsigned int vec_max (vector unsigned int, vector bool int); 17253vector unsigned int vec_max (vector unsigned int, vector unsigned int); 17254vector signed int vec_max (vector bool int, vector signed int); 17255vector signed int vec_max (vector signed int, vector bool int); 17256vector signed int vec_max (vector signed int, vector signed int); 17257vector float vec_max (vector float, vector float); 17258 17259vector float vec_vmaxfp (vector float, vector float); 17260 17261vector signed int vec_vmaxsw (vector bool int, vector signed int); 17262vector signed int vec_vmaxsw (vector signed int, vector bool int); 17263vector signed int vec_vmaxsw (vector signed int, vector signed int); 17264 17265vector unsigned int vec_vmaxuw (vector bool int, vector unsigned int); 17266vector unsigned int vec_vmaxuw (vector unsigned int, vector bool int); 17267vector unsigned int vec_vmaxuw (vector unsigned int, 17268 vector unsigned int); 17269 17270vector signed short vec_vmaxsh (vector bool short, vector signed short); 17271vector signed short vec_vmaxsh (vector signed short, vector bool short); 17272vector signed short vec_vmaxsh (vector signed short, 17273 vector signed short); 17274 17275vector unsigned short vec_vmaxuh (vector bool short, 17276 vector unsigned short); 17277vector unsigned short vec_vmaxuh (vector unsigned short, 17278 vector bool short); 17279vector unsigned short vec_vmaxuh (vector unsigned short, 17280 vector unsigned short); 17281 17282vector signed char vec_vmaxsb (vector bool char, vector signed char); 17283vector signed char vec_vmaxsb (vector signed char, vector bool char); 17284vector signed char vec_vmaxsb (vector signed char, vector signed char); 17285 17286vector unsigned char vec_vmaxub (vector bool char, 17287 vector unsigned char); 17288vector unsigned char vec_vmaxub (vector unsigned char, 17289 vector bool char); 17290vector unsigned char vec_vmaxub (vector unsigned char, 17291 vector unsigned char); 17292 17293vector bool char vec_mergeh (vector bool char, vector bool char); 17294vector signed char vec_mergeh (vector signed char, vector signed char); 17295vector unsigned char vec_mergeh (vector unsigned char, 17296 vector unsigned char); 17297vector bool short vec_mergeh (vector bool short, vector bool short); 17298vector pixel vec_mergeh (vector pixel, vector pixel); 17299vector signed short vec_mergeh (vector signed short, 17300 vector signed short); 17301vector unsigned short vec_mergeh (vector unsigned short, 17302 vector unsigned short); 17303vector float vec_mergeh (vector float, vector float); 17304vector bool int vec_mergeh (vector bool int, vector bool int); 17305vector signed int vec_mergeh (vector signed int, vector signed int); 17306vector unsigned int vec_mergeh (vector unsigned int, 17307 vector unsigned int); 17308 17309vector float vec_vmrghw (vector float, vector float); 17310vector bool int vec_vmrghw (vector bool int, vector bool int); 17311vector signed int vec_vmrghw (vector signed int, vector signed int); 17312vector unsigned int vec_vmrghw (vector unsigned int, 17313 vector unsigned int); 17314 17315vector bool short vec_vmrghh (vector bool short, vector bool short); 17316vector signed short vec_vmrghh (vector signed short, 17317 vector signed short); 17318vector unsigned short vec_vmrghh (vector unsigned short, 17319 vector unsigned short); 17320vector pixel vec_vmrghh (vector pixel, vector pixel); 17321 17322vector bool char vec_vmrghb (vector bool char, vector bool char); 17323vector signed char vec_vmrghb (vector signed char, vector signed char); 17324vector unsigned char vec_vmrghb (vector unsigned char, 17325 vector unsigned char); 17326 17327vector bool char vec_mergel (vector bool char, vector bool char); 17328vector signed char vec_mergel (vector signed char, vector signed char); 17329vector unsigned char vec_mergel (vector unsigned char, 17330 vector unsigned char); 17331vector bool short vec_mergel (vector bool short, vector bool short); 17332vector pixel vec_mergel (vector pixel, vector pixel); 17333vector signed short vec_mergel (vector signed short, 17334 vector signed short); 17335vector unsigned short vec_mergel (vector unsigned short, 17336 vector unsigned short); 17337vector float vec_mergel (vector float, vector float); 17338vector bool int vec_mergel (vector bool int, vector bool int); 17339vector signed int vec_mergel (vector signed int, vector signed int); 17340vector unsigned int vec_mergel (vector unsigned int, 17341 vector unsigned int); 17342 17343vector float vec_vmrglw (vector float, vector float); 17344vector signed int vec_vmrglw (vector signed int, vector signed int); 17345vector unsigned int vec_vmrglw (vector unsigned int, 17346 vector unsigned int); 17347vector bool int vec_vmrglw (vector bool int, vector bool int); 17348 17349vector bool short vec_vmrglh (vector bool short, vector bool short); 17350vector signed short vec_vmrglh (vector signed short, 17351 vector signed short); 17352vector unsigned short vec_vmrglh (vector unsigned short, 17353 vector unsigned short); 17354vector pixel vec_vmrglh (vector pixel, vector pixel); 17355 17356vector bool char vec_vmrglb (vector bool char, vector bool char); 17357vector signed char vec_vmrglb (vector signed char, vector signed char); 17358vector unsigned char vec_vmrglb (vector unsigned char, 17359 vector unsigned char); 17360 17361vector unsigned short vec_mfvscr (void); 17362 17363vector unsigned char vec_min (vector bool char, vector unsigned char); 17364vector unsigned char vec_min (vector unsigned char, vector bool char); 17365vector unsigned char vec_min (vector unsigned char, 17366 vector unsigned char); 17367vector signed char vec_min (vector bool char, vector signed char); 17368vector signed char vec_min (vector signed char, vector bool char); 17369vector signed char vec_min (vector signed char, vector signed char); 17370vector unsigned short vec_min (vector bool short, 17371 vector unsigned short); 17372vector unsigned short vec_min (vector unsigned short, 17373 vector bool short); 17374vector unsigned short vec_min (vector unsigned short, 17375 vector unsigned short); 17376vector signed short vec_min (vector bool short, vector signed short); 17377vector signed short vec_min (vector signed short, vector bool short); 17378vector signed short vec_min (vector signed short, vector signed short); 17379vector unsigned int vec_min (vector bool int, vector unsigned int); 17380vector unsigned int vec_min (vector unsigned int, vector bool int); 17381vector unsigned int vec_min (vector unsigned int, vector unsigned int); 17382vector signed int vec_min (vector bool int, vector signed int); 17383vector signed int vec_min (vector signed int, vector bool int); 17384vector signed int vec_min (vector signed int, vector signed int); 17385vector float vec_min (vector float, vector float); 17386 17387vector float vec_vminfp (vector float, vector float); 17388 17389vector signed int vec_vminsw (vector bool int, vector signed int); 17390vector signed int vec_vminsw (vector signed int, vector bool int); 17391vector signed int vec_vminsw (vector signed int, vector signed int); 17392 17393vector unsigned int vec_vminuw (vector bool int, vector unsigned int); 17394vector unsigned int vec_vminuw (vector unsigned int, vector bool int); 17395vector unsigned int vec_vminuw (vector unsigned int, 17396 vector unsigned int); 17397 17398vector signed short vec_vminsh (vector bool short, vector signed short); 17399vector signed short vec_vminsh (vector signed short, vector bool short); 17400vector signed short vec_vminsh (vector signed short, 17401 vector signed short); 17402 17403vector unsigned short vec_vminuh (vector bool short, 17404 vector unsigned short); 17405vector unsigned short vec_vminuh (vector unsigned short, 17406 vector bool short); 17407vector unsigned short vec_vminuh (vector unsigned short, 17408 vector unsigned short); 17409 17410vector signed char vec_vminsb (vector bool char, vector signed char); 17411vector signed char vec_vminsb (vector signed char, vector bool char); 17412vector signed char vec_vminsb (vector signed char, vector signed char); 17413 17414vector unsigned char vec_vminub (vector bool char, 17415 vector unsigned char); 17416vector unsigned char vec_vminub (vector unsigned char, 17417 vector bool char); 17418vector unsigned char vec_vminub (vector unsigned char, 17419 vector unsigned char); 17420 17421vector signed short vec_mladd (vector signed short, 17422 vector signed short, 17423 vector signed short); 17424vector signed short vec_mladd (vector signed short, 17425 vector unsigned short, 17426 vector unsigned short); 17427vector signed short vec_mladd (vector unsigned short, 17428 vector signed short, 17429 vector signed short); 17430vector unsigned short vec_mladd (vector unsigned short, 17431 vector unsigned short, 17432 vector unsigned short); 17433 17434vector signed short vec_mradds (vector signed short, 17435 vector signed short, 17436 vector signed short); 17437 17438vector unsigned int vec_msum (vector unsigned char, 17439 vector unsigned char, 17440 vector unsigned int); 17441vector signed int vec_msum (vector signed char, 17442 vector unsigned char, 17443 vector signed int); 17444vector unsigned int vec_msum (vector unsigned short, 17445 vector unsigned short, 17446 vector unsigned int); 17447vector signed int vec_msum (vector signed short, 17448 vector signed short, 17449 vector signed int); 17450 17451vector signed int vec_vmsumshm (vector signed short, 17452 vector signed short, 17453 vector signed int); 17454 17455vector unsigned int vec_vmsumuhm (vector unsigned short, 17456 vector unsigned short, 17457 vector unsigned int); 17458 17459vector signed int vec_vmsummbm (vector signed char, 17460 vector unsigned char, 17461 vector signed int); 17462 17463vector unsigned int vec_vmsumubm (vector unsigned char, 17464 vector unsigned char, 17465 vector unsigned int); 17466 17467vector unsigned int vec_msums (vector unsigned short, 17468 vector unsigned short, 17469 vector unsigned int); 17470vector signed int vec_msums (vector signed short, 17471 vector signed short, 17472 vector signed int); 17473 17474vector signed int vec_vmsumshs (vector signed short, 17475 vector signed short, 17476 vector signed int); 17477 17478vector unsigned int vec_vmsumuhs (vector unsigned short, 17479 vector unsigned short, 17480 vector unsigned int); 17481 17482void vec_mtvscr (vector signed int); 17483void vec_mtvscr (vector unsigned int); 17484void vec_mtvscr (vector bool int); 17485void vec_mtvscr (vector signed short); 17486void vec_mtvscr (vector unsigned short); 17487void vec_mtvscr (vector bool short); 17488void vec_mtvscr (vector pixel); 17489void vec_mtvscr (vector signed char); 17490void vec_mtvscr (vector unsigned char); 17491void vec_mtvscr (vector bool char); 17492 17493vector unsigned short vec_mule (vector unsigned char, 17494 vector unsigned char); 17495vector signed short vec_mule (vector signed char, 17496 vector signed char); 17497vector unsigned int vec_mule (vector unsigned short, 17498 vector unsigned short); 17499vector signed int vec_mule (vector signed short, vector signed short); 17500vector unsigned long long vec_mule (vector unsigned int, 17501 vector unsigned int); 17502vector signed long long vec_mule (vector signed int, 17503 vector signed int); 17504 17505vector signed int vec_vmulesh (vector signed short, 17506 vector signed short); 17507 17508vector unsigned int vec_vmuleuh (vector unsigned short, 17509 vector unsigned short); 17510 17511vector signed short vec_vmulesb (vector signed char, 17512 vector signed char); 17513 17514vector unsigned short vec_vmuleub (vector unsigned char, 17515 vector unsigned char); 17516 17517vector unsigned short vec_mulo (vector unsigned char, 17518 vector unsigned char); 17519vector signed short vec_mulo (vector signed char, vector signed char); 17520vector unsigned int vec_mulo (vector unsigned short, 17521 vector unsigned short); 17522vector signed int vec_mulo (vector signed short, vector signed short); 17523vector unsigned long long vec_mulo (vector unsigned int, 17524 vector unsigned int); 17525vector signed long long vec_mulo (vector signed int, 17526 vector signed int); 17527 17528vector signed int vec_vmulosh (vector signed short, 17529 vector signed short); 17530 17531vector unsigned int vec_vmulouh (vector unsigned short, 17532 vector unsigned short); 17533 17534vector signed short vec_vmulosb (vector signed char, 17535 vector signed char); 17536 17537vector unsigned short vec_vmuloub (vector unsigned char, 17538 vector unsigned char); 17539 17540vector float vec_nmsub (vector float, vector float, vector float); 17541 17542vector signed char vec_nabs (vector signed char); 17543vector signed short vec_nabs (vector signed short); 17544vector signed int vec_nabs (vector signed int); 17545vector float vec_nabs (vector float); 17546vector double vec_nabs (vector double); 17547 17548vector signed char vec_neg (vector signed char); 17549vector signed short vec_neg (vector signed short); 17550vector signed int vec_neg (vector signed int); 17551vector signed long long vec_neg (vector signed long long); 17552vector float char vec_neg (vector float); 17553vector double vec_neg (vector double); 17554 17555vector float vec_nor (vector float, vector float); 17556vector signed int vec_nor (vector signed int, vector signed int); 17557vector unsigned int vec_nor (vector unsigned int, vector unsigned int); 17558vector bool int vec_nor (vector bool int, vector bool int); 17559vector signed short vec_nor (vector signed short, vector signed short); 17560vector unsigned short vec_nor (vector unsigned short, 17561 vector unsigned short); 17562vector bool short vec_nor (vector bool short, vector bool short); 17563vector signed char vec_nor (vector signed char, vector signed char); 17564vector unsigned char vec_nor (vector unsigned char, 17565 vector unsigned char); 17566vector bool char vec_nor (vector bool char, vector bool char); 17567 17568vector float vec_or (vector float, vector float); 17569vector float vec_or (vector float, vector bool int); 17570vector float vec_or (vector bool int, vector float); 17571vector bool int vec_or (vector bool int, vector bool int); 17572vector signed int vec_or (vector bool int, vector signed int); 17573vector signed int vec_or (vector signed int, vector bool int); 17574vector signed int vec_or (vector signed int, vector signed int); 17575vector unsigned int vec_or (vector bool int, vector unsigned int); 17576vector unsigned int vec_or (vector unsigned int, vector bool int); 17577vector unsigned int vec_or (vector unsigned int, vector unsigned int); 17578vector bool short vec_or (vector bool short, vector bool short); 17579vector signed short vec_or (vector bool short, vector signed short); 17580vector signed short vec_or (vector signed short, vector bool short); 17581vector signed short vec_or (vector signed short, vector signed short); 17582vector unsigned short vec_or (vector bool short, vector unsigned short); 17583vector unsigned short vec_or (vector unsigned short, vector bool short); 17584vector unsigned short vec_or (vector unsigned short, 17585 vector unsigned short); 17586vector signed char vec_or (vector bool char, vector signed char); 17587vector bool char vec_or (vector bool char, vector bool char); 17588vector signed char vec_or (vector signed char, vector bool char); 17589vector signed char vec_or (vector signed char, vector signed char); 17590vector unsigned char vec_or (vector bool char, vector unsigned char); 17591vector unsigned char vec_or (vector unsigned char, vector bool char); 17592vector unsigned char vec_or (vector unsigned char, 17593 vector unsigned char); 17594 17595vector signed char vec_pack (vector signed short, vector signed short); 17596vector unsigned char vec_pack (vector unsigned short, 17597 vector unsigned short); 17598vector bool char vec_pack (vector bool short, vector bool short); 17599vector signed short vec_pack (vector signed int, vector signed int); 17600vector unsigned short vec_pack (vector unsigned int, 17601 vector unsigned int); 17602vector bool short vec_pack (vector bool int, vector bool int); 17603 17604vector bool short vec_vpkuwum (vector bool int, vector bool int); 17605vector signed short vec_vpkuwum (vector signed int, vector signed int); 17606vector unsigned short vec_vpkuwum (vector unsigned int, 17607 vector unsigned int); 17608 17609vector bool char vec_vpkuhum (vector bool short, vector bool short); 17610vector signed char vec_vpkuhum (vector signed short, 17611 vector signed short); 17612vector unsigned char vec_vpkuhum (vector unsigned short, 17613 vector unsigned short); 17614 17615vector pixel vec_packpx (vector unsigned int, vector unsigned int); 17616 17617vector unsigned char vec_packs (vector unsigned short, 17618 vector unsigned short); 17619vector signed char vec_packs (vector signed short, vector signed short); 17620vector unsigned short vec_packs (vector unsigned int, 17621 vector unsigned int); 17622vector signed short vec_packs (vector signed int, vector signed int); 17623 17624vector signed short vec_vpkswss (vector signed int, vector signed int); 17625 17626vector unsigned short vec_vpkuwus (vector unsigned int, 17627 vector unsigned int); 17628 17629vector signed char vec_vpkshss (vector signed short, 17630 vector signed short); 17631 17632vector unsigned char vec_vpkuhus (vector unsigned short, 17633 vector unsigned short); 17634 17635vector unsigned char vec_packsu (vector unsigned short, 17636 vector unsigned short); 17637vector unsigned char vec_packsu (vector signed short, 17638 vector signed short); 17639vector unsigned short vec_packsu (vector unsigned int, 17640 vector unsigned int); 17641vector unsigned short vec_packsu (vector signed int, vector signed int); 17642 17643vector unsigned short vec_vpkswus (vector signed int, 17644 vector signed int); 17645 17646vector unsigned char vec_vpkshus (vector signed short, 17647 vector signed short); 17648 17649vector float vec_perm (vector float, 17650 vector float, 17651 vector unsigned char); 17652vector signed int vec_perm (vector signed int, 17653 vector signed int, 17654 vector unsigned char); 17655vector unsigned int vec_perm (vector unsigned int, 17656 vector unsigned int, 17657 vector unsigned char); 17658vector bool int vec_perm (vector bool int, 17659 vector bool int, 17660 vector unsigned char); 17661vector signed short vec_perm (vector signed short, 17662 vector signed short, 17663 vector unsigned char); 17664vector unsigned short vec_perm (vector unsigned short, 17665 vector unsigned short, 17666 vector unsigned char); 17667vector bool short vec_perm (vector bool short, 17668 vector bool short, 17669 vector unsigned char); 17670vector pixel vec_perm (vector pixel, 17671 vector pixel, 17672 vector unsigned char); 17673vector signed char vec_perm (vector signed char, 17674 vector signed char, 17675 vector unsigned char); 17676vector unsigned char vec_perm (vector unsigned char, 17677 vector unsigned char, 17678 vector unsigned char); 17679vector bool char vec_perm (vector bool char, 17680 vector bool char, 17681 vector unsigned char); 17682 17683vector float vec_re (vector float); 17684 17685vector bool char vec_reve (vector bool char); 17686vector signed char vec_reve (vector signed char); 17687vector unsigned char vec_reve (vector unsigned char); 17688vector bool int vec_reve (vector bool int); 17689vector signed int vec_reve (vector signed int); 17690vector unsigned int vec_reve (vector unsigned int); 17691vector bool long long vec_reve (vector bool long long); 17692vector signed long long vec_reve (vector signed long long); 17693vector unsigned long long vec_reve (vector unsigned long long); 17694vector bool short vec_reve (vector bool short); 17695vector signed short vec_reve (vector signed short); 17696vector unsigned short vec_reve (vector unsigned short); 17697 17698vector signed char vec_rl (vector signed char, 17699 vector unsigned char); 17700vector unsigned char vec_rl (vector unsigned char, 17701 vector unsigned char); 17702vector signed short vec_rl (vector signed short, vector unsigned short); 17703vector unsigned short vec_rl (vector unsigned short, 17704 vector unsigned short); 17705vector signed int vec_rl (vector signed int, vector unsigned int); 17706vector unsigned int vec_rl (vector unsigned int, vector unsigned int); 17707 17708vector signed int vec_vrlw (vector signed int, vector unsigned int); 17709vector unsigned int vec_vrlw (vector unsigned int, vector unsigned int); 17710 17711vector signed short vec_vrlh (vector signed short, 17712 vector unsigned short); 17713vector unsigned short vec_vrlh (vector unsigned short, 17714 vector unsigned short); 17715 17716vector signed char vec_vrlb (vector signed char, vector unsigned char); 17717vector unsigned char vec_vrlb (vector unsigned char, 17718 vector unsigned char); 17719 17720vector float vec_round (vector float); 17721 17722vector float vec_recip (vector float, vector float); 17723 17724vector float vec_rsqrt (vector float); 17725 17726vector float vec_rsqrte (vector float); 17727 17728vector float vec_sel (vector float, vector float, vector bool int); 17729vector float vec_sel (vector float, vector float, vector unsigned int); 17730vector signed int vec_sel (vector signed int, 17731 vector signed int, 17732 vector bool int); 17733vector signed int vec_sel (vector signed int, 17734 vector signed int, 17735 vector unsigned int); 17736vector unsigned int vec_sel (vector unsigned int, 17737 vector unsigned int, 17738 vector bool int); 17739vector unsigned int vec_sel (vector unsigned int, 17740 vector unsigned int, 17741 vector unsigned int); 17742vector bool int vec_sel (vector bool int, 17743 vector bool int, 17744 vector bool int); 17745vector bool int vec_sel (vector bool int, 17746 vector bool int, 17747 vector unsigned int); 17748vector signed short vec_sel (vector signed short, 17749 vector signed short, 17750 vector bool short); 17751vector signed short vec_sel (vector signed short, 17752 vector signed short, 17753 vector unsigned short); 17754vector unsigned short vec_sel (vector unsigned short, 17755 vector unsigned short, 17756 vector bool short); 17757vector unsigned short vec_sel (vector unsigned short, 17758 vector unsigned short, 17759 vector unsigned short); 17760vector bool short vec_sel (vector bool short, 17761 vector bool short, 17762 vector bool short); 17763vector bool short vec_sel (vector bool short, 17764 vector bool short, 17765 vector unsigned short); 17766vector signed char vec_sel (vector signed char, 17767 vector signed char, 17768 vector bool char); 17769vector signed char vec_sel (vector signed char, 17770 vector signed char, 17771 vector unsigned char); 17772vector unsigned char vec_sel (vector unsigned char, 17773 vector unsigned char, 17774 vector bool char); 17775vector unsigned char vec_sel (vector unsigned char, 17776 vector unsigned char, 17777 vector unsigned char); 17778vector bool char vec_sel (vector bool char, 17779 vector bool char, 17780 vector bool char); 17781vector bool char vec_sel (vector bool char, 17782 vector bool char, 17783 vector unsigned char); 17784 17785vector signed long long vec_signed (vector double); 17786vector signed int vec_signed (vector float); 17787 17788vector signed int vec_signede (vector double); 17789vector signed int vec_signedo (vector double); 17790vector signed int vec_signed2 (vector double, vector double); 17791 17792vector signed char vec_sl (vector signed char, 17793 vector unsigned char); 17794vector unsigned char vec_sl (vector unsigned char, 17795 vector unsigned char); 17796vector signed short vec_sl (vector signed short, vector unsigned short); 17797vector unsigned short vec_sl (vector unsigned short, 17798 vector unsigned short); 17799vector signed int vec_sl (vector signed int, vector unsigned int); 17800vector unsigned int vec_sl (vector unsigned int, vector unsigned int); 17801 17802vector signed int vec_vslw (vector signed int, vector unsigned int); 17803vector unsigned int vec_vslw (vector unsigned int, vector unsigned int); 17804 17805vector signed short vec_vslh (vector signed short, 17806 vector unsigned short); 17807vector unsigned short vec_vslh (vector unsigned short, 17808 vector unsigned short); 17809 17810vector signed char vec_vslb (vector signed char, vector unsigned char); 17811vector unsigned char vec_vslb (vector unsigned char, 17812 vector unsigned char); 17813 17814vector float vec_sld (vector float, vector float, const int); 17815vector double vec_sld (vector double, vector double, const int); 17816 17817vector signed int vec_sld (vector signed int, 17818 vector signed int, 17819 const int); 17820vector unsigned int vec_sld (vector unsigned int, 17821 vector unsigned int, 17822 const int); 17823vector bool int vec_sld (vector bool int, 17824 vector bool int, 17825 const int); 17826vector signed short vec_sld (vector signed short, 17827 vector signed short, 17828 const int); 17829vector unsigned short vec_sld (vector unsigned short, 17830 vector unsigned short, 17831 const int); 17832vector bool short vec_sld (vector bool short, 17833 vector bool short, 17834 const int); 17835vector pixel vec_sld (vector pixel, 17836 vector pixel, 17837 const int); 17838vector signed char vec_sld (vector signed char, 17839 vector signed char, 17840 const int); 17841vector unsigned char vec_sld (vector unsigned char, 17842 vector unsigned char, 17843 const int); 17844vector bool char vec_sld (vector bool char, 17845 vector bool char, 17846 const int); 17847vector bool long long int vec_sld (vector bool long long int, 17848 vector bool long long int, const int); 17849vector long long int vec_sld (vector long long int, 17850 vector long long int, const int); 17851vector unsigned long long int vec_sld (vector unsigned long long int, 17852 vector unsigned long long int, 17853 const int); 17854 17855vector signed char vec_sldw (vector signed char, 17856 vector signed char, 17857 const int); 17858vector unsigned char vec_sldw (vector unsigned char, 17859 vector unsigned char, 17860 const int); 17861vector signed short vec_sldw (vector signed short, 17862 vector signed short, 17863 const int); 17864vector unsigned short vec_sldw (vector unsigned short, 17865 vector unsigned short, 17866 const int); 17867vector signed int vec_sldw (vector signed int, 17868 vector signed int, 17869 const int); 17870vector unsigned int vec_sldw (vector unsigned int, 17871 vector unsigned int, 17872 const int); 17873vector signed long long vec_sldw (vector signed long long, 17874 vector signed long long, 17875 const int); 17876vector unsigned long long vec_sldw (vector unsigned long long, 17877 vector unsigned long long, 17878 const int); 17879 17880vector signed int vec_sll (vector signed int, 17881 vector unsigned int); 17882vector signed int vec_sll (vector signed int, 17883 vector unsigned short); 17884vector signed int vec_sll (vector signed int, 17885 vector unsigned char); 17886vector unsigned int vec_sll (vector unsigned int, 17887 vector unsigned int); 17888vector unsigned int vec_sll (vector unsigned int, 17889 vector unsigned short); 17890vector unsigned int vec_sll (vector unsigned int, 17891 vector unsigned char); 17892vector bool int vec_sll (vector bool int, 17893 vector unsigned int); 17894vector bool int vec_sll (vector bool int, 17895 vector unsigned short); 17896vector bool int vec_sll (vector bool int, 17897 vector unsigned char); 17898vector signed short vec_sll (vector signed short, 17899 vector unsigned int); 17900vector signed short vec_sll (vector signed short, 17901 vector unsigned short); 17902vector signed short vec_sll (vector signed short, 17903 vector unsigned char); 17904vector unsigned short vec_sll (vector unsigned short, 17905 vector unsigned int); 17906vector unsigned short vec_sll (vector unsigned short, 17907 vector unsigned short); 17908vector unsigned short vec_sll (vector unsigned short, 17909 vector unsigned char); 17910vector long long int vec_sll (vector long long int, 17911 vector unsigned char); 17912vector unsigned long long int vec_sll (vector unsigned long long int, 17913 vector unsigned char); 17914vector bool short vec_sll (vector bool short, vector unsigned int); 17915vector bool short vec_sll (vector bool short, vector unsigned short); 17916vector bool short vec_sll (vector bool short, vector unsigned char); 17917vector pixel vec_sll (vector pixel, vector unsigned int); 17918vector pixel vec_sll (vector pixel, vector unsigned short); 17919vector pixel vec_sll (vector pixel, vector unsigned char); 17920vector signed char vec_sll (vector signed char, vector unsigned int); 17921vector signed char vec_sll (vector signed char, vector unsigned short); 17922vector signed char vec_sll (vector signed char, vector unsigned char); 17923vector unsigned char vec_sll (vector unsigned char, 17924 vector unsigned int); 17925vector unsigned char vec_sll (vector unsigned char, 17926 vector unsigned short); 17927vector unsigned char vec_sll (vector unsigned char, 17928 vector unsigned char); 17929vector bool char vec_sll (vector bool char, vector unsigned int); 17930vector bool char vec_sll (vector bool char, vector unsigned short); 17931vector bool char vec_sll (vector bool char, vector unsigned char); 17932 17933vector float vec_slo (vector float, vector signed char); 17934vector float vec_slo (vector float, vector unsigned char); 17935vector signed int vec_slo (vector signed int, vector signed char); 17936vector signed int vec_slo (vector signed int, vector unsigned char); 17937vector unsigned int vec_slo (vector unsigned int, vector signed char); 17938vector unsigned int vec_slo (vector unsigned int, vector unsigned char); 17939vector signed short vec_slo (vector signed short, vector signed char); 17940vector signed short vec_slo (vector signed short, vector unsigned char); 17941vector unsigned short vec_slo (vector unsigned short, 17942 vector signed char); 17943vector unsigned short vec_slo (vector unsigned short, 17944 vector unsigned char); 17945vector pixel vec_slo (vector pixel, vector signed char); 17946vector pixel vec_slo (vector pixel, vector unsigned char); 17947vector signed char vec_slo (vector signed char, vector signed char); 17948vector signed char vec_slo (vector signed char, vector unsigned char); 17949vector unsigned char vec_slo (vector unsigned char, vector signed char); 17950vector unsigned char vec_slo (vector unsigned char, 17951 vector unsigned char); 17952vector signed long long vec_slo (vector signed long long, vector signed char); 17953vector signed long long vec_slo (vector signed long long, vector unsigned char); 17954vector unsigned long long vec_slo (vector unsigned long long, vector signed char); 17955vector unsigned long long vec_slo (vector unsigned long long, vector unsigned char); 17956 17957vector signed char vec_splat (vector signed char, const int); 17958vector unsigned char vec_splat (vector unsigned char, const int); 17959vector bool char vec_splat (vector bool char, const int); 17960vector signed short vec_splat (vector signed short, const int); 17961vector unsigned short vec_splat (vector unsigned short, const int); 17962vector bool short vec_splat (vector bool short, const int); 17963vector pixel vec_splat (vector pixel, const int); 17964vector float vec_splat (vector float, const int); 17965vector signed int vec_splat (vector signed int, const int); 17966vector unsigned int vec_splat (vector unsigned int, const int); 17967vector bool int vec_splat (vector bool int, const int); 17968vector signed long vec_splat (vector signed long, const int); 17969vector unsigned long vec_splat (vector unsigned long, const int); 17970 17971vector signed char vec_splats (signed char); 17972vector unsigned char vec_splats (unsigned char); 17973vector signed short vec_splats (signed short); 17974vector unsigned short vec_splats (unsigned short); 17975vector signed int vec_splats (signed int); 17976vector unsigned int vec_splats (unsigned int); 17977vector float vec_splats (float); 17978 17979vector float vec_vspltw (vector float, const int); 17980vector signed int vec_vspltw (vector signed int, const int); 17981vector unsigned int vec_vspltw (vector unsigned int, const int); 17982vector bool int vec_vspltw (vector bool int, const int); 17983 17984vector bool short vec_vsplth (vector bool short, const int); 17985vector signed short vec_vsplth (vector signed short, const int); 17986vector unsigned short vec_vsplth (vector unsigned short, const int); 17987vector pixel vec_vsplth (vector pixel, const int); 17988 17989vector signed char vec_vspltb (vector signed char, const int); 17990vector unsigned char vec_vspltb (vector unsigned char, const int); 17991vector bool char vec_vspltb (vector bool char, const int); 17992 17993vector signed char vec_splat_s8 (const int); 17994 17995vector signed short vec_splat_s16 (const int); 17996 17997vector signed int vec_splat_s32 (const int); 17998 17999vector unsigned char vec_splat_u8 (const int); 18000 18001vector unsigned short vec_splat_u16 (const int); 18002 18003vector unsigned int vec_splat_u32 (const int); 18004 18005vector signed char vec_sr (vector signed char, vector unsigned char); 18006vector unsigned char vec_sr (vector unsigned char, 18007 vector unsigned char); 18008vector signed short vec_sr (vector signed short, 18009 vector unsigned short); 18010vector unsigned short vec_sr (vector unsigned short, 18011 vector unsigned short); 18012vector signed int vec_sr (vector signed int, vector unsigned int); 18013vector unsigned int vec_sr (vector unsigned int, vector unsigned int); 18014 18015vector signed int vec_vsrw (vector signed int, vector unsigned int); 18016vector unsigned int vec_vsrw (vector unsigned int, vector unsigned int); 18017 18018vector signed short vec_vsrh (vector signed short, 18019 vector unsigned short); 18020vector unsigned short vec_vsrh (vector unsigned short, 18021 vector unsigned short); 18022 18023vector signed char vec_vsrb (vector signed char, vector unsigned char); 18024vector unsigned char vec_vsrb (vector unsigned char, 18025 vector unsigned char); 18026 18027vector signed char vec_sra (vector signed char, vector unsigned char); 18028vector unsigned char vec_sra (vector unsigned char, 18029 vector unsigned char); 18030vector signed short vec_sra (vector signed short, 18031 vector unsigned short); 18032vector unsigned short vec_sra (vector unsigned short, 18033 vector unsigned short); 18034vector signed int vec_sra (vector signed int, vector unsigned int); 18035vector unsigned int vec_sra (vector unsigned int, vector unsigned int); 18036 18037vector signed int vec_vsraw (vector signed int, vector unsigned int); 18038vector unsigned int vec_vsraw (vector unsigned int, 18039 vector unsigned int); 18040 18041vector signed short vec_vsrah (vector signed short, 18042 vector unsigned short); 18043vector unsigned short vec_vsrah (vector unsigned short, 18044 vector unsigned short); 18045 18046vector signed char vec_vsrab (vector signed char, vector unsigned char); 18047vector unsigned char vec_vsrab (vector unsigned char, 18048 vector unsigned char); 18049 18050vector signed int vec_srl (vector signed int, vector unsigned int); 18051vector signed int vec_srl (vector signed int, vector unsigned short); 18052vector signed int vec_srl (vector signed int, vector unsigned char); 18053vector unsigned int vec_srl (vector unsigned int, vector unsigned int); 18054vector unsigned int vec_srl (vector unsigned int, 18055 vector unsigned short); 18056vector unsigned int vec_srl (vector unsigned int, vector unsigned char); 18057vector bool int vec_srl (vector bool int, vector unsigned int); 18058vector bool int vec_srl (vector bool int, vector unsigned short); 18059vector bool int vec_srl (vector bool int, vector unsigned char); 18060vector signed short vec_srl (vector signed short, vector unsigned int); 18061vector signed short vec_srl (vector signed short, 18062 vector unsigned short); 18063vector signed short vec_srl (vector signed short, vector unsigned char); 18064vector unsigned short vec_srl (vector unsigned short, 18065 vector unsigned int); 18066vector unsigned short vec_srl (vector unsigned short, 18067 vector unsigned short); 18068vector unsigned short vec_srl (vector unsigned short, 18069 vector unsigned char); 18070vector long long int vec_srl (vector long long int, 18071 vector unsigned char); 18072vector unsigned long long int vec_srl (vector unsigned long long int, 18073 vector unsigned char); 18074vector bool short vec_srl (vector bool short, vector unsigned int); 18075vector bool short vec_srl (vector bool short, vector unsigned short); 18076vector bool short vec_srl (vector bool short, vector unsigned char); 18077vector pixel vec_srl (vector pixel, vector unsigned int); 18078vector pixel vec_srl (vector pixel, vector unsigned short); 18079vector pixel vec_srl (vector pixel, vector unsigned char); 18080vector signed char vec_srl (vector signed char, vector unsigned int); 18081vector signed char vec_srl (vector signed char, vector unsigned short); 18082vector signed char vec_srl (vector signed char, vector unsigned char); 18083vector unsigned char vec_srl (vector unsigned char, 18084 vector unsigned int); 18085vector unsigned char vec_srl (vector unsigned char, 18086 vector unsigned short); 18087vector unsigned char vec_srl (vector unsigned char, 18088 vector unsigned char); 18089vector bool char vec_srl (vector bool char, vector unsigned int); 18090vector bool char vec_srl (vector bool char, vector unsigned short); 18091vector bool char vec_srl (vector bool char, vector unsigned char); 18092 18093vector float vec_sro (vector float, vector signed char); 18094vector float vec_sro (vector float, vector unsigned char); 18095vector signed int vec_sro (vector signed int, vector signed char); 18096vector signed int vec_sro (vector signed int, vector unsigned char); 18097vector unsigned int vec_sro (vector unsigned int, vector signed char); 18098vector unsigned int vec_sro (vector unsigned int, vector unsigned char); 18099vector signed short vec_sro (vector signed short, vector signed char); 18100vector signed short vec_sro (vector signed short, vector unsigned char); 18101vector unsigned short vec_sro (vector unsigned short, 18102 vector signed char); 18103vector unsigned short vec_sro (vector unsigned short, 18104 vector unsigned char); 18105vector long long int vec_sro (vector long long int, 18106 vector char); 18107vector long long int vec_sro (vector long long int, 18108 vector unsigned char); 18109vector unsigned long long int vec_sro (vector unsigned long long int, 18110 vector char); 18111vector unsigned long long int vec_sro (vector unsigned long long int, 18112 vector unsigned char); 18113vector pixel vec_sro (vector pixel, vector signed char); 18114vector pixel vec_sro (vector pixel, vector unsigned char); 18115vector signed char vec_sro (vector signed char, vector signed char); 18116vector signed char vec_sro (vector signed char, vector unsigned char); 18117vector unsigned char vec_sro (vector unsigned char, vector signed char); 18118vector unsigned char vec_sro (vector unsigned char, 18119 vector unsigned char); 18120 18121void vec_st (vector float, int, vector float *); 18122void vec_st (vector float, int, float *); 18123void vec_st (vector signed int, int, vector signed int *); 18124void vec_st (vector signed int, int, int *); 18125void vec_st (vector unsigned int, int, vector unsigned int *); 18126void vec_st (vector unsigned int, int, unsigned int *); 18127void vec_st (vector bool int, int, vector bool int *); 18128void vec_st (vector bool int, int, unsigned int *); 18129void vec_st (vector bool int, int, int *); 18130void vec_st (vector signed short, int, vector signed short *); 18131void vec_st (vector signed short, int, short *); 18132void vec_st (vector unsigned short, int, vector unsigned short *); 18133void vec_st (vector unsigned short, int, unsigned short *); 18134void vec_st (vector bool short, int, vector bool short *); 18135void vec_st (vector bool short, int, unsigned short *); 18136void vec_st (vector pixel, int, vector pixel *); 18137void vec_st (vector pixel, int, unsigned short *); 18138void vec_st (vector pixel, int, short *); 18139void vec_st (vector bool short, int, short *); 18140void vec_st (vector signed char, int, vector signed char *); 18141void vec_st (vector signed char, int, signed char *); 18142void vec_st (vector unsigned char, int, vector unsigned char *); 18143void vec_st (vector unsigned char, int, unsigned char *); 18144void vec_st (vector bool char, int, vector bool char *); 18145void vec_st (vector bool char, int, unsigned char *); 18146void vec_st (vector bool char, int, signed char *); 18147 18148void vec_ste (vector signed char, int, signed char *); 18149void vec_ste (vector unsigned char, int, unsigned char *); 18150void vec_ste (vector bool char, int, signed char *); 18151void vec_ste (vector bool char, int, unsigned char *); 18152void vec_ste (vector signed short, int, short *); 18153void vec_ste (vector unsigned short, int, unsigned short *); 18154void vec_ste (vector bool short, int, short *); 18155void vec_ste (vector bool short, int, unsigned short *); 18156void vec_ste (vector pixel, int, short *); 18157void vec_ste (vector pixel, int, unsigned short *); 18158void vec_ste (vector float, int, float *); 18159void vec_ste (vector signed int, int, int *); 18160void vec_ste (vector unsigned int, int, unsigned int *); 18161void vec_ste (vector bool int, int, int *); 18162void vec_ste (vector bool int, int, unsigned int *); 18163 18164void vec_stvewx (vector float, int, float *); 18165void vec_stvewx (vector signed int, int, int *); 18166void vec_stvewx (vector unsigned int, int, unsigned int *); 18167void vec_stvewx (vector bool int, int, int *); 18168void vec_stvewx (vector bool int, int, unsigned int *); 18169 18170void vec_stvehx (vector signed short, int, short *); 18171void vec_stvehx (vector unsigned short, int, unsigned short *); 18172void vec_stvehx (vector bool short, int, short *); 18173void vec_stvehx (vector bool short, int, unsigned short *); 18174void vec_stvehx (vector pixel, int, short *); 18175void vec_stvehx (vector pixel, int, unsigned short *); 18176 18177void vec_stvebx (vector signed char, int, signed char *); 18178void vec_stvebx (vector unsigned char, int, unsigned char *); 18179void vec_stvebx (vector bool char, int, signed char *); 18180void vec_stvebx (vector bool char, int, unsigned char *); 18181 18182void vec_stl (vector float, int, vector float *); 18183void vec_stl (vector float, int, float *); 18184void vec_stl (vector signed int, int, vector signed int *); 18185void vec_stl (vector signed int, int, int *); 18186void vec_stl (vector unsigned int, int, vector unsigned int *); 18187void vec_stl (vector unsigned int, int, unsigned int *); 18188void vec_stl (vector bool int, int, vector bool int *); 18189void vec_stl (vector bool int, int, unsigned int *); 18190void vec_stl (vector bool int, int, int *); 18191void vec_stl (vector signed short, int, vector signed short *); 18192void vec_stl (vector signed short, int, short *); 18193void vec_stl (vector unsigned short, int, vector unsigned short *); 18194void vec_stl (vector unsigned short, int, unsigned short *); 18195void vec_stl (vector bool short, int, vector bool short *); 18196void vec_stl (vector bool short, int, unsigned short *); 18197void vec_stl (vector bool short, int, short *); 18198void vec_stl (vector pixel, int, vector pixel *); 18199void vec_stl (vector pixel, int, unsigned short *); 18200void vec_stl (vector pixel, int, short *); 18201void vec_stl (vector signed char, int, vector signed char *); 18202void vec_stl (vector signed char, int, signed char *); 18203void vec_stl (vector unsigned char, int, vector unsigned char *); 18204void vec_stl (vector unsigned char, int, unsigned char *); 18205void vec_stl (vector bool char, int, vector bool char *); 18206void vec_stl (vector bool char, int, unsigned char *); 18207void vec_stl (vector bool char, int, signed char *); 18208 18209vector signed char vec_sub (vector bool char, vector signed char); 18210vector signed char vec_sub (vector signed char, vector bool char); 18211vector signed char vec_sub (vector signed char, vector signed char); 18212vector unsigned char vec_sub (vector bool char, vector unsigned char); 18213vector unsigned char vec_sub (vector unsigned char, vector bool char); 18214vector unsigned char vec_sub (vector unsigned char, 18215 vector unsigned char); 18216vector signed short vec_sub (vector bool short, vector signed short); 18217vector signed short vec_sub (vector signed short, vector bool short); 18218vector signed short vec_sub (vector signed short, vector signed short); 18219vector unsigned short vec_sub (vector bool short, 18220 vector unsigned short); 18221vector unsigned short vec_sub (vector unsigned short, 18222 vector bool short); 18223vector unsigned short vec_sub (vector unsigned short, 18224 vector unsigned short); 18225vector signed int vec_sub (vector bool int, vector signed int); 18226vector signed int vec_sub (vector signed int, vector bool int); 18227vector signed int vec_sub (vector signed int, vector signed int); 18228vector unsigned int vec_sub (vector bool int, vector unsigned int); 18229vector unsigned int vec_sub (vector unsigned int, vector bool int); 18230vector unsigned int vec_sub (vector unsigned int, vector unsigned int); 18231vector float vec_sub (vector float, vector float); 18232 18233vector float vec_vsubfp (vector float, vector float); 18234 18235vector signed int vec_vsubuwm (vector bool int, vector signed int); 18236vector signed int vec_vsubuwm (vector signed int, vector bool int); 18237vector signed int vec_vsubuwm (vector signed int, vector signed int); 18238vector unsigned int vec_vsubuwm (vector bool int, vector unsigned int); 18239vector unsigned int vec_vsubuwm (vector unsigned int, vector bool int); 18240vector unsigned int vec_vsubuwm (vector unsigned int, 18241 vector unsigned int); 18242 18243vector signed short vec_vsubuhm (vector bool short, 18244 vector signed short); 18245vector signed short vec_vsubuhm (vector signed short, 18246 vector bool short); 18247vector signed short vec_vsubuhm (vector signed short, 18248 vector signed short); 18249vector unsigned short vec_vsubuhm (vector bool short, 18250 vector unsigned short); 18251vector unsigned short vec_vsubuhm (vector unsigned short, 18252 vector bool short); 18253vector unsigned short vec_vsubuhm (vector unsigned short, 18254 vector unsigned short); 18255 18256vector signed char vec_vsububm (vector bool char, vector signed char); 18257vector signed char vec_vsububm (vector signed char, vector bool char); 18258vector signed char vec_vsububm (vector signed char, vector signed char); 18259vector unsigned char vec_vsububm (vector bool char, 18260 vector unsigned char); 18261vector unsigned char vec_vsububm (vector unsigned char, 18262 vector bool char); 18263vector unsigned char vec_vsububm (vector unsigned char, 18264 vector unsigned char); 18265 18266vector signed int vec_subc (vector signed int, vector signed int); 18267vector unsigned int vec_subc (vector unsigned int, vector unsigned int); 18268vector signed __int128 vec_subc (vector signed __int128, 18269 vector signed __int128); 18270vector unsigned __int128 vec_subc (vector unsigned __int128, 18271 vector unsigned __int128); 18272 18273vector signed int vec_sube (vector signed int, vector signed int, 18274 vector signed int); 18275vector unsigned int vec_sube (vector unsigned int, vector unsigned int, 18276 vector unsigned int); 18277vector signed __int128 vec_sube (vector signed __int128, 18278 vector signed __int128, 18279 vector signed __int128); 18280vector unsigned __int128 vec_sube (vector unsigned __int128, 18281 vector unsigned __int128, 18282 vector unsigned __int128); 18283 18284vector signed int vec_subec (vector signed int, vector signed int, 18285 vector signed int); 18286vector unsigned int vec_subec (vector unsigned int, vector unsigned int, 18287 vector unsigned int); 18288vector signed __int128 vec_subec (vector signed __int128, 18289 vector signed __int128, 18290 vector signed __int128); 18291vector unsigned __int128 vec_subec (vector unsigned __int128, 18292 vector unsigned __int128, 18293 vector unsigned __int128); 18294 18295vector unsigned char vec_subs (vector bool char, vector unsigned char); 18296vector unsigned char vec_subs (vector unsigned char, vector bool char); 18297vector unsigned char vec_subs (vector unsigned char, 18298 vector unsigned char); 18299vector signed char vec_subs (vector bool char, vector signed char); 18300vector signed char vec_subs (vector signed char, vector bool char); 18301vector signed char vec_subs (vector signed char, vector signed char); 18302vector unsigned short vec_subs (vector bool short, 18303 vector unsigned short); 18304vector unsigned short vec_subs (vector unsigned short, 18305 vector bool short); 18306vector unsigned short vec_subs (vector unsigned short, 18307 vector unsigned short); 18308vector signed short vec_subs (vector bool short, vector signed short); 18309vector signed short vec_subs (vector signed short, vector bool short); 18310vector signed short vec_subs (vector signed short, vector signed short); 18311vector unsigned int vec_subs (vector bool int, vector unsigned int); 18312vector unsigned int vec_subs (vector unsigned int, vector bool int); 18313vector unsigned int vec_subs (vector unsigned int, vector unsigned int); 18314vector signed int vec_subs (vector bool int, vector signed int); 18315vector signed int vec_subs (vector signed int, vector bool int); 18316vector signed int vec_subs (vector signed int, vector signed int); 18317 18318vector signed int vec_vsubsws (vector bool int, vector signed int); 18319vector signed int vec_vsubsws (vector signed int, vector bool int); 18320vector signed int vec_vsubsws (vector signed int, vector signed int); 18321 18322vector unsigned int vec_vsubuws (vector bool int, vector unsigned int); 18323vector unsigned int vec_vsubuws (vector unsigned int, vector bool int); 18324vector unsigned int vec_vsubuws (vector unsigned int, 18325 vector unsigned int); 18326 18327vector signed short vec_vsubshs (vector bool short, 18328 vector signed short); 18329vector signed short vec_vsubshs (vector signed short, 18330 vector bool short); 18331vector signed short vec_vsubshs (vector signed short, 18332 vector signed short); 18333 18334vector unsigned short vec_vsubuhs (vector bool short, 18335 vector unsigned short); 18336vector unsigned short vec_vsubuhs (vector unsigned short, 18337 vector bool short); 18338vector unsigned short vec_vsubuhs (vector unsigned short, 18339 vector unsigned short); 18340 18341vector signed char vec_vsubsbs (vector bool char, vector signed char); 18342vector signed char vec_vsubsbs (vector signed char, vector bool char); 18343vector signed char vec_vsubsbs (vector signed char, vector signed char); 18344 18345vector unsigned char vec_vsububs (vector bool char, 18346 vector unsigned char); 18347vector unsigned char vec_vsububs (vector unsigned char, 18348 vector bool char); 18349vector unsigned char vec_vsububs (vector unsigned char, 18350 vector unsigned char); 18351 18352vector unsigned int vec_sum4s (vector unsigned char, 18353 vector unsigned int); 18354vector signed int vec_sum4s (vector signed char, vector signed int); 18355vector signed int vec_sum4s (vector signed short, vector signed int); 18356 18357vector signed int vec_vsum4shs (vector signed short, vector signed int); 18358 18359vector signed int vec_vsum4sbs (vector signed char, vector signed int); 18360 18361vector unsigned int vec_vsum4ubs (vector unsigned char, 18362 vector unsigned int); 18363 18364vector signed int vec_sum2s (vector signed int, vector signed int); 18365 18366vector signed int vec_sums (vector signed int, vector signed int); 18367 18368vector float vec_trunc (vector float); 18369 18370vector signed long long vec_unsigned (vector double); 18371vector signed int vec_unsigned (vector float); 18372 18373vector signed int vec_unsignede (vector double); 18374vector signed int vec_unsignedo (vector double); 18375vector signed int vec_unsigned2 (vector double, vector double); 18376 18377vector signed short vec_unpackh (vector signed char); 18378vector bool short vec_unpackh (vector bool char); 18379vector signed int vec_unpackh (vector signed short); 18380vector bool int vec_unpackh (vector bool short); 18381vector unsigned int vec_unpackh (vector pixel); 18382vector double vec_unpackh (vector float); 18383 18384vector bool int vec_vupkhsh (vector bool short); 18385vector signed int vec_vupkhsh (vector signed short); 18386 18387vector unsigned int vec_vupkhpx (vector pixel); 18388 18389vector bool short vec_vupkhsb (vector bool char); 18390vector signed short vec_vupkhsb (vector signed char); 18391 18392vector signed short vec_unpackl (vector signed char); 18393vector bool short vec_unpackl (vector bool char); 18394vector unsigned int vec_unpackl (vector pixel); 18395vector signed int vec_unpackl (vector signed short); 18396vector bool int vec_unpackl (vector bool short); 18397vector double vec_unpackl (vector float); 18398 18399vector unsigned int vec_vupklpx (vector pixel); 18400 18401vector bool int vec_vupklsh (vector bool short); 18402vector signed int vec_vupklsh (vector signed short); 18403 18404vector bool short vec_vupklsb (vector bool char); 18405vector signed short vec_vupklsb (vector signed char); 18406 18407vector float vec_xor (vector float, vector float); 18408vector float vec_xor (vector float, vector bool int); 18409vector float vec_xor (vector bool int, vector float); 18410vector bool int vec_xor (vector bool int, vector bool int); 18411vector signed int vec_xor (vector bool int, vector signed int); 18412vector signed int vec_xor (vector signed int, vector bool int); 18413vector signed int vec_xor (vector signed int, vector signed int); 18414vector unsigned int vec_xor (vector bool int, vector unsigned int); 18415vector unsigned int vec_xor (vector unsigned int, vector bool int); 18416vector unsigned int vec_xor (vector unsigned int, vector unsigned int); 18417vector bool short vec_xor (vector bool short, vector bool short); 18418vector signed short vec_xor (vector bool short, vector signed short); 18419vector signed short vec_xor (vector signed short, vector bool short); 18420vector signed short vec_xor (vector signed short, vector signed short); 18421vector unsigned short vec_xor (vector bool short, 18422 vector unsigned short); 18423vector unsigned short vec_xor (vector unsigned short, 18424 vector bool short); 18425vector unsigned short vec_xor (vector unsigned short, 18426 vector unsigned short); 18427vector signed char vec_xor (vector bool char, vector signed char); 18428vector bool char vec_xor (vector bool char, vector bool char); 18429vector signed char vec_xor (vector signed char, vector bool char); 18430vector signed char vec_xor (vector signed char, vector signed char); 18431vector unsigned char vec_xor (vector bool char, vector unsigned char); 18432vector unsigned char vec_xor (vector unsigned char, vector bool char); 18433vector unsigned char vec_xor (vector unsigned char, 18434 vector unsigned char); 18435 18436int vec_all_eq (vector signed char, vector bool char); 18437int vec_all_eq (vector signed char, vector signed char); 18438int vec_all_eq (vector unsigned char, vector bool char); 18439int vec_all_eq (vector unsigned char, vector unsigned char); 18440int vec_all_eq (vector bool char, vector bool char); 18441int vec_all_eq (vector bool char, vector unsigned char); 18442int vec_all_eq (vector bool char, vector signed char); 18443int vec_all_eq (vector signed short, vector bool short); 18444int vec_all_eq (vector signed short, vector signed short); 18445int vec_all_eq (vector unsigned short, vector bool short); 18446int vec_all_eq (vector unsigned short, vector unsigned short); 18447int vec_all_eq (vector bool short, vector bool short); 18448int vec_all_eq (vector bool short, vector unsigned short); 18449int vec_all_eq (vector bool short, vector signed short); 18450int vec_all_eq (vector pixel, vector pixel); 18451int vec_all_eq (vector signed int, vector bool int); 18452int vec_all_eq (vector signed int, vector signed int); 18453int vec_all_eq (vector unsigned int, vector bool int); 18454int vec_all_eq (vector unsigned int, vector unsigned int); 18455int vec_all_eq (vector bool int, vector bool int); 18456int vec_all_eq (vector bool int, vector unsigned int); 18457int vec_all_eq (vector bool int, vector signed int); 18458int vec_all_eq (vector float, vector float); 18459 18460int vec_all_ge (vector bool char, vector unsigned char); 18461int vec_all_ge (vector unsigned char, vector bool char); 18462int vec_all_ge (vector unsigned char, vector unsigned char); 18463int vec_all_ge (vector bool char, vector signed char); 18464int vec_all_ge (vector signed char, vector bool char); 18465int vec_all_ge (vector signed char, vector signed char); 18466int vec_all_ge (vector bool short, vector unsigned short); 18467int vec_all_ge (vector unsigned short, vector bool short); 18468int vec_all_ge (vector unsigned short, vector unsigned short); 18469int vec_all_ge (vector signed short, vector signed short); 18470int vec_all_ge (vector bool short, vector signed short); 18471int vec_all_ge (vector signed short, vector bool short); 18472int vec_all_ge (vector bool int, vector unsigned int); 18473int vec_all_ge (vector unsigned int, vector bool int); 18474int vec_all_ge (vector unsigned int, vector unsigned int); 18475int vec_all_ge (vector bool int, vector signed int); 18476int vec_all_ge (vector signed int, vector bool int); 18477int vec_all_ge (vector signed int, vector signed int); 18478int vec_all_ge (vector float, vector float); 18479 18480int vec_all_gt (vector bool char, vector unsigned char); 18481int vec_all_gt (vector unsigned char, vector bool char); 18482int vec_all_gt (vector unsigned char, vector unsigned char); 18483int vec_all_gt (vector bool char, vector signed char); 18484int vec_all_gt (vector signed char, vector bool char); 18485int vec_all_gt (vector signed char, vector signed char); 18486int vec_all_gt (vector bool short, vector unsigned short); 18487int vec_all_gt (vector unsigned short, vector bool short); 18488int vec_all_gt (vector unsigned short, vector unsigned short); 18489int vec_all_gt (vector bool short, vector signed short); 18490int vec_all_gt (vector signed short, vector bool short); 18491int vec_all_gt (vector signed short, vector signed short); 18492int vec_all_gt (vector bool int, vector unsigned int); 18493int vec_all_gt (vector unsigned int, vector bool int); 18494int vec_all_gt (vector unsigned int, vector unsigned int); 18495int vec_all_gt (vector bool int, vector signed int); 18496int vec_all_gt (vector signed int, vector bool int); 18497int vec_all_gt (vector signed int, vector signed int); 18498int vec_all_gt (vector float, vector float); 18499 18500int vec_all_in (vector float, vector float); 18501 18502int vec_all_le (vector bool char, vector unsigned char); 18503int vec_all_le (vector unsigned char, vector bool char); 18504int vec_all_le (vector unsigned char, vector unsigned char); 18505int vec_all_le (vector bool char, vector signed char); 18506int vec_all_le (vector signed char, vector bool char); 18507int vec_all_le (vector signed char, vector signed char); 18508int vec_all_le (vector bool short, vector unsigned short); 18509int vec_all_le (vector unsigned short, vector bool short); 18510int vec_all_le (vector unsigned short, vector unsigned short); 18511int vec_all_le (vector bool short, vector signed short); 18512int vec_all_le (vector signed short, vector bool short); 18513int vec_all_le (vector signed short, vector signed short); 18514int vec_all_le (vector bool int, vector unsigned int); 18515int vec_all_le (vector unsigned int, vector bool int); 18516int vec_all_le (vector unsigned int, vector unsigned int); 18517int vec_all_le (vector bool int, vector signed int); 18518int vec_all_le (vector signed int, vector bool int); 18519int vec_all_le (vector signed int, vector signed int); 18520int vec_all_le (vector float, vector float); 18521 18522int vec_all_lt (vector bool char, vector unsigned char); 18523int vec_all_lt (vector unsigned char, vector bool char); 18524int vec_all_lt (vector unsigned char, vector unsigned char); 18525int vec_all_lt (vector bool char, vector signed char); 18526int vec_all_lt (vector signed char, vector bool char); 18527int vec_all_lt (vector signed char, vector signed char); 18528int vec_all_lt (vector bool short, vector unsigned short); 18529int vec_all_lt (vector unsigned short, vector bool short); 18530int vec_all_lt (vector unsigned short, vector unsigned short); 18531int vec_all_lt (vector bool short, vector signed short); 18532int vec_all_lt (vector signed short, vector bool short); 18533int vec_all_lt (vector signed short, vector signed short); 18534int vec_all_lt (vector bool int, vector unsigned int); 18535int vec_all_lt (vector unsigned int, vector bool int); 18536int vec_all_lt (vector unsigned int, vector unsigned int); 18537int vec_all_lt (vector bool int, vector signed int); 18538int vec_all_lt (vector signed int, vector bool int); 18539int vec_all_lt (vector signed int, vector signed int); 18540int vec_all_lt (vector float, vector float); 18541 18542int vec_all_nan (vector float); 18543 18544int vec_all_ne (vector signed char, vector bool char); 18545int vec_all_ne (vector signed char, vector signed char); 18546int vec_all_ne (vector unsigned char, vector bool char); 18547int vec_all_ne (vector unsigned char, vector unsigned char); 18548int vec_all_ne (vector bool char, vector bool char); 18549int vec_all_ne (vector bool char, vector unsigned char); 18550int vec_all_ne (vector bool char, vector signed char); 18551int vec_all_ne (vector signed short, vector bool short); 18552int vec_all_ne (vector signed short, vector signed short); 18553int vec_all_ne (vector unsigned short, vector bool short); 18554int vec_all_ne (vector unsigned short, vector unsigned short); 18555int vec_all_ne (vector bool short, vector bool short); 18556int vec_all_ne (vector bool short, vector unsigned short); 18557int vec_all_ne (vector bool short, vector signed short); 18558int vec_all_ne (vector pixel, vector pixel); 18559int vec_all_ne (vector signed int, vector bool int); 18560int vec_all_ne (vector signed int, vector signed int); 18561int vec_all_ne (vector unsigned int, vector bool int); 18562int vec_all_ne (vector unsigned int, vector unsigned int); 18563int vec_all_ne (vector bool int, vector bool int); 18564int vec_all_ne (vector bool int, vector unsigned int); 18565int vec_all_ne (vector bool int, vector signed int); 18566int vec_all_ne (vector float, vector float); 18567 18568int vec_all_nge (vector float, vector float); 18569 18570int vec_all_ngt (vector float, vector float); 18571 18572int vec_all_nle (vector float, vector float); 18573 18574int vec_all_nlt (vector float, vector float); 18575 18576int vec_all_numeric (vector float); 18577 18578int vec_any_eq (vector signed char, vector bool char); 18579int vec_any_eq (vector signed char, vector signed char); 18580int vec_any_eq (vector unsigned char, vector bool char); 18581int vec_any_eq (vector unsigned char, vector unsigned char); 18582int vec_any_eq (vector bool char, vector bool char); 18583int vec_any_eq (vector bool char, vector unsigned char); 18584int vec_any_eq (vector bool char, vector signed char); 18585int vec_any_eq (vector signed short, vector bool short); 18586int vec_any_eq (vector signed short, vector signed short); 18587int vec_any_eq (vector unsigned short, vector bool short); 18588int vec_any_eq (vector unsigned short, vector unsigned short); 18589int vec_any_eq (vector bool short, vector bool short); 18590int vec_any_eq (vector bool short, vector unsigned short); 18591int vec_any_eq (vector bool short, vector signed short); 18592int vec_any_eq (vector pixel, vector pixel); 18593int vec_any_eq (vector signed int, vector bool int); 18594int vec_any_eq (vector signed int, vector signed int); 18595int vec_any_eq (vector unsigned int, vector bool int); 18596int vec_any_eq (vector unsigned int, vector unsigned int); 18597int vec_any_eq (vector bool int, vector bool int); 18598int vec_any_eq (vector bool int, vector unsigned int); 18599int vec_any_eq (vector bool int, vector signed int); 18600int vec_any_eq (vector float, vector float); 18601 18602int vec_any_ge (vector signed char, vector bool char); 18603int vec_any_ge (vector unsigned char, vector bool char); 18604int vec_any_ge (vector unsigned char, vector unsigned char); 18605int vec_any_ge (vector signed char, vector signed char); 18606int vec_any_ge (vector bool char, vector unsigned char); 18607int vec_any_ge (vector bool char, vector signed char); 18608int vec_any_ge (vector unsigned short, vector bool short); 18609int vec_any_ge (vector unsigned short, vector unsigned short); 18610int vec_any_ge (vector signed short, vector signed short); 18611int vec_any_ge (vector signed short, vector bool short); 18612int vec_any_ge (vector bool short, vector unsigned short); 18613int vec_any_ge (vector bool short, vector signed short); 18614int vec_any_ge (vector signed int, vector bool int); 18615int vec_any_ge (vector unsigned int, vector bool int); 18616int vec_any_ge (vector unsigned int, vector unsigned int); 18617int vec_any_ge (vector signed int, vector signed int); 18618int vec_any_ge (vector bool int, vector unsigned int); 18619int vec_any_ge (vector bool int, vector signed int); 18620int vec_any_ge (vector float, vector float); 18621 18622int vec_any_gt (vector bool char, vector unsigned char); 18623int vec_any_gt (vector unsigned char, vector bool char); 18624int vec_any_gt (vector unsigned char, vector unsigned char); 18625int vec_any_gt (vector bool char, vector signed char); 18626int vec_any_gt (vector signed char, vector bool char); 18627int vec_any_gt (vector signed char, vector signed char); 18628int vec_any_gt (vector bool short, vector unsigned short); 18629int vec_any_gt (vector unsigned short, vector bool short); 18630int vec_any_gt (vector unsigned short, vector unsigned short); 18631int vec_any_gt (vector bool short, vector signed short); 18632int vec_any_gt (vector signed short, vector bool short); 18633int vec_any_gt (vector signed short, vector signed short); 18634int vec_any_gt (vector bool int, vector unsigned int); 18635int vec_any_gt (vector unsigned int, vector bool int); 18636int vec_any_gt (vector unsigned int, vector unsigned int); 18637int vec_any_gt (vector bool int, vector signed int); 18638int vec_any_gt (vector signed int, vector bool int); 18639int vec_any_gt (vector signed int, vector signed int); 18640int vec_any_gt (vector float, vector float); 18641 18642int vec_any_le (vector bool char, vector unsigned char); 18643int vec_any_le (vector unsigned char, vector bool char); 18644int vec_any_le (vector unsigned char, vector unsigned char); 18645int vec_any_le (vector bool char, vector signed char); 18646int vec_any_le (vector signed char, vector bool char); 18647int vec_any_le (vector signed char, vector signed char); 18648int vec_any_le (vector bool short, vector unsigned short); 18649int vec_any_le (vector unsigned short, vector bool short); 18650int vec_any_le (vector unsigned short, vector unsigned short); 18651int vec_any_le (vector bool short, vector signed short); 18652int vec_any_le (vector signed short, vector bool short); 18653int vec_any_le (vector signed short, vector signed short); 18654int vec_any_le (vector bool int, vector unsigned int); 18655int vec_any_le (vector unsigned int, vector bool int); 18656int vec_any_le (vector unsigned int, vector unsigned int); 18657int vec_any_le (vector bool int, vector signed int); 18658int vec_any_le (vector signed int, vector bool int); 18659int vec_any_le (vector signed int, vector signed int); 18660int vec_any_le (vector float, vector float); 18661 18662int vec_any_lt (vector bool char, vector unsigned char); 18663int vec_any_lt (vector unsigned char, vector bool char); 18664int vec_any_lt (vector unsigned char, vector unsigned char); 18665int vec_any_lt (vector bool char, vector signed char); 18666int vec_any_lt (vector signed char, vector bool char); 18667int vec_any_lt (vector signed char, vector signed char); 18668int vec_any_lt (vector bool short, vector unsigned short); 18669int vec_any_lt (vector unsigned short, vector bool short); 18670int vec_any_lt (vector unsigned short, vector unsigned short); 18671int vec_any_lt (vector bool short, vector signed short); 18672int vec_any_lt (vector signed short, vector bool short); 18673int vec_any_lt (vector signed short, vector signed short); 18674int vec_any_lt (vector bool int, vector unsigned int); 18675int vec_any_lt (vector unsigned int, vector bool int); 18676int vec_any_lt (vector unsigned int, vector unsigned int); 18677int vec_any_lt (vector bool int, vector signed int); 18678int vec_any_lt (vector signed int, vector bool int); 18679int vec_any_lt (vector signed int, vector signed int); 18680int vec_any_lt (vector float, vector float); 18681 18682int vec_any_nan (vector float); 18683 18684int vec_any_ne (vector signed char, vector bool char); 18685int vec_any_ne (vector signed char, vector signed char); 18686int vec_any_ne (vector unsigned char, vector bool char); 18687int vec_any_ne (vector unsigned char, vector unsigned char); 18688int vec_any_ne (vector bool char, vector bool char); 18689int vec_any_ne (vector bool char, vector unsigned char); 18690int vec_any_ne (vector bool char, vector signed char); 18691int vec_any_ne (vector signed short, vector bool short); 18692int vec_any_ne (vector signed short, vector signed short); 18693int vec_any_ne (vector unsigned short, vector bool short); 18694int vec_any_ne (vector unsigned short, vector unsigned short); 18695int vec_any_ne (vector bool short, vector bool short); 18696int vec_any_ne (vector bool short, vector unsigned short); 18697int vec_any_ne (vector bool short, vector signed short); 18698int vec_any_ne (vector pixel, vector pixel); 18699int vec_any_ne (vector signed int, vector bool int); 18700int vec_any_ne (vector signed int, vector signed int); 18701int vec_any_ne (vector unsigned int, vector bool int); 18702int vec_any_ne (vector unsigned int, vector unsigned int); 18703int vec_any_ne (vector bool int, vector bool int); 18704int vec_any_ne (vector bool int, vector unsigned int); 18705int vec_any_ne (vector bool int, vector signed int); 18706int vec_any_ne (vector float, vector float); 18707 18708int vec_any_nge (vector float, vector float); 18709 18710int vec_any_ngt (vector float, vector float); 18711 18712int vec_any_nle (vector float, vector float); 18713 18714int vec_any_nlt (vector float, vector float); 18715 18716int vec_any_numeric (vector float); 18717 18718int vec_any_out (vector float, vector float); 18719@end smallexample 18720 18721If the vector/scalar (VSX) instruction set is available, the following 18722additional functions are available: 18723 18724@smallexample 18725vector double vec_abs (vector double); 18726vector double vec_add (vector double, vector double); 18727vector double vec_and (vector double, vector double); 18728vector double vec_and (vector double, vector bool long); 18729vector double vec_and (vector bool long, vector double); 18730vector long vec_and (vector long, vector long); 18731vector long vec_and (vector long, vector bool long); 18732vector long vec_and (vector bool long, vector long); 18733vector unsigned long vec_and (vector unsigned long, vector unsigned long); 18734vector unsigned long vec_and (vector unsigned long, vector bool long); 18735vector unsigned long vec_and (vector bool long, vector unsigned long); 18736vector double vec_andc (vector double, vector double); 18737vector double vec_andc (vector double, vector bool long); 18738vector double vec_andc (vector bool long, vector double); 18739vector long vec_andc (vector long, vector long); 18740vector long vec_andc (vector long, vector bool long); 18741vector long vec_andc (vector bool long, vector long); 18742vector unsigned long vec_andc (vector unsigned long, vector unsigned long); 18743vector unsigned long vec_andc (vector unsigned long, vector bool long); 18744vector unsigned long vec_andc (vector bool long, vector unsigned long); 18745vector double vec_ceil (vector double); 18746vector bool long vec_cmpeq (vector double, vector double); 18747vector bool long vec_cmpge (vector double, vector double); 18748vector bool long vec_cmpgt (vector double, vector double); 18749vector bool long vec_cmple (vector double, vector double); 18750vector bool long vec_cmplt (vector double, vector double); 18751vector double vec_cpsgn (vector double, vector double); 18752vector float vec_div (vector float, vector float); 18753vector double vec_div (vector double, vector double); 18754vector long vec_div (vector long, vector long); 18755vector unsigned long vec_div (vector unsigned long, vector unsigned long); 18756vector double vec_floor (vector double); 18757vector signed long long vec_ld (int, const vector signed long long *); 18758vector signed long long vec_ld (int, const signed long long *); 18759vector unsigned long long vec_ld (int, const vector unsigned long long *); 18760vector unsigned long long vec_ld (int, const unsigned long long *); 18761vector __int128 vec_ld (int, const vector __int128 *); 18762vector unsigned __int128 vec_ld (int, const vector unsigned __int128 *); 18763vector __int128 vec_ld (int, const __int128 *); 18764vector unsigned __int128 vec_ld (int, const unsigned __int128 *); 18765vector double vec_ld (int, const vector double *); 18766vector double vec_ld (int, const double *); 18767vector double vec_ldl (int, const vector double *); 18768vector double vec_ldl (int, const double *); 18769vector unsigned char vec_lvsl (int, const volatile double *); 18770vector unsigned char vec_lvsr (int, const volatile double *); 18771vector double vec_madd (vector double, vector double, vector double); 18772vector double vec_max (vector double, vector double); 18773vector signed long vec_mergeh (vector signed long, vector signed long); 18774vector signed long vec_mergeh (vector signed long, vector bool long); 18775vector signed long vec_mergeh (vector bool long, vector signed long); 18776vector unsigned long vec_mergeh (vector unsigned long, vector unsigned long); 18777vector unsigned long vec_mergeh (vector unsigned long, vector bool long); 18778vector unsigned long vec_mergeh (vector bool long, vector unsigned long); 18779vector signed long vec_mergel (vector signed long, vector signed long); 18780vector signed long vec_mergel (vector signed long, vector bool long); 18781vector signed long vec_mergel (vector bool long, vector signed long); 18782vector unsigned long vec_mergel (vector unsigned long, vector unsigned long); 18783vector unsigned long vec_mergel (vector unsigned long, vector bool long); 18784vector unsigned long vec_mergel (vector bool long, vector unsigned long); 18785vector double vec_min (vector double, vector double); 18786vector float vec_msub (vector float, vector float, vector float); 18787vector double vec_msub (vector double, vector double, vector double); 18788vector float vec_mul (vector float, vector float); 18789vector double vec_mul (vector double, vector double); 18790vector long vec_mul (vector long, vector long); 18791vector unsigned long vec_mul (vector unsigned long, vector unsigned long); 18792vector float vec_nearbyint (vector float); 18793vector double vec_nearbyint (vector double); 18794vector float vec_nmadd (vector float, vector float, vector float); 18795vector double vec_nmadd (vector double, vector double, vector double); 18796vector double vec_nmsub (vector double, vector double, vector double); 18797vector double vec_nor (vector double, vector double); 18798vector long vec_nor (vector long, vector long); 18799vector long vec_nor (vector long, vector bool long); 18800vector long vec_nor (vector bool long, vector long); 18801vector unsigned long vec_nor (vector unsigned long, vector unsigned long); 18802vector unsigned long vec_nor (vector unsigned long, vector bool long); 18803vector unsigned long vec_nor (vector bool long, vector unsigned long); 18804vector double vec_or (vector double, vector double); 18805vector double vec_or (vector double, vector bool long); 18806vector double vec_or (vector bool long, vector double); 18807vector long vec_or (vector long, vector long); 18808vector long vec_or (vector long, vector bool long); 18809vector long vec_or (vector bool long, vector long); 18810vector unsigned long vec_or (vector unsigned long, vector unsigned long); 18811vector unsigned long vec_or (vector unsigned long, vector bool long); 18812vector unsigned long vec_or (vector bool long, vector unsigned long); 18813vector double vec_perm (vector double, vector double, vector unsigned char); 18814vector long vec_perm (vector long, vector long, vector unsigned char); 18815vector unsigned long vec_perm (vector unsigned long, vector unsigned long, 18816 vector unsigned char); 18817vector bool char vec_permxor (vector bool char, vector bool char, 18818 vector bool char); 18819vector unsigned char vec_permxor (vector signed char, vector signed char, 18820 vector signed char); 18821vector unsigned char vec_permxor (vector unsigned char, vector unsigned char, 18822 vector unsigned char); 18823vector double vec_rint (vector double); 18824vector double vec_recip (vector double, vector double); 18825vector double vec_rsqrt (vector double); 18826vector double vec_rsqrte (vector double); 18827vector double vec_sel (vector double, vector double, vector bool long); 18828vector double vec_sel (vector double, vector double, vector unsigned long); 18829vector long vec_sel (vector long, vector long, vector long); 18830vector long vec_sel (vector long, vector long, vector unsigned long); 18831vector long vec_sel (vector long, vector long, vector bool long); 18832vector unsigned long vec_sel (vector unsigned long, vector unsigned long, 18833 vector long); 18834vector unsigned long vec_sel (vector unsigned long, vector unsigned long, 18835 vector unsigned long); 18836vector unsigned long vec_sel (vector unsigned long, vector unsigned long, 18837 vector bool long); 18838vector double vec_splats (double); 18839vector signed long vec_splats (signed long); 18840vector unsigned long vec_splats (unsigned long); 18841vector float vec_sqrt (vector float); 18842vector double vec_sqrt (vector double); 18843void vec_st (vector signed long long, int, vector signed long long *); 18844void vec_st (vector signed long long, int, signed long long *); 18845void vec_st (vector unsigned long long, int, vector unsigned long long *); 18846void vec_st (vector unsigned long long, int, unsigned long long *); 18847void vec_st (vector bool long long, int, vector bool long long *); 18848void vec_st (vector bool long long, int, signed long long *); 18849void vec_st (vector bool long long, int, unsigned long long *); 18850void vec_st (vector double, int, vector double *); 18851void vec_st (vector double, int, double *); 18852vector double vec_sub (vector double, vector double); 18853vector double vec_trunc (vector double); 18854vector double vec_xl (int, vector double *); 18855vector double vec_xl (int, double *); 18856vector long long vec_xl (int, vector long long *); 18857vector long long vec_xl (int, long long *); 18858vector unsigned long long vec_xl (int, vector unsigned long long *); 18859vector unsigned long long vec_xl (int, unsigned long long *); 18860vector float vec_xl (int, vector float *); 18861vector float vec_xl (int, float *); 18862vector int vec_xl (int, vector int *); 18863vector int vec_xl (int, int *); 18864vector unsigned int vec_xl (int, vector unsigned int *); 18865vector unsigned int vec_xl (int, unsigned int *); 18866vector double vec_xor (vector double, vector double); 18867vector double vec_xor (vector double, vector bool long); 18868vector double vec_xor (vector bool long, vector double); 18869vector long vec_xor (vector long, vector long); 18870vector long vec_xor (vector long, vector bool long); 18871vector long vec_xor (vector bool long, vector long); 18872vector unsigned long vec_xor (vector unsigned long, vector unsigned long); 18873vector unsigned long vec_xor (vector unsigned long, vector bool long); 18874vector unsigned long vec_xor (vector bool long, vector unsigned long); 18875void vec_xst (vector double, int, vector double *); 18876void vec_xst (vector double, int, double *); 18877void vec_xst (vector long long, int, vector long long *); 18878void vec_xst (vector long long, int, long long *); 18879void vec_xst (vector unsigned long long, int, vector unsigned long long *); 18880void vec_xst (vector unsigned long long, int, unsigned long long *); 18881void vec_xst (vector float, int, vector float *); 18882void vec_xst (vector float, int, float *); 18883void vec_xst (vector int, int, vector int *); 18884void vec_xst (vector int, int, int *); 18885void vec_xst (vector unsigned int, int, vector unsigned int *); 18886void vec_xst (vector unsigned int, int, unsigned int *); 18887int vec_all_eq (vector double, vector double); 18888int vec_all_ge (vector double, vector double); 18889int vec_all_gt (vector double, vector double); 18890int vec_all_le (vector double, vector double); 18891int vec_all_lt (vector double, vector double); 18892int vec_all_nan (vector double); 18893int vec_all_ne (vector double, vector double); 18894int vec_all_nge (vector double, vector double); 18895int vec_all_ngt (vector double, vector double); 18896int vec_all_nle (vector double, vector double); 18897int vec_all_nlt (vector double, vector double); 18898int vec_all_numeric (vector double); 18899int vec_any_eq (vector double, vector double); 18900int vec_any_ge (vector double, vector double); 18901int vec_any_gt (vector double, vector double); 18902int vec_any_le (vector double, vector double); 18903int vec_any_lt (vector double, vector double); 18904int vec_any_nan (vector double); 18905int vec_any_ne (vector double, vector double); 18906int vec_any_nge (vector double, vector double); 18907int vec_any_ngt (vector double, vector double); 18908int vec_any_nle (vector double, vector double); 18909int vec_any_nlt (vector double, vector double); 18910int vec_any_numeric (vector double); 18911 18912vector double vec_vsx_ld (int, const vector double *); 18913vector double vec_vsx_ld (int, const double *); 18914vector float vec_vsx_ld (int, const vector float *); 18915vector float vec_vsx_ld (int, const float *); 18916vector bool int vec_vsx_ld (int, const vector bool int *); 18917vector signed int vec_vsx_ld (int, const vector signed int *); 18918vector signed int vec_vsx_ld (int, const int *); 18919vector signed int vec_vsx_ld (int, const long *); 18920vector unsigned int vec_vsx_ld (int, const vector unsigned int *); 18921vector unsigned int vec_vsx_ld (int, const unsigned int *); 18922vector unsigned int vec_vsx_ld (int, const unsigned long *); 18923vector bool short vec_vsx_ld (int, const vector bool short *); 18924vector pixel vec_vsx_ld (int, const vector pixel *); 18925vector signed short vec_vsx_ld (int, const vector signed short *); 18926vector signed short vec_vsx_ld (int, const short *); 18927vector unsigned short vec_vsx_ld (int, const vector unsigned short *); 18928vector unsigned short vec_vsx_ld (int, const unsigned short *); 18929vector bool char vec_vsx_ld (int, const vector bool char *); 18930vector signed char vec_vsx_ld (int, const vector signed char *); 18931vector signed char vec_vsx_ld (int, const signed char *); 18932vector unsigned char vec_vsx_ld (int, const vector unsigned char *); 18933vector unsigned char vec_vsx_ld (int, const unsigned char *); 18934 18935void vec_vsx_st (vector double, int, vector double *); 18936void vec_vsx_st (vector double, int, double *); 18937void vec_vsx_st (vector float, int, vector float *); 18938void vec_vsx_st (vector float, int, float *); 18939void vec_vsx_st (vector signed int, int, vector signed int *); 18940void vec_vsx_st (vector signed int, int, int *); 18941void vec_vsx_st (vector unsigned int, int, vector unsigned int *); 18942void vec_vsx_st (vector unsigned int, int, unsigned int *); 18943void vec_vsx_st (vector bool int, int, vector bool int *); 18944void vec_vsx_st (vector bool int, int, unsigned int *); 18945void vec_vsx_st (vector bool int, int, int *); 18946void vec_vsx_st (vector signed short, int, vector signed short *); 18947void vec_vsx_st (vector signed short, int, short *); 18948void vec_vsx_st (vector unsigned short, int, vector unsigned short *); 18949void vec_vsx_st (vector unsigned short, int, unsigned short *); 18950void vec_vsx_st (vector bool short, int, vector bool short *); 18951void vec_vsx_st (vector bool short, int, unsigned short *); 18952void vec_vsx_st (vector pixel, int, vector pixel *); 18953void vec_vsx_st (vector pixel, int, unsigned short *); 18954void vec_vsx_st (vector pixel, int, short *); 18955void vec_vsx_st (vector bool short, int, short *); 18956void vec_vsx_st (vector signed char, int, vector signed char *); 18957void vec_vsx_st (vector signed char, int, signed char *); 18958void vec_vsx_st (vector unsigned char, int, vector unsigned char *); 18959void vec_vsx_st (vector unsigned char, int, unsigned char *); 18960void vec_vsx_st (vector bool char, int, vector bool char *); 18961void vec_vsx_st (vector bool char, int, unsigned char *); 18962void vec_vsx_st (vector bool char, int, signed char *); 18963 18964vector double vec_xxpermdi (vector double, vector double, const int); 18965vector float vec_xxpermdi (vector float, vector float, const int); 18966vector long long vec_xxpermdi (vector long long, vector long long, const int); 18967vector unsigned long long vec_xxpermdi (vector unsigned long long, 18968 vector unsigned long long, const int); 18969vector int vec_xxpermdi (vector int, vector int, const int); 18970vector unsigned int vec_xxpermdi (vector unsigned int, 18971 vector unsigned int, const int); 18972vector short vec_xxpermdi (vector short, vector short, const int); 18973vector unsigned short vec_xxpermdi (vector unsigned short, 18974 vector unsigned short, const int); 18975vector signed char vec_xxpermdi (vector signed char, vector signed char, 18976 const int); 18977vector unsigned char vec_xxpermdi (vector unsigned char, 18978 vector unsigned char, const int); 18979 18980vector double vec_xxsldi (vector double, vector double, int); 18981vector float vec_xxsldi (vector float, vector float, int); 18982vector long long vec_xxsldi (vector long long, vector long long, int); 18983vector unsigned long long vec_xxsldi (vector unsigned long long, 18984 vector unsigned long long, int); 18985vector int vec_xxsldi (vector int, vector int, int); 18986vector unsigned int vec_xxsldi (vector unsigned int, vector unsigned int, int); 18987vector short vec_xxsldi (vector short, vector short, int); 18988vector unsigned short vec_xxsldi (vector unsigned short, 18989 vector unsigned short, int); 18990vector signed char vec_xxsldi (vector signed char, vector signed char, int); 18991vector unsigned char vec_xxsldi (vector unsigned char, 18992 vector unsigned char, int); 18993@end smallexample 18994 18995Note that the @samp{vec_ld} and @samp{vec_st} built-in functions always 18996generate the AltiVec @samp{LVX} and @samp{STVX} instructions even 18997if the VSX instruction set is available. The @samp{vec_vsx_ld} and 18998@samp{vec_vsx_st} built-in functions always generate the VSX @samp{LXVD2X}, 18999@samp{LXVW4X}, @samp{STXVD2X}, and @samp{STXVW4X} instructions. 19000 19001If the ISA 2.07 additions to the vector/scalar (power8-vector) 19002instruction set are available, the following additional functions are 19003available for both 32-bit and 64-bit targets. For 64-bit targets, you 19004can use @var{vector long} instead of @var{vector long long}, 19005@var{vector bool long} instead of @var{vector bool long long}, and 19006@var{vector unsigned long} instead of @var{vector unsigned long long}. 19007 19008@smallexample 19009vector long long vec_abs (vector long long); 19010 19011vector long long vec_add (vector long long, vector long long); 19012vector unsigned long long vec_add (vector unsigned long long, 19013 vector unsigned long long); 19014 19015int vec_all_eq (vector long long, vector long long); 19016int vec_all_eq (vector unsigned long long, vector unsigned long long); 19017int vec_all_ge (vector long long, vector long long); 19018int vec_all_ge (vector unsigned long long, vector unsigned long long); 19019int vec_all_gt (vector long long, vector long long); 19020int vec_all_gt (vector unsigned long long, vector unsigned long long); 19021int vec_all_le (vector long long, vector long long); 19022int vec_all_le (vector unsigned long long, vector unsigned long long); 19023int vec_all_lt (vector long long, vector long long); 19024int vec_all_lt (vector unsigned long long, vector unsigned long long); 19025int vec_all_ne (vector long long, vector long long); 19026int vec_all_ne (vector unsigned long long, vector unsigned long long); 19027 19028int vec_any_eq (vector long long, vector long long); 19029int vec_any_eq (vector unsigned long long, vector unsigned long long); 19030int vec_any_ge (vector long long, vector long long); 19031int vec_any_ge (vector unsigned long long, vector unsigned long long); 19032int vec_any_gt (vector long long, vector long long); 19033int vec_any_gt (vector unsigned long long, vector unsigned long long); 19034int vec_any_le (vector long long, vector long long); 19035int vec_any_le (vector unsigned long long, vector unsigned long long); 19036int vec_any_lt (vector long long, vector long long); 19037int vec_any_lt (vector unsigned long long, vector unsigned long long); 19038int vec_any_ne (vector long long, vector long long); 19039int vec_any_ne (vector unsigned long long, vector unsigned long long); 19040 19041vector bool long long vec_cmpeq (vector bool long long, vector bool long long); 19042 19043vector long long vec_eqv (vector long long, vector long long); 19044vector long long vec_eqv (vector bool long long, vector long long); 19045vector long long vec_eqv (vector long long, vector bool long long); 19046vector unsigned long long vec_eqv (vector unsigned long long, 19047 vector unsigned long long); 19048vector unsigned long long vec_eqv (vector bool long long, 19049 vector unsigned long long); 19050vector unsigned long long vec_eqv (vector unsigned long long, 19051 vector bool long long); 19052vector int vec_eqv (vector int, vector int); 19053vector int vec_eqv (vector bool int, vector int); 19054vector int vec_eqv (vector int, vector bool int); 19055vector unsigned int vec_eqv (vector unsigned int, vector unsigned int); 19056vector unsigned int vec_eqv (vector bool unsigned int, 19057 vector unsigned int); 19058vector unsigned int vec_eqv (vector unsigned int, 19059 vector bool unsigned int); 19060vector short vec_eqv (vector short, vector short); 19061vector short vec_eqv (vector bool short, vector short); 19062vector short vec_eqv (vector short, vector bool short); 19063vector unsigned short vec_eqv (vector unsigned short, vector unsigned short); 19064vector unsigned short vec_eqv (vector bool unsigned short, 19065 vector unsigned short); 19066vector unsigned short vec_eqv (vector unsigned short, 19067 vector bool unsigned short); 19068vector signed char vec_eqv (vector signed char, vector signed char); 19069vector signed char vec_eqv (vector bool signed char, vector signed char); 19070vector signed char vec_eqv (vector signed char, vector bool signed char); 19071vector unsigned char vec_eqv (vector unsigned char, vector unsigned char); 19072vector unsigned char vec_eqv (vector bool unsigned char, vector unsigned char); 19073vector unsigned char vec_eqv (vector unsigned char, vector bool unsigned char); 19074 19075vector long long vec_max (vector long long, vector long long); 19076vector unsigned long long vec_max (vector unsigned long long, 19077 vector unsigned long long); 19078 19079vector signed int vec_mergee (vector signed int, vector signed int); 19080vector unsigned int vec_mergee (vector unsigned int, vector unsigned int); 19081vector bool int vec_mergee (vector bool int, vector bool int); 19082 19083vector signed int vec_mergeo (vector signed int, vector signed int); 19084vector unsigned int vec_mergeo (vector unsigned int, vector unsigned int); 19085vector bool int vec_mergeo (vector bool int, vector bool int); 19086 19087vector long long vec_min (vector long long, vector long long); 19088vector unsigned long long vec_min (vector unsigned long long, 19089 vector unsigned long long); 19090 19091vector signed long long vec_nabs (vector signed long long); 19092 19093vector long long vec_nand (vector long long, vector long long); 19094vector long long vec_nand (vector bool long long, vector long long); 19095vector long long vec_nand (vector long long, vector bool long long); 19096vector unsigned long long vec_nand (vector unsigned long long, 19097 vector unsigned long long); 19098vector unsigned long long vec_nand (vector bool long long, 19099 vector unsigned long long); 19100vector unsigned long long vec_nand (vector unsigned long long, 19101 vector bool long long); 19102vector int vec_nand (vector int, vector int); 19103vector int vec_nand (vector bool int, vector int); 19104vector int vec_nand (vector int, vector bool int); 19105vector unsigned int vec_nand (vector unsigned int, vector unsigned int); 19106vector unsigned int vec_nand (vector bool unsigned int, 19107 vector unsigned int); 19108vector unsigned int vec_nand (vector unsigned int, 19109 vector bool unsigned int); 19110vector short vec_nand (vector short, vector short); 19111vector short vec_nand (vector bool short, vector short); 19112vector short vec_nand (vector short, vector bool short); 19113vector unsigned short vec_nand (vector unsigned short, vector unsigned short); 19114vector unsigned short vec_nand (vector bool unsigned short, 19115 vector unsigned short); 19116vector unsigned short vec_nand (vector unsigned short, 19117 vector bool unsigned short); 19118vector signed char vec_nand (vector signed char, vector signed char); 19119vector signed char vec_nand (vector bool signed char, vector signed char); 19120vector signed char vec_nand (vector signed char, vector bool signed char); 19121vector unsigned char vec_nand (vector unsigned char, vector unsigned char); 19122vector unsigned char vec_nand (vector bool unsigned char, vector unsigned char); 19123vector unsigned char vec_nand (vector unsigned char, vector bool unsigned char); 19124 19125vector long long vec_orc (vector long long, vector long long); 19126vector long long vec_orc (vector bool long long, vector long long); 19127vector long long vec_orc (vector long long, vector bool long long); 19128vector unsigned long long vec_orc (vector unsigned long long, 19129 vector unsigned long long); 19130vector unsigned long long vec_orc (vector bool long long, 19131 vector unsigned long long); 19132vector unsigned long long vec_orc (vector unsigned long long, 19133 vector bool long long); 19134vector int vec_orc (vector int, vector int); 19135vector int vec_orc (vector bool int, vector int); 19136vector int vec_orc (vector int, vector bool int); 19137vector unsigned int vec_orc (vector unsigned int, vector unsigned int); 19138vector unsigned int vec_orc (vector bool unsigned int, 19139 vector unsigned int); 19140vector unsigned int vec_orc (vector unsigned int, 19141 vector bool unsigned int); 19142vector short vec_orc (vector short, vector short); 19143vector short vec_orc (vector bool short, vector short); 19144vector short vec_orc (vector short, vector bool short); 19145vector unsigned short vec_orc (vector unsigned short, vector unsigned short); 19146vector unsigned short vec_orc (vector bool unsigned short, 19147 vector unsigned short); 19148vector unsigned short vec_orc (vector unsigned short, 19149 vector bool unsigned short); 19150vector signed char vec_orc (vector signed char, vector signed char); 19151vector signed char vec_orc (vector bool signed char, vector signed char); 19152vector signed char vec_orc (vector signed char, vector bool signed char); 19153vector unsigned char vec_orc (vector unsigned char, vector unsigned char); 19154vector unsigned char vec_orc (vector bool unsigned char, vector unsigned char); 19155vector unsigned char vec_orc (vector unsigned char, vector bool unsigned char); 19156 19157vector int vec_pack (vector long long, vector long long); 19158vector unsigned int vec_pack (vector unsigned long long, 19159 vector unsigned long long); 19160vector bool int vec_pack (vector bool long long, vector bool long long); 19161vector float vec_pack (vector double, vector double); 19162 19163vector int vec_packs (vector long long, vector long long); 19164vector unsigned int vec_packs (vector unsigned long long, 19165 vector unsigned long long); 19166 19167test_vsi_packsu_vssi_vssi (vector signed short x, 19168 19169vector unsigned char vec_packsu (vector signed short, vector signed short ) 19170vector unsigned char vec_packsu (vector unsigned short, vector unsigned short ) 19171vector unsigned short int vec_packsu (vector signed int, vector signed int); 19172vector unsigned short int vec_packsu (vector unsigned int, 19173 vector unsigned int); 19174vector unsigned int vec_packsu (vector long long, vector long long); 19175vector unsigned int vec_packsu (vector unsigned long long, 19176 vector unsigned long long); 19177vector unsigned int vec_packsu (vector signed long long, 19178 vector signed long long); 19179 19180vector unsigned char vec_popcnt (vector signed char); 19181vector unsigned char vec_popcnt (vector unsigned char); 19182vector unsigned short vec_popcnt (vector signed short); 19183vector unsigned short vec_popcnt (vector unsigned short); 19184vector unsigned int vec_popcnt (vector signed int); 19185vector unsigned int vec_popcnt (vector unsigned int); 19186vector unsigned long long vec_popcnt (vector signed long long); 19187vector unsigned long long vec_popcnt (vector unsigned long long); 19188 19189vector long long vec_rl (vector long long, 19190 vector unsigned long long); 19191vector long long vec_rl (vector unsigned long long, 19192 vector unsigned long long); 19193 19194vector long long vec_sl (vector long long, vector unsigned long long); 19195vector long long vec_sl (vector unsigned long long, 19196 vector unsigned long long); 19197 19198vector long long vec_sr (vector long long, vector unsigned long long); 19199vector unsigned long long char vec_sr (vector unsigned long long, 19200 vector unsigned long long); 19201 19202vector long long vec_sra (vector long long, vector unsigned long long); 19203vector unsigned long long vec_sra (vector unsigned long long, 19204 vector unsigned long long); 19205 19206vector long long vec_sub (vector long long, vector long long); 19207vector unsigned long long vec_sub (vector unsigned long long, 19208 vector unsigned long long); 19209 19210vector long long vec_unpackh (vector int); 19211vector unsigned long long vec_unpackh (vector unsigned int); 19212 19213vector long long vec_unpackl (vector int); 19214vector unsigned long long vec_unpackl (vector unsigned int); 19215 19216vector long long vec_vaddudm (vector long long, vector long long); 19217vector long long vec_vaddudm (vector bool long long, vector long long); 19218vector long long vec_vaddudm (vector long long, vector bool long long); 19219vector unsigned long long vec_vaddudm (vector unsigned long long, 19220 vector unsigned long long); 19221vector unsigned long long vec_vaddudm (vector bool unsigned long long, 19222 vector unsigned long long); 19223vector unsigned long long vec_vaddudm (vector unsigned long long, 19224 vector bool unsigned long long); 19225 19226vector long long vec_vbpermq (vector signed char, vector signed char); 19227vector long long vec_vbpermq (vector unsigned char, vector unsigned char); 19228 19229vector unsigned char vec_bperm (vector unsigned char, vector unsigned char); 19230vector unsigned char vec_bperm (vector unsigned long long, 19231 vector unsigned char); 19232vector unsigned long long vec_bperm (vector unsigned __int128, 19233 vector unsigned char); 19234 19235vector long long vec_cntlz (vector long long); 19236vector unsigned long long vec_cntlz (vector unsigned long long); 19237vector int vec_cntlz (vector int); 19238vector unsigned int vec_cntlz (vector int); 19239vector short vec_cntlz (vector short); 19240vector unsigned short vec_cntlz (vector unsigned short); 19241vector signed char vec_cntlz (vector signed char); 19242vector unsigned char vec_cntlz (vector unsigned char); 19243 19244vector long long vec_vclz (vector long long); 19245vector unsigned long long vec_vclz (vector unsigned long long); 19246vector int vec_vclz (vector int); 19247vector unsigned int vec_vclz (vector int); 19248vector short vec_vclz (vector short); 19249vector unsigned short vec_vclz (vector unsigned short); 19250vector signed char vec_vclz (vector signed char); 19251vector unsigned char vec_vclz (vector unsigned char); 19252 19253vector signed char vec_vclzb (vector signed char); 19254vector unsigned char vec_vclzb (vector unsigned char); 19255 19256vector long long vec_vclzd (vector long long); 19257vector unsigned long long vec_vclzd (vector unsigned long long); 19258 19259vector short vec_vclzh (vector short); 19260vector unsigned short vec_vclzh (vector unsigned short); 19261 19262vector int vec_vclzw (vector int); 19263vector unsigned int vec_vclzw (vector int); 19264 19265vector signed char vec_vgbbd (vector signed char); 19266vector unsigned char vec_vgbbd (vector unsigned char); 19267 19268vector long long vec_vmaxsd (vector long long, vector long long); 19269 19270vector unsigned long long vec_vmaxud (vector unsigned long long, 19271 unsigned vector long long); 19272 19273vector long long vec_vminsd (vector long long, vector long long); 19274 19275vector unsigned long long vec_vminud (vector long long, 19276 vector long long); 19277 19278vector int vec_vpksdss (vector long long, vector long long); 19279vector unsigned int vec_vpksdss (vector long long, vector long long); 19280 19281vector unsigned int vec_vpkudus (vector unsigned long long, 19282 vector unsigned long long); 19283 19284vector int vec_vpkudum (vector long long, vector long long); 19285vector unsigned int vec_vpkudum (vector unsigned long long, 19286 vector unsigned long long); 19287vector bool int vec_vpkudum (vector bool long long, vector bool long long); 19288 19289vector long long vec_vpopcnt (vector long long); 19290vector unsigned long long vec_vpopcnt (vector unsigned long long); 19291vector int vec_vpopcnt (vector int); 19292vector unsigned int vec_vpopcnt (vector int); 19293vector short vec_vpopcnt (vector short); 19294vector unsigned short vec_vpopcnt (vector unsigned short); 19295vector signed char vec_vpopcnt (vector signed char); 19296vector unsigned char vec_vpopcnt (vector unsigned char); 19297 19298vector signed char vec_vpopcntb (vector signed char); 19299vector unsigned char vec_vpopcntb (vector unsigned char); 19300 19301vector long long vec_vpopcntd (vector long long); 19302vector unsigned long long vec_vpopcntd (vector unsigned long long); 19303 19304vector short vec_vpopcnth (vector short); 19305vector unsigned short vec_vpopcnth (vector unsigned short); 19306 19307vector int vec_vpopcntw (vector int); 19308vector unsigned int vec_vpopcntw (vector int); 19309 19310vector long long vec_vrld (vector long long, vector unsigned long long); 19311vector unsigned long long vec_vrld (vector unsigned long long, 19312 vector unsigned long long); 19313 19314vector long long vec_vsld (vector long long, vector unsigned long long); 19315vector long long vec_vsld (vector unsigned long long, 19316 vector unsigned long long); 19317 19318vector long long vec_vsrad (vector long long, vector unsigned long long); 19319vector unsigned long long vec_vsrad (vector unsigned long long, 19320 vector unsigned long long); 19321 19322vector long long vec_vsrd (vector long long, vector unsigned long long); 19323vector unsigned long long char vec_vsrd (vector unsigned long long, 19324 vector unsigned long long); 19325 19326vector long long vec_vsubudm (vector long long, vector long long); 19327vector long long vec_vsubudm (vector bool long long, vector long long); 19328vector long long vec_vsubudm (vector long long, vector bool long long); 19329vector unsigned long long vec_vsubudm (vector unsigned long long, 19330 vector unsigned long long); 19331vector unsigned long long vec_vsubudm (vector bool long long, 19332 vector unsigned long long); 19333vector unsigned long long vec_vsubudm (vector unsigned long long, 19334 vector bool long long); 19335 19336vector long long vec_vupkhsw (vector int); 19337vector unsigned long long vec_vupkhsw (vector unsigned int); 19338 19339vector long long vec_vupklsw (vector int); 19340vector unsigned long long vec_vupklsw (vector int); 19341@end smallexample 19342 19343If the ISA 2.07 additions to the vector/scalar (power8-vector) 19344instruction set are available, the following additional functions are 19345available for 64-bit targets. New vector types 19346(@var{vector __int128_t} and @var{vector __uint128_t}) are available 19347to hold the @var{__int128_t} and @var{__uint128_t} types to use these 19348builtins. 19349 19350The normal vector extract, and set operations work on 19351@var{vector __int128_t} and @var{vector __uint128_t} types, 19352but the index value must be 0. 19353 19354@smallexample 19355vector __int128_t vec_vaddcuq (vector __int128_t, vector __int128_t); 19356vector __uint128_t vec_vaddcuq (vector __uint128_t, vector __uint128_t); 19357 19358vector __int128_t vec_vadduqm (vector __int128_t, vector __int128_t); 19359vector __uint128_t vec_vadduqm (vector __uint128_t, vector __uint128_t); 19360 19361vector __int128_t vec_vaddecuq (vector __int128_t, vector __int128_t, 19362 vector __int128_t); 19363vector __uint128_t vec_vaddecuq (vector __uint128_t, vector __uint128_t, 19364 vector __uint128_t); 19365 19366vector __int128_t vec_vaddeuqm (vector __int128_t, vector __int128_t, 19367 vector __int128_t); 19368vector __uint128_t vec_vaddeuqm (vector __uint128_t, vector __uint128_t, 19369 vector __uint128_t); 19370 19371vector __int128_t vec_vsubecuq (vector __int128_t, vector __int128_t, 19372 vector __int128_t); 19373vector __uint128_t vec_vsubecuq (vector __uint128_t, vector __uint128_t, 19374 vector __uint128_t); 19375 19376vector __int128_t vec_vsubeuqm (vector __int128_t, vector __int128_t, 19377 vector __int128_t); 19378vector __uint128_t vec_vsubeuqm (vector __uint128_t, vector __uint128_t, 19379 vector __uint128_t); 19380 19381vector __int128_t vec_vsubcuq (vector __int128_t, vector __int128_t); 19382vector __uint128_t vec_vsubcuq (vector __uint128_t, vector __uint128_t); 19383 19384__int128_t vec_vsubuqm (__int128_t, __int128_t); 19385__uint128_t vec_vsubuqm (__uint128_t, __uint128_t); 19386 19387vector __int128_t __builtin_bcdadd (vector __int128_t, vector __int128_t); 19388int __builtin_bcdadd_lt (vector __int128_t, vector __int128_t); 19389int __builtin_bcdadd_eq (vector __int128_t, vector __int128_t); 19390int __builtin_bcdadd_gt (vector __int128_t, vector __int128_t); 19391int __builtin_bcdadd_ov (vector __int128_t, vector __int128_t); 19392vector __int128_t bcdsub (vector __int128_t, vector __int128_t); 19393int __builtin_bcdsub_lt (vector __int128_t, vector __int128_t); 19394int __builtin_bcdsub_eq (vector __int128_t, vector __int128_t); 19395int __builtin_bcdsub_gt (vector __int128_t, vector __int128_t); 19396int __builtin_bcdsub_ov (vector __int128_t, vector __int128_t); 19397@end smallexample 19398 19399If the ISA 3.0 instruction set additions (@option{-mcpu=power9}) 19400are available: 19401 19402@smallexample 19403vector unsigned long long vec_bperm (vector unsigned long long, 19404 vector unsigned char); 19405 19406vector bool char vec_cmpne (vector bool char, vector bool char); 19407vector bool char vec_cmpne (vector signed char, vector signed char); 19408vector bool char vec_cmpne (vector unsigned char, vector unsigned char); 19409vector bool int vec_cmpne (vector bool int, vector bool int); 19410vector bool int vec_cmpne (vector signed int, vector signed int); 19411vector bool int vec_cmpne (vector unsigned int, vector unsigned int); 19412vector bool long long vec_cmpne (vector bool long long, vector bool long long); 19413vector bool long long vec_cmpne (vector signed long long, 19414 vector signed long long); 19415vector bool long long vec_cmpne (vector unsigned long long, 19416 vector unsigned long long); 19417vector bool short vec_cmpne (vector bool short, vector bool short); 19418vector bool short vec_cmpne (vector signed short, vector signed short); 19419vector bool short vec_cmpne (vector unsigned short, vector unsigned short); 19420vector bool long long vec_cmpne (vector double, vector double); 19421vector bool int vec_cmpne (vector float, vector float); 19422 19423vector float vec_extract_fp32_from_shorth (vector unsigned short); 19424vector float vec_extract_fp32_from_shortl (vector unsigned short); 19425 19426vector long long vec_vctz (vector long long); 19427vector unsigned long long vec_vctz (vector unsigned long long); 19428vector int vec_vctz (vector int); 19429vector unsigned int vec_vctz (vector int); 19430vector short vec_vctz (vector short); 19431vector unsigned short vec_vctz (vector unsigned short); 19432vector signed char vec_vctz (vector signed char); 19433vector unsigned char vec_vctz (vector unsigned char); 19434 19435vector signed char vec_vctzb (vector signed char); 19436vector unsigned char vec_vctzb (vector unsigned char); 19437 19438vector long long vec_vctzd (vector long long); 19439vector unsigned long long vec_vctzd (vector unsigned long long); 19440 19441vector short vec_vctzh (vector short); 19442vector unsigned short vec_vctzh (vector unsigned short); 19443 19444vector int vec_vctzw (vector int); 19445vector unsigned int vec_vctzw (vector int); 19446 19447vector unsigned long long vec_extract4b (vector unsigned char, const int); 19448 19449vector unsigned char vec_insert4b (vector signed int, vector unsigned char, 19450 const int); 19451vector unsigned char vec_insert4b (vector unsigned int, vector unsigned char, 19452 const int); 19453 19454vector unsigned int vec_parity_lsbb (vector signed int); 19455vector unsigned int vec_parity_lsbb (vector unsigned int); 19456vector unsigned __int128 vec_parity_lsbb (vector signed __int128); 19457vector unsigned __int128 vec_parity_lsbb (vector unsigned __int128); 19458vector unsigned long long vec_parity_lsbb (vector signed long long); 19459vector unsigned long long vec_parity_lsbb (vector unsigned long long); 19460 19461vector int vec_vprtyb (vector int); 19462vector unsigned int vec_vprtyb (vector unsigned int); 19463vector long long vec_vprtyb (vector long long); 19464vector unsigned long long vec_vprtyb (vector unsigned long long); 19465 19466vector int vec_vprtybw (vector int); 19467vector unsigned int vec_vprtybw (vector unsigned int); 19468 19469vector long long vec_vprtybd (vector long long); 19470vector unsigned long long vec_vprtybd (vector unsigned long long); 19471@end smallexample 19472 19473On 64-bit targets, if the ISA 3.0 additions (@option{-mcpu=power9}) 19474are available: 19475 19476@smallexample 19477vector long vec_vprtyb (vector long); 19478vector unsigned long vec_vprtyb (vector unsigned long); 19479vector __int128_t vec_vprtyb (vector __int128_t); 19480vector __uint128_t vec_vprtyb (vector __uint128_t); 19481 19482vector long vec_vprtybd (vector long); 19483vector unsigned long vec_vprtybd (vector unsigned long); 19484 19485vector __int128_t vec_vprtybq (vector __int128_t); 19486vector __uint128_t vec_vprtybd (vector __uint128_t); 19487@end smallexample 19488 19489The following built-in vector functions are available for the PowerPC family 19490of processors, starting with ISA 3.0 or later (@option{-mcpu=power9}): 19491@smallexample 19492__vector unsigned char 19493vec_slv (__vector unsigned char src, __vector unsigned char shift_distance); 19494__vector unsigned char 19495vec_srv (__vector unsigned char src, __vector unsigned char shift_distance); 19496@end smallexample 19497 19498The @code{vec_slv} and @code{vec_srv} functions operate on 19499all of the bytes of their @code{src} and @code{shift_distance} 19500arguments in parallel. The behavior of the @code{vec_slv} is as if 19501there existed a temporary array of 17 unsigned characters 19502@code{slv_array} within which elements 0 through 15 are the same as 19503the entries in the @code{src} array and element 16 equals 0. The 19504result returned from the @code{vec_slv} function is a 19505@code{__vector} of 16 unsigned characters within which element 19506@code{i} is computed using the C expression 19507@code{0xff & (*((unsigned short *)(slv_array + i)) << (0x07 & 19508shift_distance[i]))}, 19509with this resulting value coerced to the @code{unsigned char} type. 19510The behavior of the @code{vec_srv} is as if 19511there existed a temporary array of 17 unsigned characters 19512@code{srv_array} within which element 0 equals zero and 19513elements 1 through 16 equal the elements 0 through 15 of 19514the @code{src} array. The 19515result returned from the @code{vec_srv} function is a 19516@code{__vector} of 16 unsigned characters within which element 19517@code{i} is computed using the C expression 19518@code{0xff & (*((unsigned short *)(srv_array + i)) >> 19519(0x07 & shift_distance[i]))}, 19520with this resulting value coerced to the @code{unsigned char} type. 19521 19522The following built-in functions are available for the PowerPC family 19523of processors, starting with ISA 3.0 or later (@option{-mcpu=power9}): 19524@smallexample 19525__vector unsigned char 19526vec_absd (__vector unsigned char arg1, __vector unsigned char arg2); 19527__vector unsigned short 19528vec_absd (__vector unsigned short arg1, __vector unsigned short arg2); 19529__vector unsigned int 19530vec_absd (__vector unsigned int arg1, __vector unsigned int arg2); 19531 19532__vector unsigned char 19533vec_absdb (__vector unsigned char arg1, __vector unsigned char arg2); 19534__vector unsigned short 19535vec_absdh (__vector unsigned short arg1, __vector unsigned short arg2); 19536__vector unsigned int 19537vec_absdw (__vector unsigned int arg1, __vector unsigned int arg2); 19538@end smallexample 19539 19540The @code{vec_absd}, @code{vec_absdb}, @code{vec_absdh}, and 19541@code{vec_absdw} built-in functions each computes the absolute 19542differences of the pairs of vector elements supplied in its two vector 19543arguments, placing the absolute differences into the corresponding 19544elements of the vector result. 19545 19546The following built-in functions are available for the PowerPC family 19547of processors, starting with ISA 3.0 or later (@option{-mcpu=power9}): 19548@smallexample 19549__vector unsigned int 19550vec_extract_exp (__vector float source); 19551__vector unsigned long long int 19552vec_extract_exp (__vector double source); 19553 19554__vector unsigned int 19555vec_extract_sig (__vector float source); 19556__vector unsigned long long int 19557vec_extract_sig (__vector double source); 19558 19559__vector float 19560vec_insert_exp (__vector unsigned int significands, 19561 __vector unsigned int exponents); 19562__vector float 19563vec_insert_exp (__vector unsigned float significands, 19564 __vector unsigned int exponents); 19565__vector double 19566vec_insert_exp (__vector unsigned long long int significands, 19567 __vector unsigned long long int exponents); 19568__vector double 19569vec_insert_exp (__vector unsigned double significands, 19570 __vector unsigned long long int exponents); 19571 19572__vector bool int vec_test_data_class (__vector float source, 19573 const int condition); 19574__vector bool long long int vec_test_data_class (__vector double source, 19575 const int condition); 19576@end smallexample 19577 19578The @code{vec_extract_sig} and @code{vec_extract_exp} built-in 19579functions return vectors representing the significands and biased 19580exponent values of their @code{source} arguments respectively. 19581Within the result vector returned by @code{vec_extract_sig}, the 19582@code{0x800000} bit of each vector element returned when the 19583function's @code{source} argument is of type @code{float} is set to 1 19584if the corresponding floating point value is in normalized form. 19585Otherwise, this bit is set to 0. When the @code{source} argument is 19586of type @code{double}, the @code{0x10000000000000} bit within each of 19587the result vector's elements is set according to the same rules. 19588Note that the sign of the significand is not represented in the result 19589returned from the @code{vec_extract_sig} function. To extract the 19590sign bits, use the 19591@code{vec_cpsgn} function, which returns a new vector within which all 19592of the sign bits of its second argument vector are overwritten with the 19593sign bits copied from the coresponding elements of its first argument 19594vector, and all other (non-sign) bits of the second argument vector 19595are copied unchanged into the result vector. 19596 19597The @code{vec_insert_exp} built-in functions return a vector of 19598single- or double-precision floating 19599point values constructed by assembling the values of their 19600@code{significands} and @code{exponents} arguments into the 19601corresponding elements of the returned vector. 19602The sign of each 19603element of the result is copied from the most significant bit of the 19604corresponding entry within the @code{significands} argument. 19605Note that the relevant 19606bits of the @code{significands} argument are the same, for both integer 19607and floating point types. 19608The 19609significand and exponent components of each element of the result are 19610composed of the least significant bits of the corresponding 19611@code{significands} element and the least significant bits of the 19612corresponding @code{exponents} element. 19613 19614The @code{vec_test_data_class} built-in function returns a vector 19615representing the results of testing the @code{source} vector for the 19616condition selected by the @code{condition} argument. The 19617@code{condition} argument must be a compile-time constant integer with 19618value not exceeding 127. The 19619@code{condition} argument is encoded as a bitmask with each bit 19620enabling the testing of a different condition, as characterized by the 19621following: 19622@smallexample 196230x40 Test for NaN 196240x20 Test for +Infinity 196250x10 Test for -Infinity 196260x08 Test for +Zero 196270x04 Test for -Zero 196280x02 Test for +Denormal 196290x01 Test for -Denormal 19630@end smallexample 19631 19632If any of the enabled test conditions is true, the corresponding entry 19633in the result vector is -1. Otherwise (all of the enabled test 19634conditions are false), the corresponding entry of the result vector is 0. 19635 19636The following built-in functions are available for the PowerPC family 19637of processors, starting with ISA 3.0 or later (@option{-mcpu=power9}): 19638@smallexample 19639vector unsigned int vec_rlmi (vector unsigned int, vector unsigned int, 19640 vector unsigned int); 19641vector unsigned long long vec_rlmi (vector unsigned long long, 19642 vector unsigned long long, 19643 vector unsigned long long); 19644vector unsigned int vec_rlnm (vector unsigned int, vector unsigned int, 19645 vector unsigned int); 19646vector unsigned long long vec_rlnm (vector unsigned long long, 19647 vector unsigned long long, 19648 vector unsigned long long); 19649vector unsigned int vec_vrlnm (vector unsigned int, vector unsigned int); 19650vector unsigned long long vec_vrlnm (vector unsigned long long, 19651 vector unsigned long long); 19652@end smallexample 19653 19654The result of @code{vec_rlmi} is obtained by rotating each element of 19655the first argument vector left and inserting it under mask into the 19656second argument vector. The third argument vector contains the mask 19657beginning in bits 11:15, the mask end in bits 19:23, and the shift 19658count in bits 27:31, of each element. 19659 19660The result of @code{vec_rlnm} is obtained by rotating each element of 19661the first argument vector left and ANDing it with a mask specified by 19662the second and third argument vectors. The second argument vector 19663contains the shift count for each element in the low-order byte. The 19664third argument vector contains the mask end for each element in the 19665low-order byte, with the mask begin in the next higher byte. 19666 19667The result of @code{vec_vrlnm} is obtained by rotating each element 19668of the first argument vector left and ANDing it with a mask. The 19669second argument vector contains the mask beginning in bits 11:15, 19670the mask end in bits 19:23, and the shift count in bits 27:31, 19671of each element. 19672 19673If the ISA 3.0 instruction set additions (@option{-mcpu=power9}) 19674are available: 19675@smallexample 19676vector signed bool char vec_revb (vector signed char); 19677vector signed char vec_revb (vector signed char); 19678vector unsigned char vec_revb (vector unsigned char); 19679vector bool short vec_revb (vector bool short); 19680vector short vec_revb (vector short); 19681vector unsigned short vec_revb (vector unsigned short); 19682vector bool int vec_revb (vector bool int); 19683vector int vec_revb (vector int); 19684vector unsigned int vec_revb (vector unsigned int); 19685vector float vec_revb (vector float); 19686vector bool long long vec_revb (vector bool long long); 19687vector long long vec_revb (vector long long); 19688vector unsigned long long vec_revb (vector unsigned long long); 19689vector double vec_revb (vector double); 19690@end smallexample 19691 19692On 64-bit targets, if the ISA 3.0 additions (@option{-mcpu=power9}) 19693are available: 19694@smallexample 19695vector long vec_revb (vector long); 19696vector unsigned long vec_revb (vector unsigned long); 19697vector __int128_t vec_revb (vector __int128_t); 19698vector __uint128_t vec_revb (vector __uint128_t); 19699@end smallexample 19700 19701The @code{vec_revb} built-in function reverses the bytes on an element 19702by element basis. A vector of @code{vector unsigned char} or 19703@code{vector signed char} reverses the bytes in the whole word. 19704 19705If the cryptographic instructions are enabled (@option{-mcrypto} or 19706@option{-mcpu=power8}), the following builtins are enabled. 19707 19708@smallexample 19709vector unsigned long long __builtin_crypto_vsbox (vector unsigned long long); 19710 19711vector unsigned char vec_sbox_be (vector unsigned char); 19712 19713vector unsigned long long __builtin_crypto_vcipher (vector unsigned long long, 19714 vector unsigned long long); 19715 19716vector unsigned char vec_cipher_be (vector unsigned char, vector unsigned char); 19717 19718vector unsigned long long __builtin_crypto_vcipherlast 19719 (vector unsigned long long, 19720 vector unsigned long long); 19721 19722vector unsigned char vec_cipherlast_be (vector unsigned char, 19723 vector unsigned char); 19724 19725vector unsigned long long __builtin_crypto_vncipher (vector unsigned long long, 19726 vector unsigned long long); 19727 19728vector unsigned char vec_ncipher_be (vector unsigned char, 19729 vector unsigned char); 19730 19731vector unsigned long long __builtin_crypto_vncipherlast 19732 (vector unsigned long long, 19733 vector unsigned long long); 19734 19735vector unsigned char vec_ncipherlast_be (vector unsigned char, 19736 vector unsigned char); 19737 19738vector unsigned char __builtin_crypto_vpermxor (vector unsigned char, 19739 vector unsigned char, 19740 vector unsigned char); 19741 19742vector unsigned short __builtin_crypto_vpermxor (vector unsigned short, 19743 vector unsigned short, 19744 vector unsigned short); 19745 19746vector unsigned int __builtin_crypto_vpermxor (vector unsigned int, 19747 vector unsigned int, 19748 vector unsigned int); 19749 19750vector unsigned long long __builtin_crypto_vpermxor (vector unsigned long long, 19751 vector unsigned long long, 19752 vector unsigned long long); 19753 19754vector unsigned char __builtin_crypto_vpmsumb (vector unsigned char, 19755 vector unsigned char); 19756 19757vector unsigned short __builtin_crypto_vpmsumh (vector unsigned short, 19758 vector unsigned short); 19759 19760vector unsigned int __builtin_crypto_vpmsumw (vector unsigned int, 19761 vector unsigned int); 19762 19763vector unsigned long long __builtin_crypto_vpmsumd (vector unsigned long long, 19764 vector unsigned long long); 19765 19766vector unsigned long long __builtin_crypto_vshasigmad 19767 (vector unsigned long long, int, int); 19768 19769vector unsigned int __builtin_crypto_vshasigmaw (vector unsigned int, 19770 int, int); 19771@end smallexample 19772 19773The second argument to @var{__builtin_crypto_vshasigmad} and 19774@var{__builtin_crypto_vshasigmaw} must be a constant 19775integer that is 0 or 1. The third argument to these built-in functions 19776must be a constant integer in the range of 0 to 15. 19777 19778If the ISA 3.0 instruction set additions 19779are enabled (@option{-mcpu=power9}), the following additional 19780functions are available for both 32-bit and 64-bit targets. 19781 19782vector short vec_xl (int, vector short *); 19783vector short vec_xl (int, short *); 19784vector unsigned short vec_xl (int, vector unsigned short *); 19785vector unsigned short vec_xl (int, unsigned short *); 19786vector char vec_xl (int, vector char *); 19787vector char vec_xl (int, char *); 19788vector unsigned char vec_xl (int, vector unsigned char *); 19789vector unsigned char vec_xl (int, unsigned char *); 19790 19791void vec_xst (vector short, int, vector short *); 19792void vec_xst (vector short, int, short *); 19793void vec_xst (vector unsigned short, int, vector unsigned short *); 19794void vec_xst (vector unsigned short, int, unsigned short *); 19795void vec_xst (vector char, int, vector char *); 19796void vec_xst (vector char, int, char *); 19797void vec_xst (vector unsigned char, int, vector unsigned char *); 19798void vec_xst (vector unsigned char, int, unsigned char *); 19799 19800@node PowerPC Hardware Transactional Memory Built-in Functions 19801@subsection PowerPC Hardware Transactional Memory Built-in Functions 19802GCC provides two interfaces for accessing the Hardware Transactional 19803Memory (HTM) instructions available on some of the PowerPC family 19804of processors (eg, POWER8). The two interfaces come in a low level 19805interface, consisting of built-in functions specific to PowerPC and a 19806higher level interface consisting of inline functions that are common 19807between PowerPC and S/390. 19808 19809@subsubsection PowerPC HTM Low Level Built-in Functions 19810 19811The following low level built-in functions are available with 19812@option{-mhtm} or @option{-mcpu=CPU} where CPU is `power8' or later. 19813They all generate the machine instruction that is part of the name. 19814 19815The HTM builtins (with the exception of @code{__builtin_tbegin}) return 19816the full 4-bit condition register value set by their associated hardware 19817instruction. The header file @code{htmintrin.h} defines some macros that can 19818be used to decipher the return value. The @code{__builtin_tbegin} builtin 19819returns a simple true or false value depending on whether a transaction was 19820successfully started or not. The arguments of the builtins match exactly the 19821type and order of the associated hardware instruction's operands, except for 19822the @code{__builtin_tcheck} builtin, which does not take any input arguments. 19823Refer to the ISA manual for a description of each instruction's operands. 19824 19825@smallexample 19826unsigned int __builtin_tbegin (unsigned int) 19827unsigned int __builtin_tend (unsigned int) 19828 19829unsigned int __builtin_tabort (unsigned int) 19830unsigned int __builtin_tabortdc (unsigned int, unsigned int, unsigned int) 19831unsigned int __builtin_tabortdci (unsigned int, unsigned int, int) 19832unsigned int __builtin_tabortwc (unsigned int, unsigned int, unsigned int) 19833unsigned int __builtin_tabortwci (unsigned int, unsigned int, int) 19834 19835unsigned int __builtin_tcheck (void) 19836unsigned int __builtin_treclaim (unsigned int) 19837unsigned int __builtin_trechkpt (void) 19838unsigned int __builtin_tsr (unsigned int) 19839@end smallexample 19840 19841In addition to the above HTM built-ins, we have added built-ins for 19842some common extended mnemonics of the HTM instructions: 19843 19844@smallexample 19845unsigned int __builtin_tendall (void) 19846unsigned int __builtin_tresume (void) 19847unsigned int __builtin_tsuspend (void) 19848@end smallexample 19849 19850Note that the semantics of the above HTM builtins are required to mimic 19851the locking semantics used for critical sections. Builtins that are used 19852to create a new transaction or restart a suspended transaction must have 19853lock acquisition like semantics while those builtins that end or suspend a 19854transaction must have lock release like semantics. Specifically, this must 19855mimic lock semantics as specified by C++11, for example: Lock acquisition is 19856as-if an execution of __atomic_exchange_n(&globallock,1,__ATOMIC_ACQUIRE) 19857that returns 0, and lock release is as-if an execution of 19858__atomic_store(&globallock,0,__ATOMIC_RELEASE), with globallock being an 19859implicit implementation-defined lock used for all transactions. The HTM 19860instructions associated with with the builtins inherently provide the 19861correct acquisition and release hardware barriers required. However, 19862the compiler must also be prohibited from moving loads and stores across 19863the builtins in a way that would violate their semantics. This has been 19864accomplished by adding memory barriers to the associated HTM instructions 19865(which is a conservative approach to provide acquire and release semantics). 19866Earlier versions of the compiler did not treat the HTM instructions as 19867memory barriers. A @code{__TM_FENCE__} macro has been added, which can 19868be used to determine whether the current compiler treats HTM instructions 19869as memory barriers or not. This allows the user to explicitly add memory 19870barriers to their code when using an older version of the compiler. 19871 19872The following set of built-in functions are available to gain access 19873to the HTM specific special purpose registers. 19874 19875@smallexample 19876unsigned long __builtin_get_texasr (void) 19877unsigned long __builtin_get_texasru (void) 19878unsigned long __builtin_get_tfhar (void) 19879unsigned long __builtin_get_tfiar (void) 19880 19881void __builtin_set_texasr (unsigned long); 19882void __builtin_set_texasru (unsigned long); 19883void __builtin_set_tfhar (unsigned long); 19884void __builtin_set_tfiar (unsigned long); 19885@end smallexample 19886 19887Example usage of these low level built-in functions may look like: 19888 19889@smallexample 19890#include <htmintrin.h> 19891 19892int num_retries = 10; 19893 19894while (1) 19895 @{ 19896 if (__builtin_tbegin (0)) 19897 @{ 19898 /* Transaction State Initiated. */ 19899 if (is_locked (lock)) 19900 __builtin_tabort (0); 19901 ... transaction code... 19902 __builtin_tend (0); 19903 break; 19904 @} 19905 else 19906 @{ 19907 /* Transaction State Failed. Use locks if the transaction 19908 failure is "persistent" or we've tried too many times. */ 19909 if (num_retries-- <= 0 19910 || _TEXASRU_FAILURE_PERSISTENT (__builtin_get_texasru ())) 19911 @{ 19912 acquire_lock (lock); 19913 ... non transactional fallback path... 19914 release_lock (lock); 19915 break; 19916 @} 19917 @} 19918 @} 19919@end smallexample 19920 19921One final built-in function has been added that returns the value of 19922the 2-bit Transaction State field of the Machine Status Register (MSR) 19923as stored in @code{CR0}. 19924 19925@smallexample 19926unsigned long __builtin_ttest (void) 19927@end smallexample 19928 19929This built-in can be used to determine the current transaction state 19930using the following code example: 19931 19932@smallexample 19933#include <htmintrin.h> 19934 19935unsigned char tx_state = _HTM_STATE (__builtin_ttest ()); 19936 19937if (tx_state == _HTM_TRANSACTIONAL) 19938 @{ 19939 /* Code to use in transactional state. */ 19940 @} 19941else if (tx_state == _HTM_NONTRANSACTIONAL) 19942 @{ 19943 /* Code to use in non-transactional state. */ 19944 @} 19945else if (tx_state == _HTM_SUSPENDED) 19946 @{ 19947 /* Code to use in transaction suspended state. */ 19948 @} 19949@end smallexample 19950 19951@subsubsection PowerPC HTM High Level Inline Functions 19952 19953The following high level HTM interface is made available by including 19954@code{<htmxlintrin.h>} and using @option{-mhtm} or @option{-mcpu=CPU} 19955where CPU is `power8' or later. This interface is common between PowerPC 19956and S/390, allowing users to write one HTM source implementation that 19957can be compiled and executed on either system. 19958 19959@smallexample 19960long __TM_simple_begin (void) 19961long __TM_begin (void* const TM_buff) 19962long __TM_end (void) 19963void __TM_abort (void) 19964void __TM_named_abort (unsigned char const code) 19965void __TM_resume (void) 19966void __TM_suspend (void) 19967 19968long __TM_is_user_abort (void* const TM_buff) 19969long __TM_is_named_user_abort (void* const TM_buff, unsigned char *code) 19970long __TM_is_illegal (void* const TM_buff) 19971long __TM_is_footprint_exceeded (void* const TM_buff) 19972long __TM_nesting_depth (void* const TM_buff) 19973long __TM_is_nested_too_deep(void* const TM_buff) 19974long __TM_is_conflict(void* const TM_buff) 19975long __TM_is_failure_persistent(void* const TM_buff) 19976long __TM_failure_address(void* const TM_buff) 19977long long __TM_failure_code(void* const TM_buff) 19978@end smallexample 19979 19980Using these common set of HTM inline functions, we can create 19981a more portable version of the HTM example in the previous 19982section that will work on either PowerPC or S/390: 19983 19984@smallexample 19985#include <htmxlintrin.h> 19986 19987int num_retries = 10; 19988TM_buff_type TM_buff; 19989 19990while (1) 19991 @{ 19992 if (__TM_begin (TM_buff) == _HTM_TBEGIN_STARTED) 19993 @{ 19994 /* Transaction State Initiated. */ 19995 if (is_locked (lock)) 19996 __TM_abort (); 19997 ... transaction code... 19998 __TM_end (); 19999 break; 20000 @} 20001 else 20002 @{ 20003 /* Transaction State Failed. Use locks if the transaction 20004 failure is "persistent" or we've tried too many times. */ 20005 if (num_retries-- <= 0 20006 || __TM_is_failure_persistent (TM_buff)) 20007 @{ 20008 acquire_lock (lock); 20009 ... non transactional fallback path... 20010 release_lock (lock); 20011 break; 20012 @} 20013 @} 20014 @} 20015@end smallexample 20016 20017@node PowerPC Atomic Memory Operation Functions 20018@subsection PowerPC Atomic Memory Operation Functions 20019ISA 3.0 of the PowerPC added new atomic memory operation (amo) 20020instructions. GCC provides support for these instructions in 64-bit 20021environments. All of the functions are declared in the include file 20022@code{amo.h}. 20023 20024The functions supported are: 20025 20026@smallexample 20027#include <amo.h> 20028 20029uint32_t amo_lwat_add (uint32_t *, uint32_t); 20030uint32_t amo_lwat_xor (uint32_t *, uint32_t); 20031uint32_t amo_lwat_ior (uint32_t *, uint32_t); 20032uint32_t amo_lwat_and (uint32_t *, uint32_t); 20033uint32_t amo_lwat_umax (uint32_t *, uint32_t); 20034uint32_t amo_lwat_umin (uint32_t *, uint32_t); 20035uint32_t amo_lwat_swap (uint32_t *, uint32_t); 20036 20037int32_t amo_lwat_sadd (int32_t *, int32_t); 20038int32_t amo_lwat_smax (int32_t *, int32_t); 20039int32_t amo_lwat_smin (int32_t *, int32_t); 20040int32_t amo_lwat_sswap (int32_t *, int32_t); 20041 20042uint64_t amo_ldat_add (uint64_t *, uint64_t); 20043uint64_t amo_ldat_xor (uint64_t *, uint64_t); 20044uint64_t amo_ldat_ior (uint64_t *, uint64_t); 20045uint64_t amo_ldat_and (uint64_t *, uint64_t); 20046uint64_t amo_ldat_umax (uint64_t *, uint64_t); 20047uint64_t amo_ldat_umin (uint64_t *, uint64_t); 20048uint64_t amo_ldat_swap (uint64_t *, uint64_t); 20049 20050int64_t amo_ldat_sadd (int64_t *, int64_t); 20051int64_t amo_ldat_smax (int64_t *, int64_t); 20052int64_t amo_ldat_smin (int64_t *, int64_t); 20053int64_t amo_ldat_sswap (int64_t *, int64_t); 20054 20055void amo_stwat_add (uint32_t *, uint32_t); 20056void amo_stwat_xor (uint32_t *, uint32_t); 20057void amo_stwat_ior (uint32_t *, uint32_t); 20058void amo_stwat_and (uint32_t *, uint32_t); 20059void amo_stwat_umax (uint32_t *, uint32_t); 20060void amo_stwat_umin (uint32_t *, uint32_t); 20061 20062void amo_stwat_sadd (int32_t *, int32_t); 20063void amo_stwat_smax (int32_t *, int32_t); 20064void amo_stwat_smin (int32_t *, int32_t); 20065 20066void amo_stdat_add (uint64_t *, uint64_t); 20067void amo_stdat_xor (uint64_t *, uint64_t); 20068void amo_stdat_ior (uint64_t *, uint64_t); 20069void amo_stdat_and (uint64_t *, uint64_t); 20070void amo_stdat_umax (uint64_t *, uint64_t); 20071void amo_stdat_umin (uint64_t *, uint64_t); 20072 20073void amo_stdat_sadd (int64_t *, int64_t); 20074void amo_stdat_smax (int64_t *, int64_t); 20075void amo_stdat_smin (int64_t *, int64_t); 20076@end smallexample 20077 20078@node RX Built-in Functions 20079@subsection RX Built-in Functions 20080GCC supports some of the RX instructions which cannot be expressed in 20081the C programming language via the use of built-in functions. The 20082following functions are supported: 20083 20084@deftypefn {Built-in Function} void __builtin_rx_brk (void) 20085Generates the @code{brk} machine instruction. 20086@end deftypefn 20087 20088@deftypefn {Built-in Function} void __builtin_rx_clrpsw (int) 20089Generates the @code{clrpsw} machine instruction to clear the specified 20090bit in the processor status word. 20091@end deftypefn 20092 20093@deftypefn {Built-in Function} void __builtin_rx_int (int) 20094Generates the @code{int} machine instruction to generate an interrupt 20095with the specified value. 20096@end deftypefn 20097 20098@deftypefn {Built-in Function} void __builtin_rx_machi (int, int) 20099Generates the @code{machi} machine instruction to add the result of 20100multiplying the top 16 bits of the two arguments into the 20101accumulator. 20102@end deftypefn 20103 20104@deftypefn {Built-in Function} void __builtin_rx_maclo (int, int) 20105Generates the @code{maclo} machine instruction to add the result of 20106multiplying the bottom 16 bits of the two arguments into the 20107accumulator. 20108@end deftypefn 20109 20110@deftypefn {Built-in Function} void __builtin_rx_mulhi (int, int) 20111Generates the @code{mulhi} machine instruction to place the result of 20112multiplying the top 16 bits of the two arguments into the 20113accumulator. 20114@end deftypefn 20115 20116@deftypefn {Built-in Function} void __builtin_rx_mullo (int, int) 20117Generates the @code{mullo} machine instruction to place the result of 20118multiplying the bottom 16 bits of the two arguments into the 20119accumulator. 20120@end deftypefn 20121 20122@deftypefn {Built-in Function} int __builtin_rx_mvfachi (void) 20123Generates the @code{mvfachi} machine instruction to read the top 2012432 bits of the accumulator. 20125@end deftypefn 20126 20127@deftypefn {Built-in Function} int __builtin_rx_mvfacmi (void) 20128Generates the @code{mvfacmi} machine instruction to read the middle 2012932 bits of the accumulator. 20130@end deftypefn 20131 20132@deftypefn {Built-in Function} int __builtin_rx_mvfc (int) 20133Generates the @code{mvfc} machine instruction which reads the control 20134register specified in its argument and returns its value. 20135@end deftypefn 20136 20137@deftypefn {Built-in Function} void __builtin_rx_mvtachi (int) 20138Generates the @code{mvtachi} machine instruction to set the top 2013932 bits of the accumulator. 20140@end deftypefn 20141 20142@deftypefn {Built-in Function} void __builtin_rx_mvtaclo (int) 20143Generates the @code{mvtaclo} machine instruction to set the bottom 2014432 bits of the accumulator. 20145@end deftypefn 20146 20147@deftypefn {Built-in Function} void __builtin_rx_mvtc (int reg, int val) 20148Generates the @code{mvtc} machine instruction which sets control 20149register number @code{reg} to @code{val}. 20150@end deftypefn 20151 20152@deftypefn {Built-in Function} void __builtin_rx_mvtipl (int) 20153Generates the @code{mvtipl} machine instruction set the interrupt 20154priority level. 20155@end deftypefn 20156 20157@deftypefn {Built-in Function} void __builtin_rx_racw (int) 20158Generates the @code{racw} machine instruction to round the accumulator 20159according to the specified mode. 20160@end deftypefn 20161 20162@deftypefn {Built-in Function} int __builtin_rx_revw (int) 20163Generates the @code{revw} machine instruction which swaps the bytes in 20164the argument so that bits 0--7 now occupy bits 8--15 and vice versa, 20165and also bits 16--23 occupy bits 24--31 and vice versa. 20166@end deftypefn 20167 20168@deftypefn {Built-in Function} void __builtin_rx_rmpa (void) 20169Generates the @code{rmpa} machine instruction which initiates a 20170repeated multiply and accumulate sequence. 20171@end deftypefn 20172 20173@deftypefn {Built-in Function} void __builtin_rx_round (float) 20174Generates the @code{round} machine instruction which returns the 20175floating-point argument rounded according to the current rounding mode 20176set in the floating-point status word register. 20177@end deftypefn 20178 20179@deftypefn {Built-in Function} int __builtin_rx_sat (int) 20180Generates the @code{sat} machine instruction which returns the 20181saturated value of the argument. 20182@end deftypefn 20183 20184@deftypefn {Built-in Function} void __builtin_rx_setpsw (int) 20185Generates the @code{setpsw} machine instruction to set the specified 20186bit in the processor status word. 20187@end deftypefn 20188 20189@deftypefn {Built-in Function} void __builtin_rx_wait (void) 20190Generates the @code{wait} machine instruction. 20191@end deftypefn 20192 20193@node S/390 System z Built-in Functions 20194@subsection S/390 System z Built-in Functions 20195@deftypefn {Built-in Function} int __builtin_tbegin (void*) 20196Generates the @code{tbegin} machine instruction starting a 20197non-constrained hardware transaction. If the parameter is non-NULL the 20198memory area is used to store the transaction diagnostic buffer and 20199will be passed as first operand to @code{tbegin}. This buffer can be 20200defined using the @code{struct __htm_tdb} C struct defined in 20201@code{htmintrin.h} and must reside on a double-word boundary. The 20202second tbegin operand is set to @code{0xff0c}. This enables 20203save/restore of all GPRs and disables aborts for FPR and AR 20204manipulations inside the transaction body. The condition code set by 20205the tbegin instruction is returned as integer value. The tbegin 20206instruction by definition overwrites the content of all FPRs. The 20207compiler will generate code which saves and restores the FPRs. For 20208soft-float code it is recommended to used the @code{*_nofloat} 20209variant. In order to prevent a TDB from being written it is required 20210to pass a constant zero value as parameter. Passing a zero value 20211through a variable is not sufficient. Although modifications of 20212access registers inside the transaction will not trigger an 20213transaction abort it is not supported to actually modify them. Access 20214registers do not get saved when entering a transaction. They will have 20215undefined state when reaching the abort code. 20216@end deftypefn 20217 20218Macros for the possible return codes of tbegin are defined in the 20219@code{htmintrin.h} header file: 20220 20221@table @code 20222@item _HTM_TBEGIN_STARTED 20223@code{tbegin} has been executed as part of normal processing. The 20224transaction body is supposed to be executed. 20225@item _HTM_TBEGIN_INDETERMINATE 20226The transaction was aborted due to an indeterminate condition which 20227might be persistent. 20228@item _HTM_TBEGIN_TRANSIENT 20229The transaction aborted due to a transient failure. The transaction 20230should be re-executed in that case. 20231@item _HTM_TBEGIN_PERSISTENT 20232The transaction aborted due to a persistent failure. Re-execution 20233under same circumstances will not be productive. 20234@end table 20235 20236@defmac _HTM_FIRST_USER_ABORT_CODE 20237The @code{_HTM_FIRST_USER_ABORT_CODE} defined in @code{htmintrin.h} 20238specifies the first abort code which can be used for 20239@code{__builtin_tabort}. Values below this threshold are reserved for 20240machine use. 20241@end defmac 20242 20243@deftp {Data type} {struct __htm_tdb} 20244The @code{struct __htm_tdb} defined in @code{htmintrin.h} describes 20245the structure of the transaction diagnostic block as specified in the 20246Principles of Operation manual chapter 5-91. 20247@end deftp 20248 20249@deftypefn {Built-in Function} int __builtin_tbegin_nofloat (void*) 20250Same as @code{__builtin_tbegin} but without FPR saves and restores. 20251Using this variant in code making use of FPRs will leave the FPRs in 20252undefined state when entering the transaction abort handler code. 20253@end deftypefn 20254 20255@deftypefn {Built-in Function} int __builtin_tbegin_retry (void*, int) 20256In addition to @code{__builtin_tbegin} a loop for transient failures 20257is generated. If tbegin returns a condition code of 2 the transaction 20258will be retried as often as specified in the second argument. The 20259perform processor assist instruction is used to tell the CPU about the 20260number of fails so far. 20261@end deftypefn 20262 20263@deftypefn {Built-in Function} int __builtin_tbegin_retry_nofloat (void*, int) 20264Same as @code{__builtin_tbegin_retry} but without FPR saves and 20265restores. Using this variant in code making use of FPRs will leave 20266the FPRs in undefined state when entering the transaction abort 20267handler code. 20268@end deftypefn 20269 20270@deftypefn {Built-in Function} void __builtin_tbeginc (void) 20271Generates the @code{tbeginc} machine instruction starting a constrained 20272hardware transaction. The second operand is set to @code{0xff08}. 20273@end deftypefn 20274 20275@deftypefn {Built-in Function} int __builtin_tend (void) 20276Generates the @code{tend} machine instruction finishing a transaction 20277and making the changes visible to other threads. The condition code 20278generated by tend is returned as integer value. 20279@end deftypefn 20280 20281@deftypefn {Built-in Function} void __builtin_tabort (int) 20282Generates the @code{tabort} machine instruction with the specified 20283abort code. Abort codes from 0 through 255 are reserved and will 20284result in an error message. 20285@end deftypefn 20286 20287@deftypefn {Built-in Function} void __builtin_tx_assist (int) 20288Generates the @code{ppa rX,rY,1} machine instruction. Where the 20289integer parameter is loaded into rX and a value of zero is loaded into 20290rY. The integer parameter specifies the number of times the 20291transaction repeatedly aborted. 20292@end deftypefn 20293 20294@deftypefn {Built-in Function} int __builtin_tx_nesting_depth (void) 20295Generates the @code{etnd} machine instruction. The current nesting 20296depth is returned as integer value. For a nesting depth of 0 the code 20297is not executed as part of an transaction. 20298@end deftypefn 20299 20300@deftypefn {Built-in Function} void __builtin_non_tx_store (uint64_t *, uint64_t) 20301 20302Generates the @code{ntstg} machine instruction. The second argument 20303is written to the first arguments location. The store operation will 20304not be rolled-back in case of an transaction abort. 20305@end deftypefn 20306 20307@node SH Built-in Functions 20308@subsection SH Built-in Functions 20309The following built-in functions are supported on the SH1, SH2, SH3 and SH4 20310families of processors: 20311 20312@deftypefn {Built-in Function} {void} __builtin_set_thread_pointer (void *@var{ptr}) 20313Sets the @samp{GBR} register to the specified value @var{ptr}. This is usually 20314used by system code that manages threads and execution contexts. The compiler 20315normally does not generate code that modifies the contents of @samp{GBR} and 20316thus the value is preserved across function calls. Changing the @samp{GBR} 20317value in user code must be done with caution, since the compiler might use 20318@samp{GBR} in order to access thread local variables. 20319 20320@end deftypefn 20321 20322@deftypefn {Built-in Function} {void *} __builtin_thread_pointer (void) 20323Returns the value that is currently set in the @samp{GBR} register. 20324Memory loads and stores that use the thread pointer as a base address are 20325turned into @samp{GBR} based displacement loads and stores, if possible. 20326For example: 20327@smallexample 20328struct my_tcb 20329@{ 20330 int a, b, c, d, e; 20331@}; 20332 20333int get_tcb_value (void) 20334@{ 20335 // Generate @samp{mov.l @@(8,gbr),r0} instruction 20336 return ((my_tcb*)__builtin_thread_pointer ())->c; 20337@} 20338 20339@end smallexample 20340@end deftypefn 20341 20342@deftypefn {Built-in Function} {unsigned int} __builtin_sh_get_fpscr (void) 20343Returns the value that is currently set in the @samp{FPSCR} register. 20344@end deftypefn 20345 20346@deftypefn {Built-in Function} {void} __builtin_sh_set_fpscr (unsigned int @var{val}) 20347Sets the @samp{FPSCR} register to the specified value @var{val}, while 20348preserving the current values of the FR, SZ and PR bits. 20349@end deftypefn 20350 20351@node SPARC VIS Built-in Functions 20352@subsection SPARC VIS Built-in Functions 20353 20354GCC supports SIMD operations on the SPARC using both the generic vector 20355extensions (@pxref{Vector Extensions}) as well as built-in functions for 20356the SPARC Visual Instruction Set (VIS). When you use the @option{-mvis} 20357switch, the VIS extension is exposed as the following built-in functions: 20358 20359@smallexample 20360typedef int v1si __attribute__ ((vector_size (4))); 20361typedef int v2si __attribute__ ((vector_size (8))); 20362typedef short v4hi __attribute__ ((vector_size (8))); 20363typedef short v2hi __attribute__ ((vector_size (4))); 20364typedef unsigned char v8qi __attribute__ ((vector_size (8))); 20365typedef unsigned char v4qi __attribute__ ((vector_size (4))); 20366 20367void __builtin_vis_write_gsr (int64_t); 20368int64_t __builtin_vis_read_gsr (void); 20369 20370void * __builtin_vis_alignaddr (void *, long); 20371void * __builtin_vis_alignaddrl (void *, long); 20372int64_t __builtin_vis_faligndatadi (int64_t, int64_t); 20373v2si __builtin_vis_faligndatav2si (v2si, v2si); 20374v4hi __builtin_vis_faligndatav4hi (v4si, v4si); 20375v8qi __builtin_vis_faligndatav8qi (v8qi, v8qi); 20376 20377v4hi __builtin_vis_fexpand (v4qi); 20378 20379v4hi __builtin_vis_fmul8x16 (v4qi, v4hi); 20380v4hi __builtin_vis_fmul8x16au (v4qi, v2hi); 20381v4hi __builtin_vis_fmul8x16al (v4qi, v2hi); 20382v4hi __builtin_vis_fmul8sux16 (v8qi, v4hi); 20383v4hi __builtin_vis_fmul8ulx16 (v8qi, v4hi); 20384v2si __builtin_vis_fmuld8sux16 (v4qi, v2hi); 20385v2si __builtin_vis_fmuld8ulx16 (v4qi, v2hi); 20386 20387v4qi __builtin_vis_fpack16 (v4hi); 20388v8qi __builtin_vis_fpack32 (v2si, v8qi); 20389v2hi __builtin_vis_fpackfix (v2si); 20390v8qi __builtin_vis_fpmerge (v4qi, v4qi); 20391 20392int64_t __builtin_vis_pdist (v8qi, v8qi, int64_t); 20393 20394long __builtin_vis_edge8 (void *, void *); 20395long __builtin_vis_edge8l (void *, void *); 20396long __builtin_vis_edge16 (void *, void *); 20397long __builtin_vis_edge16l (void *, void *); 20398long __builtin_vis_edge32 (void *, void *); 20399long __builtin_vis_edge32l (void *, void *); 20400 20401long __builtin_vis_fcmple16 (v4hi, v4hi); 20402long __builtin_vis_fcmple32 (v2si, v2si); 20403long __builtin_vis_fcmpne16 (v4hi, v4hi); 20404long __builtin_vis_fcmpne32 (v2si, v2si); 20405long __builtin_vis_fcmpgt16 (v4hi, v4hi); 20406long __builtin_vis_fcmpgt32 (v2si, v2si); 20407long __builtin_vis_fcmpeq16 (v4hi, v4hi); 20408long __builtin_vis_fcmpeq32 (v2si, v2si); 20409 20410v4hi __builtin_vis_fpadd16 (v4hi, v4hi); 20411v2hi __builtin_vis_fpadd16s (v2hi, v2hi); 20412v2si __builtin_vis_fpadd32 (v2si, v2si); 20413v1si __builtin_vis_fpadd32s (v1si, v1si); 20414v4hi __builtin_vis_fpsub16 (v4hi, v4hi); 20415v2hi __builtin_vis_fpsub16s (v2hi, v2hi); 20416v2si __builtin_vis_fpsub32 (v2si, v2si); 20417v1si __builtin_vis_fpsub32s (v1si, v1si); 20418 20419long __builtin_vis_array8 (long, long); 20420long __builtin_vis_array16 (long, long); 20421long __builtin_vis_array32 (long, long); 20422@end smallexample 20423 20424When you use the @option{-mvis2} switch, the VIS version 2.0 built-in 20425functions also become available: 20426 20427@smallexample 20428long __builtin_vis_bmask (long, long); 20429int64_t __builtin_vis_bshuffledi (int64_t, int64_t); 20430v2si __builtin_vis_bshufflev2si (v2si, v2si); 20431v4hi __builtin_vis_bshufflev2si (v4hi, v4hi); 20432v8qi __builtin_vis_bshufflev2si (v8qi, v8qi); 20433 20434long __builtin_vis_edge8n (void *, void *); 20435long __builtin_vis_edge8ln (void *, void *); 20436long __builtin_vis_edge16n (void *, void *); 20437long __builtin_vis_edge16ln (void *, void *); 20438long __builtin_vis_edge32n (void *, void *); 20439long __builtin_vis_edge32ln (void *, void *); 20440@end smallexample 20441 20442When you use the @option{-mvis3} switch, the VIS version 3.0 built-in 20443functions also become available: 20444 20445@smallexample 20446void __builtin_vis_cmask8 (long); 20447void __builtin_vis_cmask16 (long); 20448void __builtin_vis_cmask32 (long); 20449 20450v4hi __builtin_vis_fchksm16 (v4hi, v4hi); 20451 20452v4hi __builtin_vis_fsll16 (v4hi, v4hi); 20453v4hi __builtin_vis_fslas16 (v4hi, v4hi); 20454v4hi __builtin_vis_fsrl16 (v4hi, v4hi); 20455v4hi __builtin_vis_fsra16 (v4hi, v4hi); 20456v2si __builtin_vis_fsll16 (v2si, v2si); 20457v2si __builtin_vis_fslas16 (v2si, v2si); 20458v2si __builtin_vis_fsrl16 (v2si, v2si); 20459v2si __builtin_vis_fsra16 (v2si, v2si); 20460 20461long __builtin_vis_pdistn (v8qi, v8qi); 20462 20463v4hi __builtin_vis_fmean16 (v4hi, v4hi); 20464 20465int64_t __builtin_vis_fpadd64 (int64_t, int64_t); 20466int64_t __builtin_vis_fpsub64 (int64_t, int64_t); 20467 20468v4hi __builtin_vis_fpadds16 (v4hi, v4hi); 20469v2hi __builtin_vis_fpadds16s (v2hi, v2hi); 20470v4hi __builtin_vis_fpsubs16 (v4hi, v4hi); 20471v2hi __builtin_vis_fpsubs16s (v2hi, v2hi); 20472v2si __builtin_vis_fpadds32 (v2si, v2si); 20473v1si __builtin_vis_fpadds32s (v1si, v1si); 20474v2si __builtin_vis_fpsubs32 (v2si, v2si); 20475v1si __builtin_vis_fpsubs32s (v1si, v1si); 20476 20477long __builtin_vis_fucmple8 (v8qi, v8qi); 20478long __builtin_vis_fucmpne8 (v8qi, v8qi); 20479long __builtin_vis_fucmpgt8 (v8qi, v8qi); 20480long __builtin_vis_fucmpeq8 (v8qi, v8qi); 20481 20482float __builtin_vis_fhadds (float, float); 20483double __builtin_vis_fhaddd (double, double); 20484float __builtin_vis_fhsubs (float, float); 20485double __builtin_vis_fhsubd (double, double); 20486float __builtin_vis_fnhadds (float, float); 20487double __builtin_vis_fnhaddd (double, double); 20488 20489int64_t __builtin_vis_umulxhi (int64_t, int64_t); 20490int64_t __builtin_vis_xmulx (int64_t, int64_t); 20491int64_t __builtin_vis_xmulxhi (int64_t, int64_t); 20492@end smallexample 20493 20494When you use the @option{-mvis4} switch, the VIS version 4.0 built-in 20495functions also become available: 20496 20497@smallexample 20498v8qi __builtin_vis_fpadd8 (v8qi, v8qi); 20499v8qi __builtin_vis_fpadds8 (v8qi, v8qi); 20500v8qi __builtin_vis_fpaddus8 (v8qi, v8qi); 20501v4hi __builtin_vis_fpaddus16 (v4hi, v4hi); 20502 20503v8qi __builtin_vis_fpsub8 (v8qi, v8qi); 20504v8qi __builtin_vis_fpsubs8 (v8qi, v8qi); 20505v8qi __builtin_vis_fpsubus8 (v8qi, v8qi); 20506v4hi __builtin_vis_fpsubus16 (v4hi, v4hi); 20507 20508long __builtin_vis_fpcmple8 (v8qi, v8qi); 20509long __builtin_vis_fpcmpgt8 (v8qi, v8qi); 20510long __builtin_vis_fpcmpule16 (v4hi, v4hi); 20511long __builtin_vis_fpcmpugt16 (v4hi, v4hi); 20512long __builtin_vis_fpcmpule32 (v2si, v2si); 20513long __builtin_vis_fpcmpugt32 (v2si, v2si); 20514 20515v8qi __builtin_vis_fpmax8 (v8qi, v8qi); 20516v4hi __builtin_vis_fpmax16 (v4hi, v4hi); 20517v2si __builtin_vis_fpmax32 (v2si, v2si); 20518 20519v8qi __builtin_vis_fpmaxu8 (v8qi, v8qi); 20520v4hi __builtin_vis_fpmaxu16 (v4hi, v4hi); 20521v2si __builtin_vis_fpmaxu32 (v2si, v2si); 20522 20523 20524v8qi __builtin_vis_fpmin8 (v8qi, v8qi); 20525v4hi __builtin_vis_fpmin16 (v4hi, v4hi); 20526v2si __builtin_vis_fpmin32 (v2si, v2si); 20527 20528v8qi __builtin_vis_fpminu8 (v8qi, v8qi); 20529v4hi __builtin_vis_fpminu16 (v4hi, v4hi); 20530v2si __builtin_vis_fpminu32 (v2si, v2si); 20531@end smallexample 20532 20533When you use the @option{-mvis4b} switch, the VIS version 4.0B 20534built-in functions also become available: 20535 20536@smallexample 20537v8qi __builtin_vis_dictunpack8 (double, int); 20538v4hi __builtin_vis_dictunpack16 (double, int); 20539v2si __builtin_vis_dictunpack32 (double, int); 20540 20541long __builtin_vis_fpcmple8shl (v8qi, v8qi, int); 20542long __builtin_vis_fpcmpgt8shl (v8qi, v8qi, int); 20543long __builtin_vis_fpcmpeq8shl (v8qi, v8qi, int); 20544long __builtin_vis_fpcmpne8shl (v8qi, v8qi, int); 20545 20546long __builtin_vis_fpcmple16shl (v4hi, v4hi, int); 20547long __builtin_vis_fpcmpgt16shl (v4hi, v4hi, int); 20548long __builtin_vis_fpcmpeq16shl (v4hi, v4hi, int); 20549long __builtin_vis_fpcmpne16shl (v4hi, v4hi, int); 20550 20551long __builtin_vis_fpcmple32shl (v2si, v2si, int); 20552long __builtin_vis_fpcmpgt32shl (v2si, v2si, int); 20553long __builtin_vis_fpcmpeq32shl (v2si, v2si, int); 20554long __builtin_vis_fpcmpne32shl (v2si, v2si, int); 20555 20556long __builtin_vis_fpcmpule8shl (v8qi, v8qi, int); 20557long __builtin_vis_fpcmpugt8shl (v8qi, v8qi, int); 20558long __builtin_vis_fpcmpule16shl (v4hi, v4hi, int); 20559long __builtin_vis_fpcmpugt16shl (v4hi, v4hi, int); 20560long __builtin_vis_fpcmpule32shl (v2si, v2si, int); 20561long __builtin_vis_fpcmpugt32shl (v2si, v2si, int); 20562 20563long __builtin_vis_fpcmpde8shl (v8qi, v8qi, int); 20564long __builtin_vis_fpcmpde16shl (v4hi, v4hi, int); 20565long __builtin_vis_fpcmpde32shl (v2si, v2si, int); 20566 20567long __builtin_vis_fpcmpur8shl (v8qi, v8qi, int); 20568long __builtin_vis_fpcmpur16shl (v4hi, v4hi, int); 20569long __builtin_vis_fpcmpur32shl (v2si, v2si, int); 20570@end smallexample 20571 20572@node SPU Built-in Functions 20573@subsection SPU Built-in Functions 20574 20575GCC provides extensions for the SPU processor as described in the 20576Sony/Toshiba/IBM SPU Language Extensions Specification. GCC's 20577implementation differs in several ways. 20578 20579@itemize @bullet 20580 20581@item 20582The optional extension of specifying vector constants in parentheses is 20583not supported. 20584 20585@item 20586A vector initializer requires no cast if the vector constant is of the 20587same type as the variable it is initializing. 20588 20589@item 20590If @code{signed} or @code{unsigned} is omitted, the signedness of the 20591vector type is the default signedness of the base type. The default 20592varies depending on the operating system, so a portable program should 20593always specify the signedness. 20594 20595@item 20596By default, the keyword @code{__vector} is added. The macro 20597@code{vector} is defined in @code{<spu_intrinsics.h>} and can be 20598undefined. 20599 20600@item 20601GCC allows using a @code{typedef} name as the type specifier for a 20602vector type. 20603 20604@item 20605For C, overloaded functions are implemented with macros so the following 20606does not work: 20607 20608@smallexample 20609 spu_add ((vector signed int)@{1, 2, 3, 4@}, foo); 20610@end smallexample 20611 20612@noindent 20613Since @code{spu_add} is a macro, the vector constant in the example 20614is treated as four separate arguments. Wrap the entire argument in 20615parentheses for this to work. 20616 20617@item 20618The extended version of @code{__builtin_expect} is not supported. 20619 20620@end itemize 20621 20622@emph{Note:} Only the interface described in the aforementioned 20623specification is supported. Internally, GCC uses built-in functions to 20624implement the required functionality, but these are not supported and 20625are subject to change without notice. 20626 20627@node TI C6X Built-in Functions 20628@subsection TI C6X Built-in Functions 20629 20630GCC provides intrinsics to access certain instructions of the TI C6X 20631processors. These intrinsics, listed below, are available after 20632inclusion of the @code{c6x_intrinsics.h} header file. They map directly 20633to C6X instructions. 20634 20635@smallexample 20636 20637int _sadd (int, int) 20638int _ssub (int, int) 20639int _sadd2 (int, int) 20640int _ssub2 (int, int) 20641long long _mpy2 (int, int) 20642long long _smpy2 (int, int) 20643int _add4 (int, int) 20644int _sub4 (int, int) 20645int _saddu4 (int, int) 20646 20647int _smpy (int, int) 20648int _smpyh (int, int) 20649int _smpyhl (int, int) 20650int _smpylh (int, int) 20651 20652int _sshl (int, int) 20653int _subc (int, int) 20654 20655int _avg2 (int, int) 20656int _avgu4 (int, int) 20657 20658int _clrr (int, int) 20659int _extr (int, int) 20660int _extru (int, int) 20661int _abs (int) 20662int _abs2 (int) 20663 20664@end smallexample 20665 20666@node TILE-Gx Built-in Functions 20667@subsection TILE-Gx Built-in Functions 20668 20669GCC provides intrinsics to access every instruction of the TILE-Gx 20670processor. The intrinsics are of the form: 20671 20672@smallexample 20673 20674unsigned long long __insn_@var{op} (...) 20675 20676@end smallexample 20677 20678Where @var{op} is the name of the instruction. Refer to the ISA manual 20679for the complete list of instructions. 20680 20681GCC also provides intrinsics to directly access the network registers. 20682The intrinsics are: 20683 20684@smallexample 20685 20686unsigned long long __tile_idn0_receive (void) 20687unsigned long long __tile_idn1_receive (void) 20688unsigned long long __tile_udn0_receive (void) 20689unsigned long long __tile_udn1_receive (void) 20690unsigned long long __tile_udn2_receive (void) 20691unsigned long long __tile_udn3_receive (void) 20692void __tile_idn_send (unsigned long long) 20693void __tile_udn_send (unsigned long long) 20694 20695@end smallexample 20696 20697The intrinsic @code{void __tile_network_barrier (void)} is used to 20698guarantee that no network operations before it are reordered with 20699those after it. 20700 20701@node TILEPro Built-in Functions 20702@subsection TILEPro Built-in Functions 20703 20704GCC provides intrinsics to access every instruction of the TILEPro 20705processor. The intrinsics are of the form: 20706 20707@smallexample 20708 20709unsigned __insn_@var{op} (...) 20710 20711@end smallexample 20712 20713@noindent 20714where @var{op} is the name of the instruction. Refer to the ISA manual 20715for the complete list of instructions. 20716 20717GCC also provides intrinsics to directly access the network registers. 20718The intrinsics are: 20719 20720@smallexample 20721 20722unsigned __tile_idn0_receive (void) 20723unsigned __tile_idn1_receive (void) 20724unsigned __tile_sn_receive (void) 20725unsigned __tile_udn0_receive (void) 20726unsigned __tile_udn1_receive (void) 20727unsigned __tile_udn2_receive (void) 20728unsigned __tile_udn3_receive (void) 20729void __tile_idn_send (unsigned) 20730void __tile_sn_send (unsigned) 20731void __tile_udn_send (unsigned) 20732 20733@end smallexample 20734 20735The intrinsic @code{void __tile_network_barrier (void)} is used to 20736guarantee that no network operations before it are reordered with 20737those after it. 20738 20739@node x86 Built-in Functions 20740@subsection x86 Built-in Functions 20741 20742These built-in functions are available for the x86-32 and x86-64 family 20743of computers, depending on the command-line switches used. 20744 20745If you specify command-line switches such as @option{-msse}, 20746the compiler could use the extended instruction sets even if the built-ins 20747are not used explicitly in the program. For this reason, applications 20748that perform run-time CPU detection must compile separate files for each 20749supported architecture, using the appropriate flags. In particular, 20750the file containing the CPU detection code should be compiled without 20751these options. 20752 20753The following machine modes are available for use with MMX built-in functions 20754(@pxref{Vector Extensions}): @code{V2SI} for a vector of two 32-bit integers, 20755@code{V4HI} for a vector of four 16-bit integers, and @code{V8QI} for a 20756vector of eight 8-bit integers. Some of the built-in functions operate on 20757MMX registers as a whole 64-bit entity, these use @code{V1DI} as their mode. 20758 20759If 3DNow!@: extensions are enabled, @code{V2SF} is used as a mode for a vector 20760of two 32-bit floating-point values. 20761 20762If SSE extensions are enabled, @code{V4SF} is used for a vector of four 32-bit 20763floating-point values. Some instructions use a vector of four 32-bit 20764integers, these use @code{V4SI}. Finally, some instructions operate on an 20765entire vector register, interpreting it as a 128-bit integer, these use mode 20766@code{TI}. 20767 20768The x86-32 and x86-64 family of processors use additional built-in 20769functions for efficient use of @code{TF} (@code{__float128}) 128-bit 20770floating point and @code{TC} 128-bit complex floating-point values. 20771 20772The following floating-point built-in functions are always available. All 20773of them implement the function that is part of the name. 20774 20775@smallexample 20776__float128 __builtin_fabsq (__float128) 20777__float128 __builtin_copysignq (__float128, __float128) 20778@end smallexample 20779 20780The following built-in functions are always available. 20781 20782@table @code 20783@item __float128 __builtin_infq (void) 20784Similar to @code{__builtin_inf}, except the return type is @code{__float128}. 20785@findex __builtin_infq 20786 20787@item __float128 __builtin_huge_valq (void) 20788Similar to @code{__builtin_huge_val}, except the return type is @code{__float128}. 20789@findex __builtin_huge_valq 20790 20791@item __float128 __builtin_nanq (void) 20792Similar to @code{__builtin_nan}, except the return type is @code{__float128}. 20793@findex __builtin_nanq 20794 20795@item __float128 __builtin_nansq (void) 20796Similar to @code{__builtin_nans}, except the return type is @code{__float128}. 20797@findex __builtin_nansq 20798@end table 20799 20800The following built-in function is always available. 20801 20802@table @code 20803@item void __builtin_ia32_pause (void) 20804Generates the @code{pause} machine instruction with a compiler memory 20805barrier. 20806@end table 20807 20808The following built-in functions are always available and can be used to 20809check the target platform type. 20810 20811@deftypefn {Built-in Function} void __builtin_cpu_init (void) 20812This function runs the CPU detection code to check the type of CPU and the 20813features supported. This built-in function needs to be invoked along with the built-in functions 20814to check CPU type and features, @code{__builtin_cpu_is} and 20815@code{__builtin_cpu_supports}, only when used in a function that is 20816executed before any constructors are called. The CPU detection code is 20817automatically executed in a very high priority constructor. 20818 20819For example, this function has to be used in @code{ifunc} resolvers that 20820check for CPU type using the built-in functions @code{__builtin_cpu_is} 20821and @code{__builtin_cpu_supports}, or in constructors on targets that 20822don't support constructor priority. 20823@smallexample 20824 20825static void (*resolve_memcpy (void)) (void) 20826@{ 20827 // ifunc resolvers fire before constructors, explicitly call the init 20828 // function. 20829 __builtin_cpu_init (); 20830 if (__builtin_cpu_supports ("ssse3")) 20831 return ssse3_memcpy; // super fast memcpy with ssse3 instructions. 20832 else 20833 return default_memcpy; 20834@} 20835 20836void *memcpy (void *, const void *, size_t) 20837 __attribute__ ((ifunc ("resolve_memcpy"))); 20838@end smallexample 20839 20840@end deftypefn 20841 20842@deftypefn {Built-in Function} int __builtin_cpu_is (const char *@var{cpuname}) 20843This function returns a positive integer if the run-time CPU 20844is of type @var{cpuname} 20845and returns @code{0} otherwise. The following CPU names can be detected: 20846 20847@table @samp 20848@item intel 20849Intel CPU. 20850 20851@item atom 20852Intel Atom CPU. 20853 20854@item core2 20855Intel Core 2 CPU. 20856 20857@item corei7 20858Intel Core i7 CPU. 20859 20860@item nehalem 20861Intel Core i7 Nehalem CPU. 20862 20863@item westmere 20864Intel Core i7 Westmere CPU. 20865 20866@item sandybridge 20867Intel Core i7 Sandy Bridge CPU. 20868 20869@item amd 20870AMD CPU. 20871 20872@item amdfam10h 20873AMD Family 10h CPU. 20874 20875@item barcelona 20876AMD Family 10h Barcelona CPU. 20877 20878@item shanghai 20879AMD Family 10h Shanghai CPU. 20880 20881@item istanbul 20882AMD Family 10h Istanbul CPU. 20883 20884@item btver1 20885AMD Family 14h CPU. 20886 20887@item amdfam15h 20888AMD Family 15h CPU. 20889 20890@item bdver1 20891AMD Family 15h Bulldozer version 1. 20892 20893@item bdver2 20894AMD Family 15h Bulldozer version 2. 20895 20896@item bdver3 20897AMD Family 15h Bulldozer version 3. 20898 20899@item bdver4 20900AMD Family 15h Bulldozer version 4. 20901 20902@item btver2 20903AMD Family 16h CPU. 20904 20905@item amdfam17h 20906AMD Family 17h CPU. 20907 20908@item znver1 20909AMD Family 17h Zen version 1. 20910@end table 20911 20912Here is an example: 20913@smallexample 20914if (__builtin_cpu_is ("corei7")) 20915 @{ 20916 do_corei7 (); // Core i7 specific implementation. 20917 @} 20918else 20919 @{ 20920 do_generic (); // Generic implementation. 20921 @} 20922@end smallexample 20923@end deftypefn 20924 20925@deftypefn {Built-in Function} int __builtin_cpu_supports (const char *@var{feature}) 20926This function returns a positive integer if the run-time CPU 20927supports @var{feature} 20928and returns @code{0} otherwise. The following features can be detected: 20929 20930@table @samp 20931@item cmov 20932CMOV instruction. 20933@item mmx 20934MMX instructions. 20935@item popcnt 20936POPCNT instruction. 20937@item sse 20938SSE instructions. 20939@item sse2 20940SSE2 instructions. 20941@item sse3 20942SSE3 instructions. 20943@item ssse3 20944SSSE3 instructions. 20945@item sse4.1 20946SSE4.1 instructions. 20947@item sse4.2 20948SSE4.2 instructions. 20949@item avx 20950AVX instructions. 20951@item avx2 20952AVX2 instructions. 20953@item avx512f 20954AVX512F instructions. 20955@end table 20956 20957Here is an example: 20958@smallexample 20959if (__builtin_cpu_supports ("popcnt")) 20960 @{ 20961 asm("popcnt %1,%0" : "=r"(count) : "rm"(n) : "cc"); 20962 @} 20963else 20964 @{ 20965 count = generic_countbits (n); //generic implementation. 20966 @} 20967@end smallexample 20968@end deftypefn 20969 20970 20971The following built-in functions are made available by @option{-mmmx}. 20972All of them generate the machine instruction that is part of the name. 20973 20974@smallexample 20975v8qi __builtin_ia32_paddb (v8qi, v8qi) 20976v4hi __builtin_ia32_paddw (v4hi, v4hi) 20977v2si __builtin_ia32_paddd (v2si, v2si) 20978v8qi __builtin_ia32_psubb (v8qi, v8qi) 20979v4hi __builtin_ia32_psubw (v4hi, v4hi) 20980v2si __builtin_ia32_psubd (v2si, v2si) 20981v8qi __builtin_ia32_paddsb (v8qi, v8qi) 20982v4hi __builtin_ia32_paddsw (v4hi, v4hi) 20983v8qi __builtin_ia32_psubsb (v8qi, v8qi) 20984v4hi __builtin_ia32_psubsw (v4hi, v4hi) 20985v8qi __builtin_ia32_paddusb (v8qi, v8qi) 20986v4hi __builtin_ia32_paddusw (v4hi, v4hi) 20987v8qi __builtin_ia32_psubusb (v8qi, v8qi) 20988v4hi __builtin_ia32_psubusw (v4hi, v4hi) 20989v4hi __builtin_ia32_pmullw (v4hi, v4hi) 20990v4hi __builtin_ia32_pmulhw (v4hi, v4hi) 20991di __builtin_ia32_pand (di, di) 20992di __builtin_ia32_pandn (di,di) 20993di __builtin_ia32_por (di, di) 20994di __builtin_ia32_pxor (di, di) 20995v8qi __builtin_ia32_pcmpeqb (v8qi, v8qi) 20996v4hi __builtin_ia32_pcmpeqw (v4hi, v4hi) 20997v2si __builtin_ia32_pcmpeqd (v2si, v2si) 20998v8qi __builtin_ia32_pcmpgtb (v8qi, v8qi) 20999v4hi __builtin_ia32_pcmpgtw (v4hi, v4hi) 21000v2si __builtin_ia32_pcmpgtd (v2si, v2si) 21001v8qi __builtin_ia32_punpckhbw (v8qi, v8qi) 21002v4hi __builtin_ia32_punpckhwd (v4hi, v4hi) 21003v2si __builtin_ia32_punpckhdq (v2si, v2si) 21004v8qi __builtin_ia32_punpcklbw (v8qi, v8qi) 21005v4hi __builtin_ia32_punpcklwd (v4hi, v4hi) 21006v2si __builtin_ia32_punpckldq (v2si, v2si) 21007v8qi __builtin_ia32_packsswb (v4hi, v4hi) 21008v4hi __builtin_ia32_packssdw (v2si, v2si) 21009v8qi __builtin_ia32_packuswb (v4hi, v4hi) 21010 21011v4hi __builtin_ia32_psllw (v4hi, v4hi) 21012v2si __builtin_ia32_pslld (v2si, v2si) 21013v1di __builtin_ia32_psllq (v1di, v1di) 21014v4hi __builtin_ia32_psrlw (v4hi, v4hi) 21015v2si __builtin_ia32_psrld (v2si, v2si) 21016v1di __builtin_ia32_psrlq (v1di, v1di) 21017v4hi __builtin_ia32_psraw (v4hi, v4hi) 21018v2si __builtin_ia32_psrad (v2si, v2si) 21019v4hi __builtin_ia32_psllwi (v4hi, int) 21020v2si __builtin_ia32_pslldi (v2si, int) 21021v1di __builtin_ia32_psllqi (v1di, int) 21022v4hi __builtin_ia32_psrlwi (v4hi, int) 21023v2si __builtin_ia32_psrldi (v2si, int) 21024v1di __builtin_ia32_psrlqi (v1di, int) 21025v4hi __builtin_ia32_psrawi (v4hi, int) 21026v2si __builtin_ia32_psradi (v2si, int) 21027 21028@end smallexample 21029 21030The following built-in functions are made available either with 21031@option{-msse}, or with @option{-m3dnowa}. All of them generate 21032the machine instruction that is part of the name. 21033 21034@smallexample 21035v4hi __builtin_ia32_pmulhuw (v4hi, v4hi) 21036v8qi __builtin_ia32_pavgb (v8qi, v8qi) 21037v4hi __builtin_ia32_pavgw (v4hi, v4hi) 21038v1di __builtin_ia32_psadbw (v8qi, v8qi) 21039v8qi __builtin_ia32_pmaxub (v8qi, v8qi) 21040v4hi __builtin_ia32_pmaxsw (v4hi, v4hi) 21041v8qi __builtin_ia32_pminub (v8qi, v8qi) 21042v4hi __builtin_ia32_pminsw (v4hi, v4hi) 21043int __builtin_ia32_pmovmskb (v8qi) 21044void __builtin_ia32_maskmovq (v8qi, v8qi, char *) 21045void __builtin_ia32_movntq (di *, di) 21046void __builtin_ia32_sfence (void) 21047@end smallexample 21048 21049The following built-in functions are available when @option{-msse} is used. 21050All of them generate the machine instruction that is part of the name. 21051 21052@smallexample 21053int __builtin_ia32_comieq (v4sf, v4sf) 21054int __builtin_ia32_comineq (v4sf, v4sf) 21055int __builtin_ia32_comilt (v4sf, v4sf) 21056int __builtin_ia32_comile (v4sf, v4sf) 21057int __builtin_ia32_comigt (v4sf, v4sf) 21058int __builtin_ia32_comige (v4sf, v4sf) 21059int __builtin_ia32_ucomieq (v4sf, v4sf) 21060int __builtin_ia32_ucomineq (v4sf, v4sf) 21061int __builtin_ia32_ucomilt (v4sf, v4sf) 21062int __builtin_ia32_ucomile (v4sf, v4sf) 21063int __builtin_ia32_ucomigt (v4sf, v4sf) 21064int __builtin_ia32_ucomige (v4sf, v4sf) 21065v4sf __builtin_ia32_addps (v4sf, v4sf) 21066v4sf __builtin_ia32_subps (v4sf, v4sf) 21067v4sf __builtin_ia32_mulps (v4sf, v4sf) 21068v4sf __builtin_ia32_divps (v4sf, v4sf) 21069v4sf __builtin_ia32_addss (v4sf, v4sf) 21070v4sf __builtin_ia32_subss (v4sf, v4sf) 21071v4sf __builtin_ia32_mulss (v4sf, v4sf) 21072v4sf __builtin_ia32_divss (v4sf, v4sf) 21073v4sf __builtin_ia32_cmpeqps (v4sf, v4sf) 21074v4sf __builtin_ia32_cmpltps (v4sf, v4sf) 21075v4sf __builtin_ia32_cmpleps (v4sf, v4sf) 21076v4sf __builtin_ia32_cmpgtps (v4sf, v4sf) 21077v4sf __builtin_ia32_cmpgeps (v4sf, v4sf) 21078v4sf __builtin_ia32_cmpunordps (v4sf, v4sf) 21079v4sf __builtin_ia32_cmpneqps (v4sf, v4sf) 21080v4sf __builtin_ia32_cmpnltps (v4sf, v4sf) 21081v4sf __builtin_ia32_cmpnleps (v4sf, v4sf) 21082v4sf __builtin_ia32_cmpngtps (v4sf, v4sf) 21083v4sf __builtin_ia32_cmpngeps (v4sf, v4sf) 21084v4sf __builtin_ia32_cmpordps (v4sf, v4sf) 21085v4sf __builtin_ia32_cmpeqss (v4sf, v4sf) 21086v4sf __builtin_ia32_cmpltss (v4sf, v4sf) 21087v4sf __builtin_ia32_cmpless (v4sf, v4sf) 21088v4sf __builtin_ia32_cmpunordss (v4sf, v4sf) 21089v4sf __builtin_ia32_cmpneqss (v4sf, v4sf) 21090v4sf __builtin_ia32_cmpnltss (v4sf, v4sf) 21091v4sf __builtin_ia32_cmpnless (v4sf, v4sf) 21092v4sf __builtin_ia32_cmpordss (v4sf, v4sf) 21093v4sf __builtin_ia32_maxps (v4sf, v4sf) 21094v4sf __builtin_ia32_maxss (v4sf, v4sf) 21095v4sf __builtin_ia32_minps (v4sf, v4sf) 21096v4sf __builtin_ia32_minss (v4sf, v4sf) 21097v4sf __builtin_ia32_andps (v4sf, v4sf) 21098v4sf __builtin_ia32_andnps (v4sf, v4sf) 21099v4sf __builtin_ia32_orps (v4sf, v4sf) 21100v4sf __builtin_ia32_xorps (v4sf, v4sf) 21101v4sf __builtin_ia32_movss (v4sf, v4sf) 21102v4sf __builtin_ia32_movhlps (v4sf, v4sf) 21103v4sf __builtin_ia32_movlhps (v4sf, v4sf) 21104v4sf __builtin_ia32_unpckhps (v4sf, v4sf) 21105v4sf __builtin_ia32_unpcklps (v4sf, v4sf) 21106v4sf __builtin_ia32_cvtpi2ps (v4sf, v2si) 21107v4sf __builtin_ia32_cvtsi2ss (v4sf, int) 21108v2si __builtin_ia32_cvtps2pi (v4sf) 21109int __builtin_ia32_cvtss2si (v4sf) 21110v2si __builtin_ia32_cvttps2pi (v4sf) 21111int __builtin_ia32_cvttss2si (v4sf) 21112v4sf __builtin_ia32_rcpps (v4sf) 21113v4sf __builtin_ia32_rsqrtps (v4sf) 21114v4sf __builtin_ia32_sqrtps (v4sf) 21115v4sf __builtin_ia32_rcpss (v4sf) 21116v4sf __builtin_ia32_rsqrtss (v4sf) 21117v4sf __builtin_ia32_sqrtss (v4sf) 21118v4sf __builtin_ia32_shufps (v4sf, v4sf, int) 21119void __builtin_ia32_movntps (float *, v4sf) 21120int __builtin_ia32_movmskps (v4sf) 21121@end smallexample 21122 21123The following built-in functions are available when @option{-msse} is used. 21124 21125@table @code 21126@item v4sf __builtin_ia32_loadups (float *) 21127Generates the @code{movups} machine instruction as a load from memory. 21128@item void __builtin_ia32_storeups (float *, v4sf) 21129Generates the @code{movups} machine instruction as a store to memory. 21130@item v4sf __builtin_ia32_loadss (float *) 21131Generates the @code{movss} machine instruction as a load from memory. 21132@item v4sf __builtin_ia32_loadhps (v4sf, const v2sf *) 21133Generates the @code{movhps} machine instruction as a load from memory. 21134@item v4sf __builtin_ia32_loadlps (v4sf, const v2sf *) 21135Generates the @code{movlps} machine instruction as a load from memory 21136@item void __builtin_ia32_storehps (v2sf *, v4sf) 21137Generates the @code{movhps} machine instruction as a store to memory. 21138@item void __builtin_ia32_storelps (v2sf *, v4sf) 21139Generates the @code{movlps} machine instruction as a store to memory. 21140@end table 21141 21142The following built-in functions are available when @option{-msse2} is used. 21143All of them generate the machine instruction that is part of the name. 21144 21145@smallexample 21146int __builtin_ia32_comisdeq (v2df, v2df) 21147int __builtin_ia32_comisdlt (v2df, v2df) 21148int __builtin_ia32_comisdle (v2df, v2df) 21149int __builtin_ia32_comisdgt (v2df, v2df) 21150int __builtin_ia32_comisdge (v2df, v2df) 21151int __builtin_ia32_comisdneq (v2df, v2df) 21152int __builtin_ia32_ucomisdeq (v2df, v2df) 21153int __builtin_ia32_ucomisdlt (v2df, v2df) 21154int __builtin_ia32_ucomisdle (v2df, v2df) 21155int __builtin_ia32_ucomisdgt (v2df, v2df) 21156int __builtin_ia32_ucomisdge (v2df, v2df) 21157int __builtin_ia32_ucomisdneq (v2df, v2df) 21158v2df __builtin_ia32_cmpeqpd (v2df, v2df) 21159v2df __builtin_ia32_cmpltpd (v2df, v2df) 21160v2df __builtin_ia32_cmplepd (v2df, v2df) 21161v2df __builtin_ia32_cmpgtpd (v2df, v2df) 21162v2df __builtin_ia32_cmpgepd (v2df, v2df) 21163v2df __builtin_ia32_cmpunordpd (v2df, v2df) 21164v2df __builtin_ia32_cmpneqpd (v2df, v2df) 21165v2df __builtin_ia32_cmpnltpd (v2df, v2df) 21166v2df __builtin_ia32_cmpnlepd (v2df, v2df) 21167v2df __builtin_ia32_cmpngtpd (v2df, v2df) 21168v2df __builtin_ia32_cmpngepd (v2df, v2df) 21169v2df __builtin_ia32_cmpordpd (v2df, v2df) 21170v2df __builtin_ia32_cmpeqsd (v2df, v2df) 21171v2df __builtin_ia32_cmpltsd (v2df, v2df) 21172v2df __builtin_ia32_cmplesd (v2df, v2df) 21173v2df __builtin_ia32_cmpunordsd (v2df, v2df) 21174v2df __builtin_ia32_cmpneqsd (v2df, v2df) 21175v2df __builtin_ia32_cmpnltsd (v2df, v2df) 21176v2df __builtin_ia32_cmpnlesd (v2df, v2df) 21177v2df __builtin_ia32_cmpordsd (v2df, v2df) 21178v2di __builtin_ia32_paddq (v2di, v2di) 21179v2di __builtin_ia32_psubq (v2di, v2di) 21180v2df __builtin_ia32_addpd (v2df, v2df) 21181v2df __builtin_ia32_subpd (v2df, v2df) 21182v2df __builtin_ia32_mulpd (v2df, v2df) 21183v2df __builtin_ia32_divpd (v2df, v2df) 21184v2df __builtin_ia32_addsd (v2df, v2df) 21185v2df __builtin_ia32_subsd (v2df, v2df) 21186v2df __builtin_ia32_mulsd (v2df, v2df) 21187v2df __builtin_ia32_divsd (v2df, v2df) 21188v2df __builtin_ia32_minpd (v2df, v2df) 21189v2df __builtin_ia32_maxpd (v2df, v2df) 21190v2df __builtin_ia32_minsd (v2df, v2df) 21191v2df __builtin_ia32_maxsd (v2df, v2df) 21192v2df __builtin_ia32_andpd (v2df, v2df) 21193v2df __builtin_ia32_andnpd (v2df, v2df) 21194v2df __builtin_ia32_orpd (v2df, v2df) 21195v2df __builtin_ia32_xorpd (v2df, v2df) 21196v2df __builtin_ia32_movsd (v2df, v2df) 21197v2df __builtin_ia32_unpckhpd (v2df, v2df) 21198v2df __builtin_ia32_unpcklpd (v2df, v2df) 21199v16qi __builtin_ia32_paddb128 (v16qi, v16qi) 21200v8hi __builtin_ia32_paddw128 (v8hi, v8hi) 21201v4si __builtin_ia32_paddd128 (v4si, v4si) 21202v2di __builtin_ia32_paddq128 (v2di, v2di) 21203v16qi __builtin_ia32_psubb128 (v16qi, v16qi) 21204v8hi __builtin_ia32_psubw128 (v8hi, v8hi) 21205v4si __builtin_ia32_psubd128 (v4si, v4si) 21206v2di __builtin_ia32_psubq128 (v2di, v2di) 21207v8hi __builtin_ia32_pmullw128 (v8hi, v8hi) 21208v8hi __builtin_ia32_pmulhw128 (v8hi, v8hi) 21209v2di __builtin_ia32_pand128 (v2di, v2di) 21210v2di __builtin_ia32_pandn128 (v2di, v2di) 21211v2di __builtin_ia32_por128 (v2di, v2di) 21212v2di __builtin_ia32_pxor128 (v2di, v2di) 21213v16qi __builtin_ia32_pavgb128 (v16qi, v16qi) 21214v8hi __builtin_ia32_pavgw128 (v8hi, v8hi) 21215v16qi __builtin_ia32_pcmpeqb128 (v16qi, v16qi) 21216v8hi __builtin_ia32_pcmpeqw128 (v8hi, v8hi) 21217v4si __builtin_ia32_pcmpeqd128 (v4si, v4si) 21218v16qi __builtin_ia32_pcmpgtb128 (v16qi, v16qi) 21219v8hi __builtin_ia32_pcmpgtw128 (v8hi, v8hi) 21220v4si __builtin_ia32_pcmpgtd128 (v4si, v4si) 21221v16qi __builtin_ia32_pmaxub128 (v16qi, v16qi) 21222v8hi __builtin_ia32_pmaxsw128 (v8hi, v8hi) 21223v16qi __builtin_ia32_pminub128 (v16qi, v16qi) 21224v8hi __builtin_ia32_pminsw128 (v8hi, v8hi) 21225v16qi __builtin_ia32_punpckhbw128 (v16qi, v16qi) 21226v8hi __builtin_ia32_punpckhwd128 (v8hi, v8hi) 21227v4si __builtin_ia32_punpckhdq128 (v4si, v4si) 21228v2di __builtin_ia32_punpckhqdq128 (v2di, v2di) 21229v16qi __builtin_ia32_punpcklbw128 (v16qi, v16qi) 21230v8hi __builtin_ia32_punpcklwd128 (v8hi, v8hi) 21231v4si __builtin_ia32_punpckldq128 (v4si, v4si) 21232v2di __builtin_ia32_punpcklqdq128 (v2di, v2di) 21233v16qi __builtin_ia32_packsswb128 (v8hi, v8hi) 21234v8hi __builtin_ia32_packssdw128 (v4si, v4si) 21235v16qi __builtin_ia32_packuswb128 (v8hi, v8hi) 21236v8hi __builtin_ia32_pmulhuw128 (v8hi, v8hi) 21237void __builtin_ia32_maskmovdqu (v16qi, v16qi) 21238v2df __builtin_ia32_loadupd (double *) 21239void __builtin_ia32_storeupd (double *, v2df) 21240v2df __builtin_ia32_loadhpd (v2df, double const *) 21241v2df __builtin_ia32_loadlpd (v2df, double const *) 21242int __builtin_ia32_movmskpd (v2df) 21243int __builtin_ia32_pmovmskb128 (v16qi) 21244void __builtin_ia32_movnti (int *, int) 21245void __builtin_ia32_movnti64 (long long int *, long long int) 21246void __builtin_ia32_movntpd (double *, v2df) 21247void __builtin_ia32_movntdq (v2df *, v2df) 21248v4si __builtin_ia32_pshufd (v4si, int) 21249v8hi __builtin_ia32_pshuflw (v8hi, int) 21250v8hi __builtin_ia32_pshufhw (v8hi, int) 21251v2di __builtin_ia32_psadbw128 (v16qi, v16qi) 21252v2df __builtin_ia32_sqrtpd (v2df) 21253v2df __builtin_ia32_sqrtsd (v2df) 21254v2df __builtin_ia32_shufpd (v2df, v2df, int) 21255v2df __builtin_ia32_cvtdq2pd (v4si) 21256v4sf __builtin_ia32_cvtdq2ps (v4si) 21257v4si __builtin_ia32_cvtpd2dq (v2df) 21258v2si __builtin_ia32_cvtpd2pi (v2df) 21259v4sf __builtin_ia32_cvtpd2ps (v2df) 21260v4si __builtin_ia32_cvttpd2dq (v2df) 21261v2si __builtin_ia32_cvttpd2pi (v2df) 21262v2df __builtin_ia32_cvtpi2pd (v2si) 21263int __builtin_ia32_cvtsd2si (v2df) 21264int __builtin_ia32_cvttsd2si (v2df) 21265long long __builtin_ia32_cvtsd2si64 (v2df) 21266long long __builtin_ia32_cvttsd2si64 (v2df) 21267v4si __builtin_ia32_cvtps2dq (v4sf) 21268v2df __builtin_ia32_cvtps2pd (v4sf) 21269v4si __builtin_ia32_cvttps2dq (v4sf) 21270v2df __builtin_ia32_cvtsi2sd (v2df, int) 21271v2df __builtin_ia32_cvtsi642sd (v2df, long long) 21272v4sf __builtin_ia32_cvtsd2ss (v4sf, v2df) 21273v2df __builtin_ia32_cvtss2sd (v2df, v4sf) 21274void __builtin_ia32_clflush (const void *) 21275void __builtin_ia32_lfence (void) 21276void __builtin_ia32_mfence (void) 21277v16qi __builtin_ia32_loaddqu (const char *) 21278void __builtin_ia32_storedqu (char *, v16qi) 21279v1di __builtin_ia32_pmuludq (v2si, v2si) 21280v2di __builtin_ia32_pmuludq128 (v4si, v4si) 21281v8hi __builtin_ia32_psllw128 (v8hi, v8hi) 21282v4si __builtin_ia32_pslld128 (v4si, v4si) 21283v2di __builtin_ia32_psllq128 (v2di, v2di) 21284v8hi __builtin_ia32_psrlw128 (v8hi, v8hi) 21285v4si __builtin_ia32_psrld128 (v4si, v4si) 21286v2di __builtin_ia32_psrlq128 (v2di, v2di) 21287v8hi __builtin_ia32_psraw128 (v8hi, v8hi) 21288v4si __builtin_ia32_psrad128 (v4si, v4si) 21289v2di __builtin_ia32_pslldqi128 (v2di, int) 21290v8hi __builtin_ia32_psllwi128 (v8hi, int) 21291v4si __builtin_ia32_pslldi128 (v4si, int) 21292v2di __builtin_ia32_psllqi128 (v2di, int) 21293v2di __builtin_ia32_psrldqi128 (v2di, int) 21294v8hi __builtin_ia32_psrlwi128 (v8hi, int) 21295v4si __builtin_ia32_psrldi128 (v4si, int) 21296v2di __builtin_ia32_psrlqi128 (v2di, int) 21297v8hi __builtin_ia32_psrawi128 (v8hi, int) 21298v4si __builtin_ia32_psradi128 (v4si, int) 21299v4si __builtin_ia32_pmaddwd128 (v8hi, v8hi) 21300v2di __builtin_ia32_movq128 (v2di) 21301@end smallexample 21302 21303The following built-in functions are available when @option{-msse3} is used. 21304All of them generate the machine instruction that is part of the name. 21305 21306@smallexample 21307v2df __builtin_ia32_addsubpd (v2df, v2df) 21308v4sf __builtin_ia32_addsubps (v4sf, v4sf) 21309v2df __builtin_ia32_haddpd (v2df, v2df) 21310v4sf __builtin_ia32_haddps (v4sf, v4sf) 21311v2df __builtin_ia32_hsubpd (v2df, v2df) 21312v4sf __builtin_ia32_hsubps (v4sf, v4sf) 21313v16qi __builtin_ia32_lddqu (char const *) 21314void __builtin_ia32_monitor (void *, unsigned int, unsigned int) 21315v4sf __builtin_ia32_movshdup (v4sf) 21316v4sf __builtin_ia32_movsldup (v4sf) 21317void __builtin_ia32_mwait (unsigned int, unsigned int) 21318@end smallexample 21319 21320The following built-in functions are available when @option{-mssse3} is used. 21321All of them generate the machine instruction that is part of the name. 21322 21323@smallexample 21324v2si __builtin_ia32_phaddd (v2si, v2si) 21325v4hi __builtin_ia32_phaddw (v4hi, v4hi) 21326v4hi __builtin_ia32_phaddsw (v4hi, v4hi) 21327v2si __builtin_ia32_phsubd (v2si, v2si) 21328v4hi __builtin_ia32_phsubw (v4hi, v4hi) 21329v4hi __builtin_ia32_phsubsw (v4hi, v4hi) 21330v4hi __builtin_ia32_pmaddubsw (v8qi, v8qi) 21331v4hi __builtin_ia32_pmulhrsw (v4hi, v4hi) 21332v8qi __builtin_ia32_pshufb (v8qi, v8qi) 21333v8qi __builtin_ia32_psignb (v8qi, v8qi) 21334v2si __builtin_ia32_psignd (v2si, v2si) 21335v4hi __builtin_ia32_psignw (v4hi, v4hi) 21336v1di __builtin_ia32_palignr (v1di, v1di, int) 21337v8qi __builtin_ia32_pabsb (v8qi) 21338v2si __builtin_ia32_pabsd (v2si) 21339v4hi __builtin_ia32_pabsw (v4hi) 21340@end smallexample 21341 21342The following built-in functions are available when @option{-mssse3} is used. 21343All of them generate the machine instruction that is part of the name. 21344 21345@smallexample 21346v4si __builtin_ia32_phaddd128 (v4si, v4si) 21347v8hi __builtin_ia32_phaddw128 (v8hi, v8hi) 21348v8hi __builtin_ia32_phaddsw128 (v8hi, v8hi) 21349v4si __builtin_ia32_phsubd128 (v4si, v4si) 21350v8hi __builtin_ia32_phsubw128 (v8hi, v8hi) 21351v8hi __builtin_ia32_phsubsw128 (v8hi, v8hi) 21352v8hi __builtin_ia32_pmaddubsw128 (v16qi, v16qi) 21353v8hi __builtin_ia32_pmulhrsw128 (v8hi, v8hi) 21354v16qi __builtin_ia32_pshufb128 (v16qi, v16qi) 21355v16qi __builtin_ia32_psignb128 (v16qi, v16qi) 21356v4si __builtin_ia32_psignd128 (v4si, v4si) 21357v8hi __builtin_ia32_psignw128 (v8hi, v8hi) 21358v2di __builtin_ia32_palignr128 (v2di, v2di, int) 21359v16qi __builtin_ia32_pabsb128 (v16qi) 21360v4si __builtin_ia32_pabsd128 (v4si) 21361v8hi __builtin_ia32_pabsw128 (v8hi) 21362@end smallexample 21363 21364The following built-in functions are available when @option{-msse4.1} is 21365used. All of them generate the machine instruction that is part of the 21366name. 21367 21368@smallexample 21369v2df __builtin_ia32_blendpd (v2df, v2df, const int) 21370v4sf __builtin_ia32_blendps (v4sf, v4sf, const int) 21371v2df __builtin_ia32_blendvpd (v2df, v2df, v2df) 21372v4sf __builtin_ia32_blendvps (v4sf, v4sf, v4sf) 21373v2df __builtin_ia32_dppd (v2df, v2df, const int) 21374v4sf __builtin_ia32_dpps (v4sf, v4sf, const int) 21375v4sf __builtin_ia32_insertps128 (v4sf, v4sf, const int) 21376v2di __builtin_ia32_movntdqa (v2di *); 21377v16qi __builtin_ia32_mpsadbw128 (v16qi, v16qi, const int) 21378v8hi __builtin_ia32_packusdw128 (v4si, v4si) 21379v16qi __builtin_ia32_pblendvb128 (v16qi, v16qi, v16qi) 21380v8hi __builtin_ia32_pblendw128 (v8hi, v8hi, const int) 21381v2di __builtin_ia32_pcmpeqq (v2di, v2di) 21382v8hi __builtin_ia32_phminposuw128 (v8hi) 21383v16qi __builtin_ia32_pmaxsb128 (v16qi, v16qi) 21384v4si __builtin_ia32_pmaxsd128 (v4si, v4si) 21385v4si __builtin_ia32_pmaxud128 (v4si, v4si) 21386v8hi __builtin_ia32_pmaxuw128 (v8hi, v8hi) 21387v16qi __builtin_ia32_pminsb128 (v16qi, v16qi) 21388v4si __builtin_ia32_pminsd128 (v4si, v4si) 21389v4si __builtin_ia32_pminud128 (v4si, v4si) 21390v8hi __builtin_ia32_pminuw128 (v8hi, v8hi) 21391v4si __builtin_ia32_pmovsxbd128 (v16qi) 21392v2di __builtin_ia32_pmovsxbq128 (v16qi) 21393v8hi __builtin_ia32_pmovsxbw128 (v16qi) 21394v2di __builtin_ia32_pmovsxdq128 (v4si) 21395v4si __builtin_ia32_pmovsxwd128 (v8hi) 21396v2di __builtin_ia32_pmovsxwq128 (v8hi) 21397v4si __builtin_ia32_pmovzxbd128 (v16qi) 21398v2di __builtin_ia32_pmovzxbq128 (v16qi) 21399v8hi __builtin_ia32_pmovzxbw128 (v16qi) 21400v2di __builtin_ia32_pmovzxdq128 (v4si) 21401v4si __builtin_ia32_pmovzxwd128 (v8hi) 21402v2di __builtin_ia32_pmovzxwq128 (v8hi) 21403v2di __builtin_ia32_pmuldq128 (v4si, v4si) 21404v4si __builtin_ia32_pmulld128 (v4si, v4si) 21405int __builtin_ia32_ptestc128 (v2di, v2di) 21406int __builtin_ia32_ptestnzc128 (v2di, v2di) 21407int __builtin_ia32_ptestz128 (v2di, v2di) 21408v2df __builtin_ia32_roundpd (v2df, const int) 21409v4sf __builtin_ia32_roundps (v4sf, const int) 21410v2df __builtin_ia32_roundsd (v2df, v2df, const int) 21411v4sf __builtin_ia32_roundss (v4sf, v4sf, const int) 21412@end smallexample 21413 21414The following built-in functions are available when @option{-msse4.1} is 21415used. 21416 21417@table @code 21418@item v4sf __builtin_ia32_vec_set_v4sf (v4sf, float, const int) 21419Generates the @code{insertps} machine instruction. 21420@item int __builtin_ia32_vec_ext_v16qi (v16qi, const int) 21421Generates the @code{pextrb} machine instruction. 21422@item v16qi __builtin_ia32_vec_set_v16qi (v16qi, int, const int) 21423Generates the @code{pinsrb} machine instruction. 21424@item v4si __builtin_ia32_vec_set_v4si (v4si, int, const int) 21425Generates the @code{pinsrd} machine instruction. 21426@item v2di __builtin_ia32_vec_set_v2di (v2di, long long, const int) 21427Generates the @code{pinsrq} machine instruction in 64bit mode. 21428@end table 21429 21430The following built-in functions are changed to generate new SSE4.1 21431instructions when @option{-msse4.1} is used. 21432 21433@table @code 21434@item float __builtin_ia32_vec_ext_v4sf (v4sf, const int) 21435Generates the @code{extractps} machine instruction. 21436@item int __builtin_ia32_vec_ext_v4si (v4si, const int) 21437Generates the @code{pextrd} machine instruction. 21438@item long long __builtin_ia32_vec_ext_v2di (v2di, const int) 21439Generates the @code{pextrq} machine instruction in 64bit mode. 21440@end table 21441 21442The following built-in functions are available when @option{-msse4.2} is 21443used. All of them generate the machine instruction that is part of the 21444name. 21445 21446@smallexample 21447v16qi __builtin_ia32_pcmpestrm128 (v16qi, int, v16qi, int, const int) 21448int __builtin_ia32_pcmpestri128 (v16qi, int, v16qi, int, const int) 21449int __builtin_ia32_pcmpestria128 (v16qi, int, v16qi, int, const int) 21450int __builtin_ia32_pcmpestric128 (v16qi, int, v16qi, int, const int) 21451int __builtin_ia32_pcmpestrio128 (v16qi, int, v16qi, int, const int) 21452int __builtin_ia32_pcmpestris128 (v16qi, int, v16qi, int, const int) 21453int __builtin_ia32_pcmpestriz128 (v16qi, int, v16qi, int, const int) 21454v16qi __builtin_ia32_pcmpistrm128 (v16qi, v16qi, const int) 21455int __builtin_ia32_pcmpistri128 (v16qi, v16qi, const int) 21456int __builtin_ia32_pcmpistria128 (v16qi, v16qi, const int) 21457int __builtin_ia32_pcmpistric128 (v16qi, v16qi, const int) 21458int __builtin_ia32_pcmpistrio128 (v16qi, v16qi, const int) 21459int __builtin_ia32_pcmpistris128 (v16qi, v16qi, const int) 21460int __builtin_ia32_pcmpistriz128 (v16qi, v16qi, const int) 21461v2di __builtin_ia32_pcmpgtq (v2di, v2di) 21462@end smallexample 21463 21464The following built-in functions are available when @option{-msse4.2} is 21465used. 21466 21467@table @code 21468@item unsigned int __builtin_ia32_crc32qi (unsigned int, unsigned char) 21469Generates the @code{crc32b} machine instruction. 21470@item unsigned int __builtin_ia32_crc32hi (unsigned int, unsigned short) 21471Generates the @code{crc32w} machine instruction. 21472@item unsigned int __builtin_ia32_crc32si (unsigned int, unsigned int) 21473Generates the @code{crc32l} machine instruction. 21474@item unsigned long long __builtin_ia32_crc32di (unsigned long long, unsigned long long) 21475Generates the @code{crc32q} machine instruction. 21476@end table 21477 21478The following built-in functions are changed to generate new SSE4.2 21479instructions when @option{-msse4.2} is used. 21480 21481@table @code 21482@item int __builtin_popcount (unsigned int) 21483Generates the @code{popcntl} machine instruction. 21484@item int __builtin_popcountl (unsigned long) 21485Generates the @code{popcntl} or @code{popcntq} machine instruction, 21486depending on the size of @code{unsigned long}. 21487@item int __builtin_popcountll (unsigned long long) 21488Generates the @code{popcntq} machine instruction. 21489@end table 21490 21491The following built-in functions are available when @option{-mavx} is 21492used. All of them generate the machine instruction that is part of the 21493name. 21494 21495@smallexample 21496v4df __builtin_ia32_addpd256 (v4df,v4df) 21497v8sf __builtin_ia32_addps256 (v8sf,v8sf) 21498v4df __builtin_ia32_addsubpd256 (v4df,v4df) 21499v8sf __builtin_ia32_addsubps256 (v8sf,v8sf) 21500v4df __builtin_ia32_andnpd256 (v4df,v4df) 21501v8sf __builtin_ia32_andnps256 (v8sf,v8sf) 21502v4df __builtin_ia32_andpd256 (v4df,v4df) 21503v8sf __builtin_ia32_andps256 (v8sf,v8sf) 21504v4df __builtin_ia32_blendpd256 (v4df,v4df,int) 21505v8sf __builtin_ia32_blendps256 (v8sf,v8sf,int) 21506v4df __builtin_ia32_blendvpd256 (v4df,v4df,v4df) 21507v8sf __builtin_ia32_blendvps256 (v8sf,v8sf,v8sf) 21508v2df __builtin_ia32_cmppd (v2df,v2df,int) 21509v4df __builtin_ia32_cmppd256 (v4df,v4df,int) 21510v4sf __builtin_ia32_cmpps (v4sf,v4sf,int) 21511v8sf __builtin_ia32_cmpps256 (v8sf,v8sf,int) 21512v2df __builtin_ia32_cmpsd (v2df,v2df,int) 21513v4sf __builtin_ia32_cmpss (v4sf,v4sf,int) 21514v4df __builtin_ia32_cvtdq2pd256 (v4si) 21515v8sf __builtin_ia32_cvtdq2ps256 (v8si) 21516v4si __builtin_ia32_cvtpd2dq256 (v4df) 21517v4sf __builtin_ia32_cvtpd2ps256 (v4df) 21518v8si __builtin_ia32_cvtps2dq256 (v8sf) 21519v4df __builtin_ia32_cvtps2pd256 (v4sf) 21520v4si __builtin_ia32_cvttpd2dq256 (v4df) 21521v8si __builtin_ia32_cvttps2dq256 (v8sf) 21522v4df __builtin_ia32_divpd256 (v4df,v4df) 21523v8sf __builtin_ia32_divps256 (v8sf,v8sf) 21524v8sf __builtin_ia32_dpps256 (v8sf,v8sf,int) 21525v4df __builtin_ia32_haddpd256 (v4df,v4df) 21526v8sf __builtin_ia32_haddps256 (v8sf,v8sf) 21527v4df __builtin_ia32_hsubpd256 (v4df,v4df) 21528v8sf __builtin_ia32_hsubps256 (v8sf,v8sf) 21529v32qi __builtin_ia32_lddqu256 (pcchar) 21530v32qi __builtin_ia32_loaddqu256 (pcchar) 21531v4df __builtin_ia32_loadupd256 (pcdouble) 21532v8sf __builtin_ia32_loadups256 (pcfloat) 21533v2df __builtin_ia32_maskloadpd (pcv2df,v2df) 21534v4df __builtin_ia32_maskloadpd256 (pcv4df,v4df) 21535v4sf __builtin_ia32_maskloadps (pcv4sf,v4sf) 21536v8sf __builtin_ia32_maskloadps256 (pcv8sf,v8sf) 21537void __builtin_ia32_maskstorepd (pv2df,v2df,v2df) 21538void __builtin_ia32_maskstorepd256 (pv4df,v4df,v4df) 21539void __builtin_ia32_maskstoreps (pv4sf,v4sf,v4sf) 21540void __builtin_ia32_maskstoreps256 (pv8sf,v8sf,v8sf) 21541v4df __builtin_ia32_maxpd256 (v4df,v4df) 21542v8sf __builtin_ia32_maxps256 (v8sf,v8sf) 21543v4df __builtin_ia32_minpd256 (v4df,v4df) 21544v8sf __builtin_ia32_minps256 (v8sf,v8sf) 21545v4df __builtin_ia32_movddup256 (v4df) 21546int __builtin_ia32_movmskpd256 (v4df) 21547int __builtin_ia32_movmskps256 (v8sf) 21548v8sf __builtin_ia32_movshdup256 (v8sf) 21549v8sf __builtin_ia32_movsldup256 (v8sf) 21550v4df __builtin_ia32_mulpd256 (v4df,v4df) 21551v8sf __builtin_ia32_mulps256 (v8sf,v8sf) 21552v4df __builtin_ia32_orpd256 (v4df,v4df) 21553v8sf __builtin_ia32_orps256 (v8sf,v8sf) 21554v2df __builtin_ia32_pd_pd256 (v4df) 21555v4df __builtin_ia32_pd256_pd (v2df) 21556v4sf __builtin_ia32_ps_ps256 (v8sf) 21557v8sf __builtin_ia32_ps256_ps (v4sf) 21558int __builtin_ia32_ptestc256 (v4di,v4di,ptest) 21559int __builtin_ia32_ptestnzc256 (v4di,v4di,ptest) 21560int __builtin_ia32_ptestz256 (v4di,v4di,ptest) 21561v8sf __builtin_ia32_rcpps256 (v8sf) 21562v4df __builtin_ia32_roundpd256 (v4df,int) 21563v8sf __builtin_ia32_roundps256 (v8sf,int) 21564v8sf __builtin_ia32_rsqrtps_nr256 (v8sf) 21565v8sf __builtin_ia32_rsqrtps256 (v8sf) 21566v4df __builtin_ia32_shufpd256 (v4df,v4df,int) 21567v8sf __builtin_ia32_shufps256 (v8sf,v8sf,int) 21568v4si __builtin_ia32_si_si256 (v8si) 21569v8si __builtin_ia32_si256_si (v4si) 21570v4df __builtin_ia32_sqrtpd256 (v4df) 21571v8sf __builtin_ia32_sqrtps_nr256 (v8sf) 21572v8sf __builtin_ia32_sqrtps256 (v8sf) 21573void __builtin_ia32_storedqu256 (pchar,v32qi) 21574void __builtin_ia32_storeupd256 (pdouble,v4df) 21575void __builtin_ia32_storeups256 (pfloat,v8sf) 21576v4df __builtin_ia32_subpd256 (v4df,v4df) 21577v8sf __builtin_ia32_subps256 (v8sf,v8sf) 21578v4df __builtin_ia32_unpckhpd256 (v4df,v4df) 21579v8sf __builtin_ia32_unpckhps256 (v8sf,v8sf) 21580v4df __builtin_ia32_unpcklpd256 (v4df,v4df) 21581v8sf __builtin_ia32_unpcklps256 (v8sf,v8sf) 21582v4df __builtin_ia32_vbroadcastf128_pd256 (pcv2df) 21583v8sf __builtin_ia32_vbroadcastf128_ps256 (pcv4sf) 21584v4df __builtin_ia32_vbroadcastsd256 (pcdouble) 21585v4sf __builtin_ia32_vbroadcastss (pcfloat) 21586v8sf __builtin_ia32_vbroadcastss256 (pcfloat) 21587v2df __builtin_ia32_vextractf128_pd256 (v4df,int) 21588v4sf __builtin_ia32_vextractf128_ps256 (v8sf,int) 21589v4si __builtin_ia32_vextractf128_si256 (v8si,int) 21590v4df __builtin_ia32_vinsertf128_pd256 (v4df,v2df,int) 21591v8sf __builtin_ia32_vinsertf128_ps256 (v8sf,v4sf,int) 21592v8si __builtin_ia32_vinsertf128_si256 (v8si,v4si,int) 21593v4df __builtin_ia32_vperm2f128_pd256 (v4df,v4df,int) 21594v8sf __builtin_ia32_vperm2f128_ps256 (v8sf,v8sf,int) 21595v8si __builtin_ia32_vperm2f128_si256 (v8si,v8si,int) 21596v2df __builtin_ia32_vpermil2pd (v2df,v2df,v2di,int) 21597v4df __builtin_ia32_vpermil2pd256 (v4df,v4df,v4di,int) 21598v4sf __builtin_ia32_vpermil2ps (v4sf,v4sf,v4si,int) 21599v8sf __builtin_ia32_vpermil2ps256 (v8sf,v8sf,v8si,int) 21600v2df __builtin_ia32_vpermilpd (v2df,int) 21601v4df __builtin_ia32_vpermilpd256 (v4df,int) 21602v4sf __builtin_ia32_vpermilps (v4sf,int) 21603v8sf __builtin_ia32_vpermilps256 (v8sf,int) 21604v2df __builtin_ia32_vpermilvarpd (v2df,v2di) 21605v4df __builtin_ia32_vpermilvarpd256 (v4df,v4di) 21606v4sf __builtin_ia32_vpermilvarps (v4sf,v4si) 21607v8sf __builtin_ia32_vpermilvarps256 (v8sf,v8si) 21608int __builtin_ia32_vtestcpd (v2df,v2df,ptest) 21609int __builtin_ia32_vtestcpd256 (v4df,v4df,ptest) 21610int __builtin_ia32_vtestcps (v4sf,v4sf,ptest) 21611int __builtin_ia32_vtestcps256 (v8sf,v8sf,ptest) 21612int __builtin_ia32_vtestnzcpd (v2df,v2df,ptest) 21613int __builtin_ia32_vtestnzcpd256 (v4df,v4df,ptest) 21614int __builtin_ia32_vtestnzcps (v4sf,v4sf,ptest) 21615int __builtin_ia32_vtestnzcps256 (v8sf,v8sf,ptest) 21616int __builtin_ia32_vtestzpd (v2df,v2df,ptest) 21617int __builtin_ia32_vtestzpd256 (v4df,v4df,ptest) 21618int __builtin_ia32_vtestzps (v4sf,v4sf,ptest) 21619int __builtin_ia32_vtestzps256 (v8sf,v8sf,ptest) 21620void __builtin_ia32_vzeroall (void) 21621void __builtin_ia32_vzeroupper (void) 21622v4df __builtin_ia32_xorpd256 (v4df,v4df) 21623v8sf __builtin_ia32_xorps256 (v8sf,v8sf) 21624@end smallexample 21625 21626The following built-in functions are available when @option{-mavx2} is 21627used. All of them generate the machine instruction that is part of the 21628name. 21629 21630@smallexample 21631v32qi __builtin_ia32_mpsadbw256 (v32qi,v32qi,int) 21632v32qi __builtin_ia32_pabsb256 (v32qi) 21633v16hi __builtin_ia32_pabsw256 (v16hi) 21634v8si __builtin_ia32_pabsd256 (v8si) 21635v16hi __builtin_ia32_packssdw256 (v8si,v8si) 21636v32qi __builtin_ia32_packsswb256 (v16hi,v16hi) 21637v16hi __builtin_ia32_packusdw256 (v8si,v8si) 21638v32qi __builtin_ia32_packuswb256 (v16hi,v16hi) 21639v32qi __builtin_ia32_paddb256 (v32qi,v32qi) 21640v16hi __builtin_ia32_paddw256 (v16hi,v16hi) 21641v8si __builtin_ia32_paddd256 (v8si,v8si) 21642v4di __builtin_ia32_paddq256 (v4di,v4di) 21643v32qi __builtin_ia32_paddsb256 (v32qi,v32qi) 21644v16hi __builtin_ia32_paddsw256 (v16hi,v16hi) 21645v32qi __builtin_ia32_paddusb256 (v32qi,v32qi) 21646v16hi __builtin_ia32_paddusw256 (v16hi,v16hi) 21647v4di __builtin_ia32_palignr256 (v4di,v4di,int) 21648v4di __builtin_ia32_andsi256 (v4di,v4di) 21649v4di __builtin_ia32_andnotsi256 (v4di,v4di) 21650v32qi __builtin_ia32_pavgb256 (v32qi,v32qi) 21651v16hi __builtin_ia32_pavgw256 (v16hi,v16hi) 21652v32qi __builtin_ia32_pblendvb256 (v32qi,v32qi,v32qi) 21653v16hi __builtin_ia32_pblendw256 (v16hi,v16hi,int) 21654v32qi __builtin_ia32_pcmpeqb256 (v32qi,v32qi) 21655v16hi __builtin_ia32_pcmpeqw256 (v16hi,v16hi) 21656v8si __builtin_ia32_pcmpeqd256 (c8si,v8si) 21657v4di __builtin_ia32_pcmpeqq256 (v4di,v4di) 21658v32qi __builtin_ia32_pcmpgtb256 (v32qi,v32qi) 21659v16hi __builtin_ia32_pcmpgtw256 (16hi,v16hi) 21660v8si __builtin_ia32_pcmpgtd256 (v8si,v8si) 21661v4di __builtin_ia32_pcmpgtq256 (v4di,v4di) 21662v16hi __builtin_ia32_phaddw256 (v16hi,v16hi) 21663v8si __builtin_ia32_phaddd256 (v8si,v8si) 21664v16hi __builtin_ia32_phaddsw256 (v16hi,v16hi) 21665v16hi __builtin_ia32_phsubw256 (v16hi,v16hi) 21666v8si __builtin_ia32_phsubd256 (v8si,v8si) 21667v16hi __builtin_ia32_phsubsw256 (v16hi,v16hi) 21668v32qi __builtin_ia32_pmaddubsw256 (v32qi,v32qi) 21669v16hi __builtin_ia32_pmaddwd256 (v16hi,v16hi) 21670v32qi __builtin_ia32_pmaxsb256 (v32qi,v32qi) 21671v16hi __builtin_ia32_pmaxsw256 (v16hi,v16hi) 21672v8si __builtin_ia32_pmaxsd256 (v8si,v8si) 21673v32qi __builtin_ia32_pmaxub256 (v32qi,v32qi) 21674v16hi __builtin_ia32_pmaxuw256 (v16hi,v16hi) 21675v8si __builtin_ia32_pmaxud256 (v8si,v8si) 21676v32qi __builtin_ia32_pminsb256 (v32qi,v32qi) 21677v16hi __builtin_ia32_pminsw256 (v16hi,v16hi) 21678v8si __builtin_ia32_pminsd256 (v8si,v8si) 21679v32qi __builtin_ia32_pminub256 (v32qi,v32qi) 21680v16hi __builtin_ia32_pminuw256 (v16hi,v16hi) 21681v8si __builtin_ia32_pminud256 (v8si,v8si) 21682int __builtin_ia32_pmovmskb256 (v32qi) 21683v16hi __builtin_ia32_pmovsxbw256 (v16qi) 21684v8si __builtin_ia32_pmovsxbd256 (v16qi) 21685v4di __builtin_ia32_pmovsxbq256 (v16qi) 21686v8si __builtin_ia32_pmovsxwd256 (v8hi) 21687v4di __builtin_ia32_pmovsxwq256 (v8hi) 21688v4di __builtin_ia32_pmovsxdq256 (v4si) 21689v16hi __builtin_ia32_pmovzxbw256 (v16qi) 21690v8si __builtin_ia32_pmovzxbd256 (v16qi) 21691v4di __builtin_ia32_pmovzxbq256 (v16qi) 21692v8si __builtin_ia32_pmovzxwd256 (v8hi) 21693v4di __builtin_ia32_pmovzxwq256 (v8hi) 21694v4di __builtin_ia32_pmovzxdq256 (v4si) 21695v4di __builtin_ia32_pmuldq256 (v8si,v8si) 21696v16hi __builtin_ia32_pmulhrsw256 (v16hi, v16hi) 21697v16hi __builtin_ia32_pmulhuw256 (v16hi,v16hi) 21698v16hi __builtin_ia32_pmulhw256 (v16hi,v16hi) 21699v16hi __builtin_ia32_pmullw256 (v16hi,v16hi) 21700v8si __builtin_ia32_pmulld256 (v8si,v8si) 21701v4di __builtin_ia32_pmuludq256 (v8si,v8si) 21702v4di __builtin_ia32_por256 (v4di,v4di) 21703v16hi __builtin_ia32_psadbw256 (v32qi,v32qi) 21704v32qi __builtin_ia32_pshufb256 (v32qi,v32qi) 21705v8si __builtin_ia32_pshufd256 (v8si,int) 21706v16hi __builtin_ia32_pshufhw256 (v16hi,int) 21707v16hi __builtin_ia32_pshuflw256 (v16hi,int) 21708v32qi __builtin_ia32_psignb256 (v32qi,v32qi) 21709v16hi __builtin_ia32_psignw256 (v16hi,v16hi) 21710v8si __builtin_ia32_psignd256 (v8si,v8si) 21711v4di __builtin_ia32_pslldqi256 (v4di,int) 21712v16hi __builtin_ia32_psllwi256 (16hi,int) 21713v16hi __builtin_ia32_psllw256(v16hi,v8hi) 21714v8si __builtin_ia32_pslldi256 (v8si,int) 21715v8si __builtin_ia32_pslld256(v8si,v4si) 21716v4di __builtin_ia32_psllqi256 (v4di,int) 21717v4di __builtin_ia32_psllq256(v4di,v2di) 21718v16hi __builtin_ia32_psrawi256 (v16hi,int) 21719v16hi __builtin_ia32_psraw256 (v16hi,v8hi) 21720v8si __builtin_ia32_psradi256 (v8si,int) 21721v8si __builtin_ia32_psrad256 (v8si,v4si) 21722v4di __builtin_ia32_psrldqi256 (v4di, int) 21723v16hi __builtin_ia32_psrlwi256 (v16hi,int) 21724v16hi __builtin_ia32_psrlw256 (v16hi,v8hi) 21725v8si __builtin_ia32_psrldi256 (v8si,int) 21726v8si __builtin_ia32_psrld256 (v8si,v4si) 21727v4di __builtin_ia32_psrlqi256 (v4di,int) 21728v4di __builtin_ia32_psrlq256(v4di,v2di) 21729v32qi __builtin_ia32_psubb256 (v32qi,v32qi) 21730v32hi __builtin_ia32_psubw256 (v16hi,v16hi) 21731v8si __builtin_ia32_psubd256 (v8si,v8si) 21732v4di __builtin_ia32_psubq256 (v4di,v4di) 21733v32qi __builtin_ia32_psubsb256 (v32qi,v32qi) 21734v16hi __builtin_ia32_psubsw256 (v16hi,v16hi) 21735v32qi __builtin_ia32_psubusb256 (v32qi,v32qi) 21736v16hi __builtin_ia32_psubusw256 (v16hi,v16hi) 21737v32qi __builtin_ia32_punpckhbw256 (v32qi,v32qi) 21738v16hi __builtin_ia32_punpckhwd256 (v16hi,v16hi) 21739v8si __builtin_ia32_punpckhdq256 (v8si,v8si) 21740v4di __builtin_ia32_punpckhqdq256 (v4di,v4di) 21741v32qi __builtin_ia32_punpcklbw256 (v32qi,v32qi) 21742v16hi __builtin_ia32_punpcklwd256 (v16hi,v16hi) 21743v8si __builtin_ia32_punpckldq256 (v8si,v8si) 21744v4di __builtin_ia32_punpcklqdq256 (v4di,v4di) 21745v4di __builtin_ia32_pxor256 (v4di,v4di) 21746v4di __builtin_ia32_movntdqa256 (pv4di) 21747v4sf __builtin_ia32_vbroadcastss_ps (v4sf) 21748v8sf __builtin_ia32_vbroadcastss_ps256 (v4sf) 21749v4df __builtin_ia32_vbroadcastsd_pd256 (v2df) 21750v4di __builtin_ia32_vbroadcastsi256 (v2di) 21751v4si __builtin_ia32_pblendd128 (v4si,v4si) 21752v8si __builtin_ia32_pblendd256 (v8si,v8si) 21753v32qi __builtin_ia32_pbroadcastb256 (v16qi) 21754v16hi __builtin_ia32_pbroadcastw256 (v8hi) 21755v8si __builtin_ia32_pbroadcastd256 (v4si) 21756v4di __builtin_ia32_pbroadcastq256 (v2di) 21757v16qi __builtin_ia32_pbroadcastb128 (v16qi) 21758v8hi __builtin_ia32_pbroadcastw128 (v8hi) 21759v4si __builtin_ia32_pbroadcastd128 (v4si) 21760v2di __builtin_ia32_pbroadcastq128 (v2di) 21761v8si __builtin_ia32_permvarsi256 (v8si,v8si) 21762v4df __builtin_ia32_permdf256 (v4df,int) 21763v8sf __builtin_ia32_permvarsf256 (v8sf,v8sf) 21764v4di __builtin_ia32_permdi256 (v4di,int) 21765v4di __builtin_ia32_permti256 (v4di,v4di,int) 21766v4di __builtin_ia32_extract128i256 (v4di,int) 21767v4di __builtin_ia32_insert128i256 (v4di,v2di,int) 21768v8si __builtin_ia32_maskloadd256 (pcv8si,v8si) 21769v4di __builtin_ia32_maskloadq256 (pcv4di,v4di) 21770v4si __builtin_ia32_maskloadd (pcv4si,v4si) 21771v2di __builtin_ia32_maskloadq (pcv2di,v2di) 21772void __builtin_ia32_maskstored256 (pv8si,v8si,v8si) 21773void __builtin_ia32_maskstoreq256 (pv4di,v4di,v4di) 21774void __builtin_ia32_maskstored (pv4si,v4si,v4si) 21775void __builtin_ia32_maskstoreq (pv2di,v2di,v2di) 21776v8si __builtin_ia32_psllv8si (v8si,v8si) 21777v4si __builtin_ia32_psllv4si (v4si,v4si) 21778v4di __builtin_ia32_psllv4di (v4di,v4di) 21779v2di __builtin_ia32_psllv2di (v2di,v2di) 21780v8si __builtin_ia32_psrav8si (v8si,v8si) 21781v4si __builtin_ia32_psrav4si (v4si,v4si) 21782v8si __builtin_ia32_psrlv8si (v8si,v8si) 21783v4si __builtin_ia32_psrlv4si (v4si,v4si) 21784v4di __builtin_ia32_psrlv4di (v4di,v4di) 21785v2di __builtin_ia32_psrlv2di (v2di,v2di) 21786v2df __builtin_ia32_gathersiv2df (v2df, pcdouble,v4si,v2df,int) 21787v4df __builtin_ia32_gathersiv4df (v4df, pcdouble,v4si,v4df,int) 21788v2df __builtin_ia32_gatherdiv2df (v2df, pcdouble,v2di,v2df,int) 21789v4df __builtin_ia32_gatherdiv4df (v4df, pcdouble,v4di,v4df,int) 21790v4sf __builtin_ia32_gathersiv4sf (v4sf, pcfloat,v4si,v4sf,int) 21791v8sf __builtin_ia32_gathersiv8sf (v8sf, pcfloat,v8si,v8sf,int) 21792v4sf __builtin_ia32_gatherdiv4sf (v4sf, pcfloat,v2di,v4sf,int) 21793v4sf __builtin_ia32_gatherdiv4sf256 (v4sf, pcfloat,v4di,v4sf,int) 21794v2di __builtin_ia32_gathersiv2di (v2di, pcint64,v4si,v2di,int) 21795v4di __builtin_ia32_gathersiv4di (v4di, pcint64,v4si,v4di,int) 21796v2di __builtin_ia32_gatherdiv2di (v2di, pcint64,v2di,v2di,int) 21797v4di __builtin_ia32_gatherdiv4di (v4di, pcint64,v4di,v4di,int) 21798v4si __builtin_ia32_gathersiv4si (v4si, pcint,v4si,v4si,int) 21799v8si __builtin_ia32_gathersiv8si (v8si, pcint,v8si,v8si,int) 21800v4si __builtin_ia32_gatherdiv4si (v4si, pcint,v2di,v4si,int) 21801v4si __builtin_ia32_gatherdiv4si256 (v4si, pcint,v4di,v4si,int) 21802@end smallexample 21803 21804The following built-in functions are available when @option{-maes} is 21805used. All of them generate the machine instruction that is part of the 21806name. 21807 21808@smallexample 21809v2di __builtin_ia32_aesenc128 (v2di, v2di) 21810v2di __builtin_ia32_aesenclast128 (v2di, v2di) 21811v2di __builtin_ia32_aesdec128 (v2di, v2di) 21812v2di __builtin_ia32_aesdeclast128 (v2di, v2di) 21813v2di __builtin_ia32_aeskeygenassist128 (v2di, const int) 21814v2di __builtin_ia32_aesimc128 (v2di) 21815@end smallexample 21816 21817The following built-in function is available when @option{-mpclmul} is 21818used. 21819 21820@table @code 21821@item v2di __builtin_ia32_pclmulqdq128 (v2di, v2di, const int) 21822Generates the @code{pclmulqdq} machine instruction. 21823@end table 21824 21825The following built-in function is available when @option{-mfsgsbase} is 21826used. All of them generate the machine instruction that is part of the 21827name. 21828 21829@smallexample 21830unsigned int __builtin_ia32_rdfsbase32 (void) 21831unsigned long long __builtin_ia32_rdfsbase64 (void) 21832unsigned int __builtin_ia32_rdgsbase32 (void) 21833unsigned long long __builtin_ia32_rdgsbase64 (void) 21834void _writefsbase_u32 (unsigned int) 21835void _writefsbase_u64 (unsigned long long) 21836void _writegsbase_u32 (unsigned int) 21837void _writegsbase_u64 (unsigned long long) 21838@end smallexample 21839 21840The following built-in function is available when @option{-mrdrnd} is 21841used. All of them generate the machine instruction that is part of the 21842name. 21843 21844@smallexample 21845unsigned int __builtin_ia32_rdrand16_step (unsigned short *) 21846unsigned int __builtin_ia32_rdrand32_step (unsigned int *) 21847unsigned int __builtin_ia32_rdrand64_step (unsigned long long *) 21848@end smallexample 21849 21850The following built-in functions are available when @option{-msse4a} is used. 21851All of them generate the machine instruction that is part of the name. 21852 21853@smallexample 21854void __builtin_ia32_movntsd (double *, v2df) 21855void __builtin_ia32_movntss (float *, v4sf) 21856v2di __builtin_ia32_extrq (v2di, v16qi) 21857v2di __builtin_ia32_extrqi (v2di, const unsigned int, const unsigned int) 21858v2di __builtin_ia32_insertq (v2di, v2di) 21859v2di __builtin_ia32_insertqi (v2di, v2di, const unsigned int, const unsigned int) 21860@end smallexample 21861 21862The following built-in functions are available when @option{-mxop} is used. 21863@smallexample 21864v2df __builtin_ia32_vfrczpd (v2df) 21865v4sf __builtin_ia32_vfrczps (v4sf) 21866v2df __builtin_ia32_vfrczsd (v2df) 21867v4sf __builtin_ia32_vfrczss (v4sf) 21868v4df __builtin_ia32_vfrczpd256 (v4df) 21869v8sf __builtin_ia32_vfrczps256 (v8sf) 21870v2di __builtin_ia32_vpcmov (v2di, v2di, v2di) 21871v2di __builtin_ia32_vpcmov_v2di (v2di, v2di, v2di) 21872v4si __builtin_ia32_vpcmov_v4si (v4si, v4si, v4si) 21873v8hi __builtin_ia32_vpcmov_v8hi (v8hi, v8hi, v8hi) 21874v16qi __builtin_ia32_vpcmov_v16qi (v16qi, v16qi, v16qi) 21875v2df __builtin_ia32_vpcmov_v2df (v2df, v2df, v2df) 21876v4sf __builtin_ia32_vpcmov_v4sf (v4sf, v4sf, v4sf) 21877v4di __builtin_ia32_vpcmov_v4di256 (v4di, v4di, v4di) 21878v8si __builtin_ia32_vpcmov_v8si256 (v8si, v8si, v8si) 21879v16hi __builtin_ia32_vpcmov_v16hi256 (v16hi, v16hi, v16hi) 21880v32qi __builtin_ia32_vpcmov_v32qi256 (v32qi, v32qi, v32qi) 21881v4df __builtin_ia32_vpcmov_v4df256 (v4df, v4df, v4df) 21882v8sf __builtin_ia32_vpcmov_v8sf256 (v8sf, v8sf, v8sf) 21883v16qi __builtin_ia32_vpcomeqb (v16qi, v16qi) 21884v8hi __builtin_ia32_vpcomeqw (v8hi, v8hi) 21885v4si __builtin_ia32_vpcomeqd (v4si, v4si) 21886v2di __builtin_ia32_vpcomeqq (v2di, v2di) 21887v16qi __builtin_ia32_vpcomequb (v16qi, v16qi) 21888v4si __builtin_ia32_vpcomequd (v4si, v4si) 21889v2di __builtin_ia32_vpcomequq (v2di, v2di) 21890v8hi __builtin_ia32_vpcomequw (v8hi, v8hi) 21891v8hi __builtin_ia32_vpcomeqw (v8hi, v8hi) 21892v16qi __builtin_ia32_vpcomfalseb (v16qi, v16qi) 21893v4si __builtin_ia32_vpcomfalsed (v4si, v4si) 21894v2di __builtin_ia32_vpcomfalseq (v2di, v2di) 21895v16qi __builtin_ia32_vpcomfalseub (v16qi, v16qi) 21896v4si __builtin_ia32_vpcomfalseud (v4si, v4si) 21897v2di __builtin_ia32_vpcomfalseuq (v2di, v2di) 21898v8hi __builtin_ia32_vpcomfalseuw (v8hi, v8hi) 21899v8hi __builtin_ia32_vpcomfalsew (v8hi, v8hi) 21900v16qi __builtin_ia32_vpcomgeb (v16qi, v16qi) 21901v4si __builtin_ia32_vpcomged (v4si, v4si) 21902v2di __builtin_ia32_vpcomgeq (v2di, v2di) 21903v16qi __builtin_ia32_vpcomgeub (v16qi, v16qi) 21904v4si __builtin_ia32_vpcomgeud (v4si, v4si) 21905v2di __builtin_ia32_vpcomgeuq (v2di, v2di) 21906v8hi __builtin_ia32_vpcomgeuw (v8hi, v8hi) 21907v8hi __builtin_ia32_vpcomgew (v8hi, v8hi) 21908v16qi __builtin_ia32_vpcomgtb (v16qi, v16qi) 21909v4si __builtin_ia32_vpcomgtd (v4si, v4si) 21910v2di __builtin_ia32_vpcomgtq (v2di, v2di) 21911v16qi __builtin_ia32_vpcomgtub (v16qi, v16qi) 21912v4si __builtin_ia32_vpcomgtud (v4si, v4si) 21913v2di __builtin_ia32_vpcomgtuq (v2di, v2di) 21914v8hi __builtin_ia32_vpcomgtuw (v8hi, v8hi) 21915v8hi __builtin_ia32_vpcomgtw (v8hi, v8hi) 21916v16qi __builtin_ia32_vpcomleb (v16qi, v16qi) 21917v4si __builtin_ia32_vpcomled (v4si, v4si) 21918v2di __builtin_ia32_vpcomleq (v2di, v2di) 21919v16qi __builtin_ia32_vpcomleub (v16qi, v16qi) 21920v4si __builtin_ia32_vpcomleud (v4si, v4si) 21921v2di __builtin_ia32_vpcomleuq (v2di, v2di) 21922v8hi __builtin_ia32_vpcomleuw (v8hi, v8hi) 21923v8hi __builtin_ia32_vpcomlew (v8hi, v8hi) 21924v16qi __builtin_ia32_vpcomltb (v16qi, v16qi) 21925v4si __builtin_ia32_vpcomltd (v4si, v4si) 21926v2di __builtin_ia32_vpcomltq (v2di, v2di) 21927v16qi __builtin_ia32_vpcomltub (v16qi, v16qi) 21928v4si __builtin_ia32_vpcomltud (v4si, v4si) 21929v2di __builtin_ia32_vpcomltuq (v2di, v2di) 21930v8hi __builtin_ia32_vpcomltuw (v8hi, v8hi) 21931v8hi __builtin_ia32_vpcomltw (v8hi, v8hi) 21932v16qi __builtin_ia32_vpcomneb (v16qi, v16qi) 21933v4si __builtin_ia32_vpcomned (v4si, v4si) 21934v2di __builtin_ia32_vpcomneq (v2di, v2di) 21935v16qi __builtin_ia32_vpcomneub (v16qi, v16qi) 21936v4si __builtin_ia32_vpcomneud (v4si, v4si) 21937v2di __builtin_ia32_vpcomneuq (v2di, v2di) 21938v8hi __builtin_ia32_vpcomneuw (v8hi, v8hi) 21939v8hi __builtin_ia32_vpcomnew (v8hi, v8hi) 21940v16qi __builtin_ia32_vpcomtrueb (v16qi, v16qi) 21941v4si __builtin_ia32_vpcomtrued (v4si, v4si) 21942v2di __builtin_ia32_vpcomtrueq (v2di, v2di) 21943v16qi __builtin_ia32_vpcomtrueub (v16qi, v16qi) 21944v4si __builtin_ia32_vpcomtrueud (v4si, v4si) 21945v2di __builtin_ia32_vpcomtrueuq (v2di, v2di) 21946v8hi __builtin_ia32_vpcomtrueuw (v8hi, v8hi) 21947v8hi __builtin_ia32_vpcomtruew (v8hi, v8hi) 21948v4si __builtin_ia32_vphaddbd (v16qi) 21949v2di __builtin_ia32_vphaddbq (v16qi) 21950v8hi __builtin_ia32_vphaddbw (v16qi) 21951v2di __builtin_ia32_vphadddq (v4si) 21952v4si __builtin_ia32_vphaddubd (v16qi) 21953v2di __builtin_ia32_vphaddubq (v16qi) 21954v8hi __builtin_ia32_vphaddubw (v16qi) 21955v2di __builtin_ia32_vphaddudq (v4si) 21956v4si __builtin_ia32_vphadduwd (v8hi) 21957v2di __builtin_ia32_vphadduwq (v8hi) 21958v4si __builtin_ia32_vphaddwd (v8hi) 21959v2di __builtin_ia32_vphaddwq (v8hi) 21960v8hi __builtin_ia32_vphsubbw (v16qi) 21961v2di __builtin_ia32_vphsubdq (v4si) 21962v4si __builtin_ia32_vphsubwd (v8hi) 21963v4si __builtin_ia32_vpmacsdd (v4si, v4si, v4si) 21964v2di __builtin_ia32_vpmacsdqh (v4si, v4si, v2di) 21965v2di __builtin_ia32_vpmacsdql (v4si, v4si, v2di) 21966v4si __builtin_ia32_vpmacssdd (v4si, v4si, v4si) 21967v2di __builtin_ia32_vpmacssdqh (v4si, v4si, v2di) 21968v2di __builtin_ia32_vpmacssdql (v4si, v4si, v2di) 21969v4si __builtin_ia32_vpmacsswd (v8hi, v8hi, v4si) 21970v8hi __builtin_ia32_vpmacssww (v8hi, v8hi, v8hi) 21971v4si __builtin_ia32_vpmacswd (v8hi, v8hi, v4si) 21972v8hi __builtin_ia32_vpmacsww (v8hi, v8hi, v8hi) 21973v4si __builtin_ia32_vpmadcsswd (v8hi, v8hi, v4si) 21974v4si __builtin_ia32_vpmadcswd (v8hi, v8hi, v4si) 21975v16qi __builtin_ia32_vpperm (v16qi, v16qi, v16qi) 21976v16qi __builtin_ia32_vprotb (v16qi, v16qi) 21977v4si __builtin_ia32_vprotd (v4si, v4si) 21978v2di __builtin_ia32_vprotq (v2di, v2di) 21979v8hi __builtin_ia32_vprotw (v8hi, v8hi) 21980v16qi __builtin_ia32_vpshab (v16qi, v16qi) 21981v4si __builtin_ia32_vpshad (v4si, v4si) 21982v2di __builtin_ia32_vpshaq (v2di, v2di) 21983v8hi __builtin_ia32_vpshaw (v8hi, v8hi) 21984v16qi __builtin_ia32_vpshlb (v16qi, v16qi) 21985v4si __builtin_ia32_vpshld (v4si, v4si) 21986v2di __builtin_ia32_vpshlq (v2di, v2di) 21987v8hi __builtin_ia32_vpshlw (v8hi, v8hi) 21988@end smallexample 21989 21990The following built-in functions are available when @option{-mfma4} is used. 21991All of them generate the machine instruction that is part of the name. 21992 21993@smallexample 21994v2df __builtin_ia32_vfmaddpd (v2df, v2df, v2df) 21995v4sf __builtin_ia32_vfmaddps (v4sf, v4sf, v4sf) 21996v2df __builtin_ia32_vfmaddsd (v2df, v2df, v2df) 21997v4sf __builtin_ia32_vfmaddss (v4sf, v4sf, v4sf) 21998v2df __builtin_ia32_vfmsubpd (v2df, v2df, v2df) 21999v4sf __builtin_ia32_vfmsubps (v4sf, v4sf, v4sf) 22000v2df __builtin_ia32_vfmsubsd (v2df, v2df, v2df) 22001v4sf __builtin_ia32_vfmsubss (v4sf, v4sf, v4sf) 22002v2df __builtin_ia32_vfnmaddpd (v2df, v2df, v2df) 22003v4sf __builtin_ia32_vfnmaddps (v4sf, v4sf, v4sf) 22004v2df __builtin_ia32_vfnmaddsd (v2df, v2df, v2df) 22005v4sf __builtin_ia32_vfnmaddss (v4sf, v4sf, v4sf) 22006v2df __builtin_ia32_vfnmsubpd (v2df, v2df, v2df) 22007v4sf __builtin_ia32_vfnmsubps (v4sf, v4sf, v4sf) 22008v2df __builtin_ia32_vfnmsubsd (v2df, v2df, v2df) 22009v4sf __builtin_ia32_vfnmsubss (v4sf, v4sf, v4sf) 22010v2df __builtin_ia32_vfmaddsubpd (v2df, v2df, v2df) 22011v4sf __builtin_ia32_vfmaddsubps (v4sf, v4sf, v4sf) 22012v2df __builtin_ia32_vfmsubaddpd (v2df, v2df, v2df) 22013v4sf __builtin_ia32_vfmsubaddps (v4sf, v4sf, v4sf) 22014v4df __builtin_ia32_vfmaddpd256 (v4df, v4df, v4df) 22015v8sf __builtin_ia32_vfmaddps256 (v8sf, v8sf, v8sf) 22016v4df __builtin_ia32_vfmsubpd256 (v4df, v4df, v4df) 22017v8sf __builtin_ia32_vfmsubps256 (v8sf, v8sf, v8sf) 22018v4df __builtin_ia32_vfnmaddpd256 (v4df, v4df, v4df) 22019v8sf __builtin_ia32_vfnmaddps256 (v8sf, v8sf, v8sf) 22020v4df __builtin_ia32_vfnmsubpd256 (v4df, v4df, v4df) 22021v8sf __builtin_ia32_vfnmsubps256 (v8sf, v8sf, v8sf) 22022v4df __builtin_ia32_vfmaddsubpd256 (v4df, v4df, v4df) 22023v8sf __builtin_ia32_vfmaddsubps256 (v8sf, v8sf, v8sf) 22024v4df __builtin_ia32_vfmsubaddpd256 (v4df, v4df, v4df) 22025v8sf __builtin_ia32_vfmsubaddps256 (v8sf, v8sf, v8sf) 22026 22027@end smallexample 22028 22029The following built-in functions are available when @option{-mlwp} is used. 22030 22031@smallexample 22032void __builtin_ia32_llwpcb16 (void *); 22033void __builtin_ia32_llwpcb32 (void *); 22034void __builtin_ia32_llwpcb64 (void *); 22035void * __builtin_ia32_llwpcb16 (void); 22036void * __builtin_ia32_llwpcb32 (void); 22037void * __builtin_ia32_llwpcb64 (void); 22038void __builtin_ia32_lwpval16 (unsigned short, unsigned int, unsigned short) 22039void __builtin_ia32_lwpval32 (unsigned int, unsigned int, unsigned int) 22040void __builtin_ia32_lwpval64 (unsigned __int64, unsigned int, unsigned int) 22041unsigned char __builtin_ia32_lwpins16 (unsigned short, unsigned int, unsigned short) 22042unsigned char __builtin_ia32_lwpins32 (unsigned int, unsigned int, unsigned int) 22043unsigned char __builtin_ia32_lwpins64 (unsigned __int64, unsigned int, unsigned int) 22044@end smallexample 22045 22046The following built-in functions are available when @option{-mbmi} is used. 22047All of them generate the machine instruction that is part of the name. 22048@smallexample 22049unsigned int __builtin_ia32_bextr_u32(unsigned int, unsigned int); 22050unsigned long long __builtin_ia32_bextr_u64 (unsigned long long, unsigned long long); 22051@end smallexample 22052 22053The following built-in functions are available when @option{-mbmi2} is used. 22054All of them generate the machine instruction that is part of the name. 22055@smallexample 22056unsigned int _bzhi_u32 (unsigned int, unsigned int) 22057unsigned int _pdep_u32 (unsigned int, unsigned int) 22058unsigned int _pext_u32 (unsigned int, unsigned int) 22059unsigned long long _bzhi_u64 (unsigned long long, unsigned long long) 22060unsigned long long _pdep_u64 (unsigned long long, unsigned long long) 22061unsigned long long _pext_u64 (unsigned long long, unsigned long long) 22062@end smallexample 22063 22064The following built-in functions are available when @option{-mlzcnt} is used. 22065All of them generate the machine instruction that is part of the name. 22066@smallexample 22067unsigned short __builtin_ia32_lzcnt_u16(unsigned short); 22068unsigned int __builtin_ia32_lzcnt_u32(unsigned int); 22069unsigned long long __builtin_ia32_lzcnt_u64 (unsigned long long); 22070@end smallexample 22071 22072The following built-in functions are available when @option{-mfxsr} is used. 22073All of them generate the machine instruction that is part of the name. 22074@smallexample 22075void __builtin_ia32_fxsave (void *) 22076void __builtin_ia32_fxrstor (void *) 22077void __builtin_ia32_fxsave64 (void *) 22078void __builtin_ia32_fxrstor64 (void *) 22079@end smallexample 22080 22081The following built-in functions are available when @option{-mxsave} is used. 22082All of them generate the machine instruction that is part of the name. 22083@smallexample 22084void __builtin_ia32_xsave (void *, long long) 22085void __builtin_ia32_xrstor (void *, long long) 22086void __builtin_ia32_xsave64 (void *, long long) 22087void __builtin_ia32_xrstor64 (void *, long long) 22088@end smallexample 22089 22090The following built-in functions are available when @option{-mxsaveopt} is used. 22091All of them generate the machine instruction that is part of the name. 22092@smallexample 22093void __builtin_ia32_xsaveopt (void *, long long) 22094void __builtin_ia32_xsaveopt64 (void *, long long) 22095@end smallexample 22096 22097The following built-in functions are available when @option{-mtbm} is used. 22098Both of them generate the immediate form of the bextr machine instruction. 22099@smallexample 22100unsigned int __builtin_ia32_bextri_u32 (unsigned int, 22101 const unsigned int); 22102unsigned long long __builtin_ia32_bextri_u64 (unsigned long long, 22103 const unsigned long long); 22104@end smallexample 22105 22106 22107The following built-in functions are available when @option{-m3dnow} is used. 22108All of them generate the machine instruction that is part of the name. 22109 22110@smallexample 22111void __builtin_ia32_femms (void) 22112v8qi __builtin_ia32_pavgusb (v8qi, v8qi) 22113v2si __builtin_ia32_pf2id (v2sf) 22114v2sf __builtin_ia32_pfacc (v2sf, v2sf) 22115v2sf __builtin_ia32_pfadd (v2sf, v2sf) 22116v2si __builtin_ia32_pfcmpeq (v2sf, v2sf) 22117v2si __builtin_ia32_pfcmpge (v2sf, v2sf) 22118v2si __builtin_ia32_pfcmpgt (v2sf, v2sf) 22119v2sf __builtin_ia32_pfmax (v2sf, v2sf) 22120v2sf __builtin_ia32_pfmin (v2sf, v2sf) 22121v2sf __builtin_ia32_pfmul (v2sf, v2sf) 22122v2sf __builtin_ia32_pfrcp (v2sf) 22123v2sf __builtin_ia32_pfrcpit1 (v2sf, v2sf) 22124v2sf __builtin_ia32_pfrcpit2 (v2sf, v2sf) 22125v2sf __builtin_ia32_pfrsqrt (v2sf) 22126v2sf __builtin_ia32_pfsub (v2sf, v2sf) 22127v2sf __builtin_ia32_pfsubr (v2sf, v2sf) 22128v2sf __builtin_ia32_pi2fd (v2si) 22129v4hi __builtin_ia32_pmulhrw (v4hi, v4hi) 22130@end smallexample 22131 22132The following built-in functions are available when @option{-m3dnowa} is used. 22133All of them generate the machine instruction that is part of the name. 22134 22135@smallexample 22136v2si __builtin_ia32_pf2iw (v2sf) 22137v2sf __builtin_ia32_pfnacc (v2sf, v2sf) 22138v2sf __builtin_ia32_pfpnacc (v2sf, v2sf) 22139v2sf __builtin_ia32_pi2fw (v2si) 22140v2sf __builtin_ia32_pswapdsf (v2sf) 22141v2si __builtin_ia32_pswapdsi (v2si) 22142@end smallexample 22143 22144The following built-in functions are available when @option{-mrtm} is used 22145They are used for restricted transactional memory. These are the internal 22146low level functions. Normally the functions in 22147@ref{x86 transactional memory intrinsics} should be used instead. 22148 22149@smallexample 22150int __builtin_ia32_xbegin () 22151void __builtin_ia32_xend () 22152void __builtin_ia32_xabort (status) 22153int __builtin_ia32_xtest () 22154@end smallexample 22155 22156The following built-in functions are available when @option{-mmwaitx} is used. 22157All of them generate the machine instruction that is part of the name. 22158@smallexample 22159void __builtin_ia32_monitorx (void *, unsigned int, unsigned int) 22160void __builtin_ia32_mwaitx (unsigned int, unsigned int, unsigned int) 22161@end smallexample 22162 22163The following built-in functions are available when @option{-mclzero} is used. 22164All of them generate the machine instruction that is part of the name. 22165@smallexample 22166void __builtin_i32_clzero (void *) 22167@end smallexample 22168 22169The following built-in functions are available when @option{-mpku} is used. 22170They generate reads and writes to PKRU. 22171@smallexample 22172void __builtin_ia32_wrpkru (unsigned int) 22173unsigned int __builtin_ia32_rdpkru () 22174@end smallexample 22175 22176The following built-in functions are available when @option{-mcet} or 22177@option{-mshstk} option is used. They support shadow stack 22178machine instructions from Intel Control-flow Enforcement Technology (CET). 22179Each built-in function generates the machine instruction that is part 22180of the function's name. These are the internal low-level functions. 22181Normally the functions in @ref{x86 control-flow protection intrinsics} 22182should be used instead. 22183 22184@smallexample 22185unsigned int __builtin_ia32_rdsspd (void) 22186unsigned long long __builtin_ia32_rdsspq (void) 22187void __builtin_ia32_incsspd (unsigned int) 22188void __builtin_ia32_incsspq (unsigned long long) 22189void __builtin_ia32_saveprevssp(void); 22190void __builtin_ia32_rstorssp(void *); 22191void __builtin_ia32_wrssd(unsigned int, void *); 22192void __builtin_ia32_wrssq(unsigned long long, void *); 22193void __builtin_ia32_wrussd(unsigned int, void *); 22194void __builtin_ia32_wrussq(unsigned long long, void *); 22195void __builtin_ia32_setssbsy(void); 22196void __builtin_ia32_clrssbsy(void *); 22197@end smallexample 22198 22199@node x86 transactional memory intrinsics 22200@subsection x86 Transactional Memory Intrinsics 22201 22202These hardware transactional memory intrinsics for x86 allow you to use 22203memory transactions with RTM (Restricted Transactional Memory). 22204This support is enabled with the @option{-mrtm} option. 22205For using HLE (Hardware Lock Elision) see 22206@ref{x86 specific memory model extensions for transactional memory} instead. 22207 22208A memory transaction commits all changes to memory in an atomic way, 22209as visible to other threads. If the transaction fails it is rolled back 22210and all side effects discarded. 22211 22212Generally there is no guarantee that a memory transaction ever succeeds 22213and suitable fallback code always needs to be supplied. 22214 22215@deftypefn {RTM Function} {unsigned} _xbegin () 22216Start a RTM (Restricted Transactional Memory) transaction. 22217Returns @code{_XBEGIN_STARTED} when the transaction 22218started successfully (note this is not 0, so the constant has to be 22219explicitly tested). 22220 22221If the transaction aborts, all side effects 22222are undone and an abort code encoded as a bit mask is returned. 22223The following macros are defined: 22224 22225@table @code 22226@item _XABORT_EXPLICIT 22227Transaction was explicitly aborted with @code{_xabort}. The parameter passed 22228to @code{_xabort} is available with @code{_XABORT_CODE(status)}. 22229@item _XABORT_RETRY 22230Transaction retry is possible. 22231@item _XABORT_CONFLICT 22232Transaction abort due to a memory conflict with another thread. 22233@item _XABORT_CAPACITY 22234Transaction abort due to the transaction using too much memory. 22235@item _XABORT_DEBUG 22236Transaction abort due to a debug trap. 22237@item _XABORT_NESTED 22238Transaction abort in an inner nested transaction. 22239@end table 22240 22241There is no guarantee 22242any transaction ever succeeds, so there always needs to be a valid 22243fallback path. 22244@end deftypefn 22245 22246@deftypefn {RTM Function} {void} _xend () 22247Commit the current transaction. When no transaction is active this faults. 22248All memory side effects of the transaction become visible 22249to other threads in an atomic manner. 22250@end deftypefn 22251 22252@deftypefn {RTM Function} {int} _xtest () 22253Return a nonzero value if a transaction is currently active, otherwise 0. 22254@end deftypefn 22255 22256@deftypefn {RTM Function} {void} _xabort (status) 22257Abort the current transaction. When no transaction is active this is a no-op. 22258The @var{status} is an 8-bit constant; its value is encoded in the return 22259value from @code{_xbegin}. 22260@end deftypefn 22261 22262Here is an example showing handling for @code{_XABORT_RETRY} 22263and a fallback path for other failures: 22264 22265@smallexample 22266#include <immintrin.h> 22267 22268int n_tries, max_tries; 22269unsigned status = _XABORT_EXPLICIT; 22270... 22271 22272for (n_tries = 0; n_tries < max_tries; n_tries++) 22273 @{ 22274 status = _xbegin (); 22275 if (status == _XBEGIN_STARTED || !(status & _XABORT_RETRY)) 22276 break; 22277 @} 22278if (status == _XBEGIN_STARTED) 22279 @{ 22280 ... transaction code... 22281 _xend (); 22282 @} 22283else 22284 @{ 22285 ... non-transactional fallback path... 22286 @} 22287@end smallexample 22288 22289@noindent 22290Note that, in most cases, the transactional and non-transactional code 22291must synchronize together to ensure consistency. 22292 22293@node x86 control-flow protection intrinsics 22294@subsection x86 Control-Flow Protection Intrinsics 22295 22296@deftypefn {CET Function} {ret_type} _get_ssp (void) 22297Get the current value of shadow stack pointer if shadow stack support 22298from Intel CET is enabled in the hardware or @code{0} otherwise. 22299The @code{ret_type} is @code{unsigned long long} for 64-bit targets 22300and @code{unsigned int} for 32-bit targets. 22301@end deftypefn 22302 22303@deftypefn {CET Function} void _inc_ssp (unsigned int) 22304Increment the current shadow stack pointer by the size specified by the 22305function argument. The argument is masked to a byte value for security 22306reasons, so to increment by more than 255 bytes you must call the function 22307multiple times. 22308@end deftypefn 22309 22310The shadow stack unwind code looks like: 22311 22312@smallexample 22313#include <immintrin.h> 22314 22315/* Unwind the shadow stack for EH. */ 22316#define _Unwind_Frames_Extra(x) \ 22317 do \ 22318 @{ \ 22319 _Unwind_Word ssp = _get_ssp (); \ 22320 if (ssp != 0) \ 22321 @{ \ 22322 _Unwind_Word tmp = (x); \ 22323 while (tmp > 255) \ 22324 @{ \ 22325 _inc_ssp (tmp); \ 22326 tmp -= 255; \ 22327 @} \ 22328 _inc_ssp (tmp); \ 22329 @} \ 22330 @} \ 22331 while (0) 22332@end smallexample 22333 22334@noindent 22335This code runs unconditionally on all 64-bit processors. For 32-bit 22336processors the code runs on those that support multi-byte NOP instructions. 22337 22338@node Target Format Checks 22339@section Format Checks Specific to Particular Target Machines 22340 22341For some target machines, GCC supports additional options to the 22342format attribute 22343(@pxref{Function Attributes,,Declaring Attributes of Functions}). 22344 22345@menu 22346* Solaris Format Checks:: 22347* Darwin Format Checks:: 22348@end menu 22349 22350@node Solaris Format Checks 22351@subsection Solaris Format Checks 22352 22353Solaris targets support the @code{cmn_err} (or @code{__cmn_err__}) format 22354check. @code{cmn_err} accepts a subset of the standard @code{printf} 22355conversions, and the two-argument @code{%b} conversion for displaying 22356bit-fields. See the Solaris man page for @code{cmn_err} for more information. 22357 22358@node Darwin Format Checks 22359@subsection Darwin Format Checks 22360 22361Darwin targets support the @code{CFString} (or @code{__CFString__}) in the format 22362attribute context. Declarations made with such attribution are parsed for correct syntax 22363and format argument types. However, parsing of the format string itself is currently undefined 22364and is not carried out by this version of the compiler. 22365 22366Additionally, @code{CFStringRefs} (defined by the @code{CoreFoundation} headers) may 22367also be used as format arguments. Note that the relevant headers are only likely to be 22368available on Darwin (OSX) installations. On such installations, the XCode and system 22369documentation provide descriptions of @code{CFString}, @code{CFStringRefs} and 22370associated functions. 22371 22372@node Pragmas 22373@section Pragmas Accepted by GCC 22374@cindex pragmas 22375@cindex @code{#pragma} 22376 22377GCC supports several types of pragmas, primarily in order to compile 22378code originally written for other compilers. Note that in general 22379we do not recommend the use of pragmas; @xref{Function Attributes}, 22380for further explanation. 22381 22382@menu 22383* AArch64 Pragmas:: 22384* ARM Pragmas:: 22385* M32C Pragmas:: 22386* MeP Pragmas:: 22387* RS/6000 and PowerPC Pragmas:: 22388* S/390 Pragmas:: 22389* Darwin Pragmas:: 22390* Solaris Pragmas:: 22391* Symbol-Renaming Pragmas:: 22392* Structure-Layout Pragmas:: 22393* Weak Pragmas:: 22394* Diagnostic Pragmas:: 22395* Visibility Pragmas:: 22396* Push/Pop Macro Pragmas:: 22397* Function Specific Option Pragmas:: 22398* Loop-Specific Pragmas:: 22399@end menu 22400 22401@node AArch64 Pragmas 22402@subsection AArch64 Pragmas 22403 22404The pragmas defined by the AArch64 target correspond to the AArch64 22405target function attributes. They can be specified as below: 22406@smallexample 22407#pragma GCC target("string") 22408@end smallexample 22409 22410where @code{@var{string}} can be any string accepted as an AArch64 target 22411attribute. @xref{AArch64 Function Attributes}, for more details 22412on the permissible values of @code{string}. 22413 22414@node ARM Pragmas 22415@subsection ARM Pragmas 22416 22417The ARM target defines pragmas for controlling the default addition of 22418@code{long_call} and @code{short_call} attributes to functions. 22419@xref{Function Attributes}, for information about the effects of these 22420attributes. 22421 22422@table @code 22423@item long_calls 22424@cindex pragma, long_calls 22425Set all subsequent functions to have the @code{long_call} attribute. 22426 22427@item no_long_calls 22428@cindex pragma, no_long_calls 22429Set all subsequent functions to have the @code{short_call} attribute. 22430 22431@item long_calls_off 22432@cindex pragma, long_calls_off 22433Do not affect the @code{long_call} or @code{short_call} attributes of 22434subsequent functions. 22435@end table 22436 22437@node M32C Pragmas 22438@subsection M32C Pragmas 22439 22440@table @code 22441@item GCC memregs @var{number} 22442@cindex pragma, memregs 22443Overrides the command-line option @code{-memregs=} for the current 22444file. Use with care! This pragma must be before any function in the 22445file, and mixing different memregs values in different objects may 22446make them incompatible. This pragma is useful when a 22447performance-critical function uses a memreg for temporary values, 22448as it may allow you to reduce the number of memregs used. 22449 22450@item ADDRESS @var{name} @var{address} 22451@cindex pragma, address 22452For any declared symbols matching @var{name}, this does three things 22453to that symbol: it forces the symbol to be located at the given 22454address (a number), it forces the symbol to be volatile, and it 22455changes the symbol's scope to be static. This pragma exists for 22456compatibility with other compilers, but note that the common 22457@code{1234H} numeric syntax is not supported (use @code{0x1234} 22458instead). Example: 22459 22460@smallexample 22461#pragma ADDRESS port3 0x103 22462char port3; 22463@end smallexample 22464 22465@end table 22466 22467@node MeP Pragmas 22468@subsection MeP Pragmas 22469 22470@table @code 22471 22472@item custom io_volatile (on|off) 22473@cindex pragma, custom io_volatile 22474Overrides the command-line option @code{-mio-volatile} for the current 22475file. Note that for compatibility with future GCC releases, this 22476option should only be used once before any @code{io} variables in each 22477file. 22478 22479@item GCC coprocessor available @var{registers} 22480@cindex pragma, coprocessor available 22481Specifies which coprocessor registers are available to the register 22482allocator. @var{registers} may be a single register, register range 22483separated by ellipses, or comma-separated list of those. Example: 22484 22485@smallexample 22486#pragma GCC coprocessor available $c0...$c10, $c28 22487@end smallexample 22488 22489@item GCC coprocessor call_saved @var{registers} 22490@cindex pragma, coprocessor call_saved 22491Specifies which coprocessor registers are to be saved and restored by 22492any function using them. @var{registers} may be a single register, 22493register range separated by ellipses, or comma-separated list of 22494those. Example: 22495 22496@smallexample 22497#pragma GCC coprocessor call_saved $c4...$c6, $c31 22498@end smallexample 22499 22500@item GCC coprocessor subclass '(A|B|C|D)' = @var{registers} 22501@cindex pragma, coprocessor subclass 22502Creates and defines a register class. These register classes can be 22503used by inline @code{asm} constructs. @var{registers} may be a single 22504register, register range separated by ellipses, or comma-separated 22505list of those. Example: 22506 22507@smallexample 22508#pragma GCC coprocessor subclass 'B' = $c2, $c4, $c6 22509 22510asm ("cpfoo %0" : "=B" (x)); 22511@end smallexample 22512 22513@item GCC disinterrupt @var{name} , @var{name} @dots{} 22514@cindex pragma, disinterrupt 22515For the named functions, the compiler adds code to disable interrupts 22516for the duration of those functions. If any functions so named 22517are not encountered in the source, a warning is emitted that the pragma is 22518not used. Examples: 22519 22520@smallexample 22521#pragma disinterrupt foo 22522#pragma disinterrupt bar, grill 22523int foo () @{ @dots{} @} 22524@end smallexample 22525 22526@item GCC call @var{name} , @var{name} @dots{} 22527@cindex pragma, call 22528For the named functions, the compiler always uses a register-indirect 22529call model when calling the named functions. Examples: 22530 22531@smallexample 22532extern int foo (); 22533#pragma call foo 22534@end smallexample 22535 22536@end table 22537 22538@node RS/6000 and PowerPC Pragmas 22539@subsection RS/6000 and PowerPC Pragmas 22540 22541The RS/6000 and PowerPC targets define one pragma for controlling 22542whether or not the @code{longcall} attribute is added to function 22543declarations by default. This pragma overrides the @option{-mlongcall} 22544option, but not the @code{longcall} and @code{shortcall} attributes. 22545@xref{RS/6000 and PowerPC Options}, for more information about when long 22546calls are and are not necessary. 22547 22548@table @code 22549@item longcall (1) 22550@cindex pragma, longcall 22551Apply the @code{longcall} attribute to all subsequent function 22552declarations. 22553 22554@item longcall (0) 22555Do not apply the @code{longcall} attribute to subsequent function 22556declarations. 22557@end table 22558 22559@c Describe h8300 pragmas here. 22560@c Describe sh pragmas here. 22561@c Describe v850 pragmas here. 22562 22563@node S/390 Pragmas 22564@subsection S/390 Pragmas 22565 22566The pragmas defined by the S/390 target correspond to the S/390 22567target function attributes and some the additional options: 22568 22569@table @samp 22570@item zvector 22571@itemx no-zvector 22572@end table 22573 22574Note that options of the pragma, unlike options of the target 22575attribute, do change the value of preprocessor macros like 22576@code{__VEC__}. They can be specified as below: 22577 22578@smallexample 22579#pragma GCC target("string[,string]...") 22580#pragma GCC target("string"[,"string"]...) 22581@end smallexample 22582 22583@node Darwin Pragmas 22584@subsection Darwin Pragmas 22585 22586The following pragmas are available for all architectures running the 22587Darwin operating system. These are useful for compatibility with other 22588Mac OS compilers. 22589 22590@table @code 22591@item mark @var{tokens}@dots{} 22592@cindex pragma, mark 22593This pragma is accepted, but has no effect. 22594 22595@item options align=@var{alignment} 22596@cindex pragma, options align 22597This pragma sets the alignment of fields in structures. The values of 22598@var{alignment} may be @code{mac68k}, to emulate m68k alignment, or 22599@code{power}, to emulate PowerPC alignment. Uses of this pragma nest 22600properly; to restore the previous setting, use @code{reset} for the 22601@var{alignment}. 22602 22603@item segment @var{tokens}@dots{} 22604@cindex pragma, segment 22605This pragma is accepted, but has no effect. 22606 22607@item unused (@var{var} [, @var{var}]@dots{}) 22608@cindex pragma, unused 22609This pragma declares variables to be possibly unused. GCC does not 22610produce warnings for the listed variables. The effect is similar to 22611that of the @code{unused} attribute, except that this pragma may appear 22612anywhere within the variables' scopes. 22613@end table 22614 22615@node Solaris Pragmas 22616@subsection Solaris Pragmas 22617 22618The Solaris target supports @code{#pragma redefine_extname} 22619(@pxref{Symbol-Renaming Pragmas}). It also supports additional 22620@code{#pragma} directives for compatibility with the system compiler. 22621 22622@table @code 22623@item align @var{alignment} (@var{variable} [, @var{variable}]...) 22624@cindex pragma, align 22625 22626Increase the minimum alignment of each @var{variable} to @var{alignment}. 22627This is the same as GCC's @code{aligned} attribute @pxref{Variable 22628Attributes}). Macro expansion occurs on the arguments to this pragma 22629when compiling C and Objective-C@. It does not currently occur when 22630compiling C++, but this is a bug which may be fixed in a future 22631release. 22632 22633@item fini (@var{function} [, @var{function}]...) 22634@cindex pragma, fini 22635 22636This pragma causes each listed @var{function} to be called after 22637main, or during shared module unloading, by adding a call to the 22638@code{.fini} section. 22639 22640@item init (@var{function} [, @var{function}]...) 22641@cindex pragma, init 22642 22643This pragma causes each listed @var{function} to be called during 22644initialization (before @code{main}) or during shared module loading, by 22645adding a call to the @code{.init} section. 22646 22647@end table 22648 22649@node Symbol-Renaming Pragmas 22650@subsection Symbol-Renaming Pragmas 22651 22652GCC supports a @code{#pragma} directive that changes the name used in 22653assembly for a given declaration. While this pragma is supported on all 22654platforms, it is intended primarily to provide compatibility with the 22655Solaris system headers. This effect can also be achieved using the asm 22656labels extension (@pxref{Asm Labels}). 22657 22658@table @code 22659@item redefine_extname @var{oldname} @var{newname} 22660@cindex pragma, redefine_extname 22661 22662This pragma gives the C function @var{oldname} the assembly symbol 22663@var{newname}. The preprocessor macro @code{__PRAGMA_REDEFINE_EXTNAME} 22664is defined if this pragma is available (currently on all platforms). 22665@end table 22666 22667This pragma and the asm labels extension interact in a complicated 22668manner. Here are some corner cases you may want to be aware of: 22669 22670@enumerate 22671@item This pragma silently applies only to declarations with external 22672linkage. Asm labels do not have this restriction. 22673 22674@item In C++, this pragma silently applies only to declarations with 22675``C'' linkage. Again, asm labels do not have this restriction. 22676 22677@item If either of the ways of changing the assembly name of a 22678declaration are applied to a declaration whose assembly name has 22679already been determined (either by a previous use of one of these 22680features, or because the compiler needed the assembly name in order to 22681generate code), and the new name is different, a warning issues and 22682the name does not change. 22683 22684@item The @var{oldname} used by @code{#pragma redefine_extname} is 22685always the C-language name. 22686@end enumerate 22687 22688@node Structure-Layout Pragmas 22689@subsection Structure-Layout Pragmas 22690 22691For compatibility with Microsoft Windows compilers, GCC supports a 22692set of @code{#pragma} directives that change the maximum alignment of 22693members of structures (other than zero-width bit-fields), unions, and 22694classes subsequently defined. The @var{n} value below always is required 22695to be a small power of two and specifies the new alignment in bytes. 22696 22697@enumerate 22698@item @code{#pragma pack(@var{n})} simply sets the new alignment. 22699@item @code{#pragma pack()} sets the alignment to the one that was in 22700effect when compilation started (see also command-line option 22701@option{-fpack-struct[=@var{n}]} @pxref{Code Gen Options}). 22702@item @code{#pragma pack(push[,@var{n}])} pushes the current alignment 22703setting on an internal stack and then optionally sets the new alignment. 22704@item @code{#pragma pack(pop)} restores the alignment setting to the one 22705saved at the top of the internal stack (and removes that stack entry). 22706Note that @code{#pragma pack([@var{n}])} does not influence this internal 22707stack; thus it is possible to have @code{#pragma pack(push)} followed by 22708multiple @code{#pragma pack(@var{n})} instances and finalized by a single 22709@code{#pragma pack(pop)}. 22710@end enumerate 22711 22712Some targets, e.g.@: x86 and PowerPC, support the @code{#pragma ms_struct} 22713directive which lays out structures and unions subsequently defined as the 22714documented @code{__attribute__ ((ms_struct))}. 22715 22716@enumerate 22717@item @code{#pragma ms_struct on} turns on the Microsoft layout. 22718@item @code{#pragma ms_struct off} turns off the Microsoft layout. 22719@item @code{#pragma ms_struct reset} goes back to the default layout. 22720@end enumerate 22721 22722Most targets also support the @code{#pragma scalar_storage_order} directive 22723which lays out structures and unions subsequently defined as the documented 22724@code{__attribute__ ((scalar_storage_order))}. 22725 22726@enumerate 22727@item @code{#pragma scalar_storage_order big-endian} sets the storage order 22728of the scalar fields to big-endian. 22729@item @code{#pragma scalar_storage_order little-endian} sets the storage order 22730of the scalar fields to little-endian. 22731@item @code{#pragma scalar_storage_order default} goes back to the endianness 22732that was in effect when compilation started (see also command-line option 22733@option{-fsso-struct=@var{endianness}} @pxref{C Dialect Options}). 22734@end enumerate 22735 22736@node Weak Pragmas 22737@subsection Weak Pragmas 22738 22739For compatibility with SVR4, GCC supports a set of @code{#pragma} 22740directives for declaring symbols to be weak, and defining weak 22741aliases. 22742 22743@table @code 22744@item #pragma weak @var{symbol} 22745@cindex pragma, weak 22746This pragma declares @var{symbol} to be weak, as if the declaration 22747had the attribute of the same name. The pragma may appear before 22748or after the declaration of @var{symbol}. It is not an error for 22749@var{symbol} to never be defined at all. 22750 22751@item #pragma weak @var{symbol1} = @var{symbol2} 22752This pragma declares @var{symbol1} to be a weak alias of @var{symbol2}. 22753It is an error if @var{symbol2} is not defined in the current 22754translation unit. 22755@end table 22756 22757@node Diagnostic Pragmas 22758@subsection Diagnostic Pragmas 22759 22760GCC allows the user to selectively enable or disable certain types of 22761diagnostics, and change the kind of the diagnostic. For example, a 22762project's policy might require that all sources compile with 22763@option{-Werror} but certain files might have exceptions allowing 22764specific types of warnings. Or, a project might selectively enable 22765diagnostics and treat them as errors depending on which preprocessor 22766macros are defined. 22767 22768@table @code 22769@item #pragma GCC diagnostic @var{kind} @var{option} 22770@cindex pragma, diagnostic 22771 22772Modifies the disposition of a diagnostic. Note that not all 22773diagnostics are modifiable; at the moment only warnings (normally 22774controlled by @samp{-W@dots{}}) can be controlled, and not all of them. 22775Use @option{-fdiagnostics-show-option} to determine which diagnostics 22776are controllable and which option controls them. 22777 22778@var{kind} is @samp{error} to treat this diagnostic as an error, 22779@samp{warning} to treat it like a warning (even if @option{-Werror} is 22780in effect), or @samp{ignored} if the diagnostic is to be ignored. 22781@var{option} is a double quoted string that matches the command-line 22782option. 22783 22784@smallexample 22785#pragma GCC diagnostic warning "-Wformat" 22786#pragma GCC diagnostic error "-Wformat" 22787#pragma GCC diagnostic ignored "-Wformat" 22788@end smallexample 22789 22790Note that these pragmas override any command-line options. GCC keeps 22791track of the location of each pragma, and issues diagnostics according 22792to the state as of that point in the source file. Thus, pragmas occurring 22793after a line do not affect diagnostics caused by that line. 22794 22795@item #pragma GCC diagnostic push 22796@itemx #pragma GCC diagnostic pop 22797 22798Causes GCC to remember the state of the diagnostics as of each 22799@code{push}, and restore to that point at each @code{pop}. If a 22800@code{pop} has no matching @code{push}, the command-line options are 22801restored. 22802 22803@smallexample 22804#pragma GCC diagnostic error "-Wuninitialized" 22805 foo(a); /* error is given for this one */ 22806#pragma GCC diagnostic push 22807#pragma GCC diagnostic ignored "-Wuninitialized" 22808 foo(b); /* no diagnostic for this one */ 22809#pragma GCC diagnostic pop 22810 foo(c); /* error is given for this one */ 22811#pragma GCC diagnostic pop 22812 foo(d); /* depends on command-line options */ 22813@end smallexample 22814 22815@end table 22816 22817GCC also offers a simple mechanism for printing messages during 22818compilation. 22819 22820@table @code 22821@item #pragma message @var{string} 22822@cindex pragma, diagnostic 22823 22824Prints @var{string} as a compiler message on compilation. The message 22825is informational only, and is neither a compilation warning nor an error. 22826 22827@smallexample 22828#pragma message "Compiling " __FILE__ "..." 22829@end smallexample 22830 22831@var{string} may be parenthesized, and is printed with location 22832information. For example, 22833 22834@smallexample 22835#define DO_PRAGMA(x) _Pragma (#x) 22836#define TODO(x) DO_PRAGMA(message ("TODO - " #x)) 22837 22838TODO(Remember to fix this) 22839@end smallexample 22840 22841@noindent 22842prints @samp{/tmp/file.c:4: note: #pragma message: 22843TODO - Remember to fix this}. 22844 22845@end table 22846 22847@node Visibility Pragmas 22848@subsection Visibility Pragmas 22849 22850@table @code 22851@item #pragma GCC visibility push(@var{visibility}) 22852@itemx #pragma GCC visibility pop 22853@cindex pragma, visibility 22854 22855This pragma allows the user to set the visibility for multiple 22856declarations without having to give each a visibility attribute 22857(@pxref{Function Attributes}). 22858 22859In C++, @samp{#pragma GCC visibility} affects only namespace-scope 22860declarations. Class members and template specializations are not 22861affected; if you want to override the visibility for a particular 22862member or instantiation, you must use an attribute. 22863 22864@end table 22865 22866 22867@node Push/Pop Macro Pragmas 22868@subsection Push/Pop Macro Pragmas 22869 22870For compatibility with Microsoft Windows compilers, GCC supports 22871@samp{#pragma push_macro(@var{"macro_name"})} 22872and @samp{#pragma pop_macro(@var{"macro_name"})}. 22873 22874@table @code 22875@item #pragma push_macro(@var{"macro_name"}) 22876@cindex pragma, push_macro 22877This pragma saves the value of the macro named as @var{macro_name} to 22878the top of the stack for this macro. 22879 22880@item #pragma pop_macro(@var{"macro_name"}) 22881@cindex pragma, pop_macro 22882This pragma sets the value of the macro named as @var{macro_name} to 22883the value on top of the stack for this macro. If the stack for 22884@var{macro_name} is empty, the value of the macro remains unchanged. 22885@end table 22886 22887For example: 22888 22889@smallexample 22890#define X 1 22891#pragma push_macro("X") 22892#undef X 22893#define X -1 22894#pragma pop_macro("X") 22895int x [X]; 22896@end smallexample 22897 22898@noindent 22899In this example, the definition of X as 1 is saved by @code{#pragma 22900push_macro} and restored by @code{#pragma pop_macro}. 22901 22902@node Function Specific Option Pragmas 22903@subsection Function Specific Option Pragmas 22904 22905@table @code 22906@item #pragma GCC target (@var{"string"}...) 22907@cindex pragma GCC target 22908 22909This pragma allows you to set target specific options for functions 22910defined later in the source file. One or more strings can be 22911specified. Each function that is defined after this point is as 22912if @code{attribute((target("STRING")))} was specified for that 22913function. The parenthesis around the options is optional. 22914@xref{Function Attributes}, for more information about the 22915@code{target} attribute and the attribute syntax. 22916 22917The @code{#pragma GCC target} pragma is presently implemented for 22918x86, ARM, AArch64, PowerPC, S/390, and Nios II targets only. 22919 22920@item #pragma GCC optimize (@var{"string"}...) 22921@cindex pragma GCC optimize 22922 22923This pragma allows you to set global optimization options for functions 22924defined later in the source file. One or more strings can be 22925specified. Each function that is defined after this point is as 22926if @code{attribute((optimize("STRING")))} was specified for that 22927function. The parenthesis around the options is optional. 22928@xref{Function Attributes}, for more information about the 22929@code{optimize} attribute and the attribute syntax. 22930 22931@item #pragma GCC push_options 22932@itemx #pragma GCC pop_options 22933@cindex pragma GCC push_options 22934@cindex pragma GCC pop_options 22935 22936These pragmas maintain a stack of the current target and optimization 22937options. It is intended for include files where you temporarily want 22938to switch to using a different @samp{#pragma GCC target} or 22939@samp{#pragma GCC optimize} and then to pop back to the previous 22940options. 22941 22942@item #pragma GCC reset_options 22943@cindex pragma GCC reset_options 22944 22945This pragma clears the current @code{#pragma GCC target} and 22946@code{#pragma GCC optimize} to use the default switches as specified 22947on the command line. 22948 22949@end table 22950 22951@node Loop-Specific Pragmas 22952@subsection Loop-Specific Pragmas 22953 22954@table @code 22955@item #pragma GCC ivdep 22956@cindex pragma GCC ivdep 22957 22958With this pragma, the programmer asserts that there are no loop-carried 22959dependencies which would prevent consecutive iterations of 22960the following loop from executing concurrently with SIMD 22961(single instruction multiple data) instructions. 22962 22963For example, the compiler can only unconditionally vectorize the following 22964loop with the pragma: 22965 22966@smallexample 22967void foo (int n, int *a, int *b, int *c) 22968@{ 22969 int i, j; 22970#pragma GCC ivdep 22971 for (i = 0; i < n; ++i) 22972 a[i] = b[i] + c[i]; 22973@} 22974@end smallexample 22975 22976@noindent 22977In this example, using the @code{restrict} qualifier had the same 22978effect. In the following example, that would not be possible. Assume 22979@math{k < -m} or @math{k >= m}. Only with the pragma, the compiler knows 22980that it can unconditionally vectorize the following loop: 22981 22982@smallexample 22983void ignore_vec_dep (int *a, int k, int c, int m) 22984@{ 22985#pragma GCC ivdep 22986 for (int i = 0; i < m; i++) 22987 a[i] = a[i + k] * c; 22988@} 22989@end smallexample 22990 22991@item #pragma GCC unroll @var{n} 22992@cindex pragma GCC unroll @var{n} 22993 22994You can use this pragma to control how many times a loop should be unrolled. 22995It must be placed immediately before a @code{for}, @code{while} or @code{do} 22996loop or a @code{#pragma GCC ivdep}, and applies only to the loop that follows. 22997@var{n} is an integer constant expression specifying the unrolling factor. 22998The values of @math{0} and @math{1} block any unrolling of the loop. 22999 23000@end table 23001 23002@node Unnamed Fields 23003@section Unnamed Structure and Union Fields 23004@cindex @code{struct} 23005@cindex @code{union} 23006 23007As permitted by ISO C11 and for compatibility with other compilers, 23008GCC allows you to define 23009a structure or union that contains, as fields, structures and unions 23010without names. For example: 23011 23012@smallexample 23013struct @{ 23014 int a; 23015 union @{ 23016 int b; 23017 float c; 23018 @}; 23019 int d; 23020@} foo; 23021@end smallexample 23022 23023@noindent 23024In this example, you are able to access members of the unnamed 23025union with code like @samp{foo.b}. Note that only unnamed structs and 23026unions are allowed, you may not have, for example, an unnamed 23027@code{int}. 23028 23029You must never create such structures that cause ambiguous field definitions. 23030For example, in this structure: 23031 23032@smallexample 23033struct @{ 23034 int a; 23035 struct @{ 23036 int a; 23037 @}; 23038@} foo; 23039@end smallexample 23040 23041@noindent 23042it is ambiguous which @code{a} is being referred to with @samp{foo.a}. 23043The compiler gives errors for such constructs. 23044 23045@opindex fms-extensions 23046Unless @option{-fms-extensions} is used, the unnamed field must be a 23047structure or union definition without a tag (for example, @samp{struct 23048@{ int a; @};}). If @option{-fms-extensions} is used, the field may 23049also be a definition with a tag such as @samp{struct foo @{ int a; 23050@};}, a reference to a previously defined structure or union such as 23051@samp{struct foo;}, or a reference to a @code{typedef} name for a 23052previously defined structure or union type. 23053 23054@opindex fplan9-extensions 23055The option @option{-fplan9-extensions} enables 23056@option{-fms-extensions} as well as two other extensions. First, a 23057pointer to a structure is automatically converted to a pointer to an 23058anonymous field for assignments and function calls. For example: 23059 23060@smallexample 23061struct s1 @{ int a; @}; 23062struct s2 @{ struct s1; @}; 23063extern void f1 (struct s1 *); 23064void f2 (struct s2 *p) @{ f1 (p); @} 23065@end smallexample 23066 23067@noindent 23068In the call to @code{f1} inside @code{f2}, the pointer @code{p} is 23069converted into a pointer to the anonymous field. 23070 23071Second, when the type of an anonymous field is a @code{typedef} for a 23072@code{struct} or @code{union}, code may refer to the field using the 23073name of the @code{typedef}. 23074 23075@smallexample 23076typedef struct @{ int a; @} s1; 23077struct s2 @{ s1; @}; 23078s1 f1 (struct s2 *p) @{ return p->s1; @} 23079@end smallexample 23080 23081These usages are only permitted when they are not ambiguous. 23082 23083@node Thread-Local 23084@section Thread-Local Storage 23085@cindex Thread-Local Storage 23086@cindex @acronym{TLS} 23087@cindex @code{__thread} 23088 23089Thread-local storage (@acronym{TLS}) is a mechanism by which variables 23090are allocated such that there is one instance of the variable per extant 23091thread. The runtime model GCC uses to implement this originates 23092in the IA-64 processor-specific ABI, but has since been migrated 23093to other processors as well. It requires significant support from 23094the linker (@command{ld}), dynamic linker (@command{ld.so}), and 23095system libraries (@file{libc.so} and @file{libpthread.so}), so it 23096is not available everywhere. 23097 23098At the user level, the extension is visible with a new storage 23099class keyword: @code{__thread}. For example: 23100 23101@smallexample 23102__thread int i; 23103extern __thread struct state s; 23104static __thread char *p; 23105@end smallexample 23106 23107The @code{__thread} specifier may be used alone, with the @code{extern} 23108or @code{static} specifiers, but with no other storage class specifier. 23109When used with @code{extern} or @code{static}, @code{__thread} must appear 23110immediately after the other storage class specifier. 23111 23112The @code{__thread} specifier may be applied to any global, file-scoped 23113static, function-scoped static, or static data member of a class. It may 23114not be applied to block-scoped automatic or non-static data member. 23115 23116When the address-of operator is applied to a thread-local variable, it is 23117evaluated at run time and returns the address of the current thread's 23118instance of that variable. An address so obtained may be used by any 23119thread. When a thread terminates, any pointers to thread-local variables 23120in that thread become invalid. 23121 23122No static initialization may refer to the address of a thread-local variable. 23123 23124In C++, if an initializer is present for a thread-local variable, it must 23125be a @var{constant-expression}, as defined in 5.19.2 of the ANSI/ISO C++ 23126standard. 23127 23128See @uref{https://www.akkadia.org/drepper/tls.pdf, 23129ELF Handling For Thread-Local Storage} for a detailed explanation of 23130the four thread-local storage addressing models, and how the runtime 23131is expected to function. 23132 23133@menu 23134* C99 Thread-Local Edits:: 23135* C++98 Thread-Local Edits:: 23136@end menu 23137 23138@node C99 Thread-Local Edits 23139@subsection ISO/IEC 9899:1999 Edits for Thread-Local Storage 23140 23141The following are a set of changes to ISO/IEC 9899:1999 (aka C99) 23142that document the exact semantics of the language extension. 23143 23144@itemize @bullet 23145@item 23146@cite{5.1.2 Execution environments} 23147 23148Add new text after paragraph 1 23149 23150@quotation 23151Within either execution environment, a @dfn{thread} is a flow of 23152control within a program. It is implementation defined whether 23153or not there may be more than one thread associated with a program. 23154It is implementation defined how threads beyond the first are 23155created, the name and type of the function called at thread 23156startup, and how threads may be terminated. However, objects 23157with thread storage duration shall be initialized before thread 23158startup. 23159@end quotation 23160 23161@item 23162@cite{6.2.4 Storage durations of objects} 23163 23164Add new text before paragraph 3 23165 23166@quotation 23167An object whose identifier is declared with the storage-class 23168specifier @w{@code{__thread}} has @dfn{thread storage duration}. 23169Its lifetime is the entire execution of the thread, and its 23170stored value is initialized only once, prior to thread startup. 23171@end quotation 23172 23173@item 23174@cite{6.4.1 Keywords} 23175 23176Add @code{__thread}. 23177 23178@item 23179@cite{6.7.1 Storage-class specifiers} 23180 23181Add @code{__thread} to the list of storage class specifiers in 23182paragraph 1. 23183 23184Change paragraph 2 to 23185 23186@quotation 23187With the exception of @code{__thread}, at most one storage-class 23188specifier may be given [@dots{}]. The @code{__thread} specifier may 23189be used alone, or immediately following @code{extern} or 23190@code{static}. 23191@end quotation 23192 23193Add new text after paragraph 6 23194 23195@quotation 23196The declaration of an identifier for a variable that has 23197block scope that specifies @code{__thread} shall also 23198specify either @code{extern} or @code{static}. 23199 23200The @code{__thread} specifier shall be used only with 23201variables. 23202@end quotation 23203@end itemize 23204 23205@node C++98 Thread-Local Edits 23206@subsection ISO/IEC 14882:1998 Edits for Thread-Local Storage 23207 23208The following are a set of changes to ISO/IEC 14882:1998 (aka C++98) 23209that document the exact semantics of the language extension. 23210 23211@itemize @bullet 23212@item 23213@b{[intro.execution]} 23214 23215New text after paragraph 4 23216 23217@quotation 23218A @dfn{thread} is a flow of control within the abstract machine. 23219It is implementation defined whether or not there may be more than 23220one thread. 23221@end quotation 23222 23223New text after paragraph 7 23224 23225@quotation 23226It is unspecified whether additional action must be taken to 23227ensure when and whether side effects are visible to other threads. 23228@end quotation 23229 23230@item 23231@b{[lex.key]} 23232 23233Add @code{__thread}. 23234 23235@item 23236@b{[basic.start.main]} 23237 23238Add after paragraph 5 23239 23240@quotation 23241The thread that begins execution at the @code{main} function is called 23242the @dfn{main thread}. It is implementation defined how functions 23243beginning threads other than the main thread are designated or typed. 23244A function so designated, as well as the @code{main} function, is called 23245a @dfn{thread startup function}. It is implementation defined what 23246happens if a thread startup function returns. It is implementation 23247defined what happens to other threads when any thread calls @code{exit}. 23248@end quotation 23249 23250@item 23251@b{[basic.start.init]} 23252 23253Add after paragraph 4 23254 23255@quotation 23256The storage for an object of thread storage duration shall be 23257statically initialized before the first statement of the thread startup 23258function. An object of thread storage duration shall not require 23259dynamic initialization. 23260@end quotation 23261 23262@item 23263@b{[basic.start.term]} 23264 23265Add after paragraph 3 23266 23267@quotation 23268The type of an object with thread storage duration shall not have a 23269non-trivial destructor, nor shall it be an array type whose elements 23270(directly or indirectly) have non-trivial destructors. 23271@end quotation 23272 23273@item 23274@b{[basic.stc]} 23275 23276Add ``thread storage duration'' to the list in paragraph 1. 23277 23278Change paragraph 2 23279 23280@quotation 23281Thread, static, and automatic storage durations are associated with 23282objects introduced by declarations [@dots{}]. 23283@end quotation 23284 23285Add @code{__thread} to the list of specifiers in paragraph 3. 23286 23287@item 23288@b{[basic.stc.thread]} 23289 23290New section before @b{[basic.stc.static]} 23291 23292@quotation 23293The keyword @code{__thread} applied to a non-local object gives the 23294object thread storage duration. 23295 23296A local variable or class data member declared both @code{static} 23297and @code{__thread} gives the variable or member thread storage 23298duration. 23299@end quotation 23300 23301@item 23302@b{[basic.stc.static]} 23303 23304Change paragraph 1 23305 23306@quotation 23307All objects that have neither thread storage duration, dynamic 23308storage duration nor are local [@dots{}]. 23309@end quotation 23310 23311@item 23312@b{[dcl.stc]} 23313 23314Add @code{__thread} to the list in paragraph 1. 23315 23316Change paragraph 1 23317 23318@quotation 23319With the exception of @code{__thread}, at most one 23320@var{storage-class-specifier} shall appear in a given 23321@var{decl-specifier-seq}. The @code{__thread} specifier may 23322be used alone, or immediately following the @code{extern} or 23323@code{static} specifiers. [@dots{}] 23324@end quotation 23325 23326Add after paragraph 5 23327 23328@quotation 23329The @code{__thread} specifier can be applied only to the names of objects 23330and to anonymous unions. 23331@end quotation 23332 23333@item 23334@b{[class.mem]} 23335 23336Add after paragraph 6 23337 23338@quotation 23339Non-@code{static} members shall not be @code{__thread}. 23340@end quotation 23341@end itemize 23342 23343@node Binary constants 23344@section Binary Constants using the @samp{0b} Prefix 23345@cindex Binary constants using the @samp{0b} prefix 23346 23347Integer constants can be written as binary constants, consisting of a 23348sequence of @samp{0} and @samp{1} digits, prefixed by @samp{0b} or 23349@samp{0B}. This is particularly useful in environments that operate a 23350lot on the bit level (like microcontrollers). 23351 23352The following statements are identical: 23353 23354@smallexample 23355i = 42; 23356i = 0x2a; 23357i = 052; 23358i = 0b101010; 23359@end smallexample 23360 23361The type of these constants follows the same rules as for octal or 23362hexadecimal integer constants, so suffixes like @samp{L} or @samp{UL} 23363can be applied. 23364 23365@node C++ Extensions 23366@chapter Extensions to the C++ Language 23367@cindex extensions, C++ language 23368@cindex C++ language extensions 23369 23370The GNU compiler provides these extensions to the C++ language (and you 23371can also use most of the C language extensions in your C++ programs). If you 23372want to write code that checks whether these features are available, you can 23373test for the GNU compiler the same way as for C programs: check for a 23374predefined macro @code{__GNUC__}. You can also use @code{__GNUG__} to 23375test specifically for GNU C++ (@pxref{Common Predefined Macros,, 23376Predefined Macros,cpp,The GNU C Preprocessor}). 23377 23378@menu 23379* C++ Volatiles:: What constitutes an access to a volatile object. 23380* Restricted Pointers:: C99 restricted pointers and references. 23381* Vague Linkage:: Where G++ puts inlines, vtables and such. 23382* C++ Interface:: You can use a single C++ header file for both 23383 declarations and definitions. 23384* Template Instantiation:: Methods for ensuring that exactly one copy of 23385 each needed template instantiation is emitted. 23386* Bound member functions:: You can extract a function pointer to the 23387 method denoted by a @samp{->*} or @samp{.*} expression. 23388* C++ Attributes:: Variable, function, and type attributes for C++ only. 23389* Function Multiversioning:: Declaring multiple function versions. 23390* Type Traits:: Compiler support for type traits. 23391* C++ Concepts:: Improved support for generic programming. 23392* Deprecated Features:: Things will disappear from G++. 23393* Backwards Compatibility:: Compatibilities with earlier definitions of C++. 23394@end menu 23395 23396@node C++ Volatiles 23397@section When is a Volatile C++ Object Accessed? 23398@cindex accessing volatiles 23399@cindex volatile read 23400@cindex volatile write 23401@cindex volatile access 23402 23403The C++ standard differs from the C standard in its treatment of 23404volatile objects. It fails to specify what constitutes a volatile 23405access, except to say that C++ should behave in a similar manner to C 23406with respect to volatiles, where possible. However, the different 23407lvalueness of expressions between C and C++ complicate the behavior. 23408G++ behaves the same as GCC for volatile access, @xref{C 23409Extensions,,Volatiles}, for a description of GCC's behavior. 23410 23411The C and C++ language specifications differ when an object is 23412accessed in a void context: 23413 23414@smallexample 23415volatile int *src = @var{somevalue}; 23416*src; 23417@end smallexample 23418 23419The C++ standard specifies that such expressions do not undergo lvalue 23420to rvalue conversion, and that the type of the dereferenced object may 23421be incomplete. The C++ standard does not specify explicitly that it 23422is lvalue to rvalue conversion that is responsible for causing an 23423access. There is reason to believe that it is, because otherwise 23424certain simple expressions become undefined. However, because it 23425would surprise most programmers, G++ treats dereferencing a pointer to 23426volatile object of complete type as GCC would do for an equivalent 23427type in C@. When the object has incomplete type, G++ issues a 23428warning; if you wish to force an error, you must force a conversion to 23429rvalue with, for instance, a static cast. 23430 23431When using a reference to volatile, G++ does not treat equivalent 23432expressions as accesses to volatiles, but instead issues a warning that 23433no volatile is accessed. The rationale for this is that otherwise it 23434becomes difficult to determine where volatile access occur, and not 23435possible to ignore the return value from functions returning volatile 23436references. Again, if you wish to force a read, cast the reference to 23437an rvalue. 23438 23439G++ implements the same behavior as GCC does when assigning to a 23440volatile object---there is no reread of the assigned-to object, the 23441assigned rvalue is reused. Note that in C++ assignment expressions 23442are lvalues, and if used as an lvalue, the volatile object is 23443referred to. For instance, @var{vref} refers to @var{vobj}, as 23444expected, in the following example: 23445 23446@smallexample 23447volatile int vobj; 23448volatile int &vref = vobj = @var{something}; 23449@end smallexample 23450 23451@node Restricted Pointers 23452@section Restricting Pointer Aliasing 23453@cindex restricted pointers 23454@cindex restricted references 23455@cindex restricted this pointer 23456 23457As with the C front end, G++ understands the C99 feature of restricted pointers, 23458specified with the @code{__restrict__}, or @code{__restrict} type 23459qualifier. Because you cannot compile C++ by specifying the @option{-std=c99} 23460language flag, @code{restrict} is not a keyword in C++. 23461 23462In addition to allowing restricted pointers, you can specify restricted 23463references, which indicate that the reference is not aliased in the local 23464context. 23465 23466@smallexample 23467void fn (int *__restrict__ rptr, int &__restrict__ rref) 23468@{ 23469 /* @r{@dots{}} */ 23470@} 23471@end smallexample 23472 23473@noindent 23474In the body of @code{fn}, @var{rptr} points to an unaliased integer and 23475@var{rref} refers to a (different) unaliased integer. 23476 23477You may also specify whether a member function's @var{this} pointer is 23478unaliased by using @code{__restrict__} as a member function qualifier. 23479 23480@smallexample 23481void T::fn () __restrict__ 23482@{ 23483 /* @r{@dots{}} */ 23484@} 23485@end smallexample 23486 23487@noindent 23488Within the body of @code{T::fn}, @var{this} has the effective 23489definition @code{T *__restrict__ const this}. Notice that the 23490interpretation of a @code{__restrict__} member function qualifier is 23491different to that of @code{const} or @code{volatile} qualifier, in that it 23492is applied to the pointer rather than the object. This is consistent with 23493other compilers that implement restricted pointers. 23494 23495As with all outermost parameter qualifiers, @code{__restrict__} is 23496ignored in function definition matching. This means you only need to 23497specify @code{__restrict__} in a function definition, rather than 23498in a function prototype as well. 23499 23500@node Vague Linkage 23501@section Vague Linkage 23502@cindex vague linkage 23503 23504There are several constructs in C++ that require space in the object 23505file but are not clearly tied to a single translation unit. We say that 23506these constructs have ``vague linkage''. Typically such constructs are 23507emitted wherever they are needed, though sometimes we can be more 23508clever. 23509 23510@table @asis 23511@item Inline Functions 23512Inline functions are typically defined in a header file which can be 23513included in many different compilations. Hopefully they can usually be 23514inlined, but sometimes an out-of-line copy is necessary, if the address 23515of the function is taken or if inlining fails. In general, we emit an 23516out-of-line copy in all translation units where one is needed. As an 23517exception, we only emit inline virtual functions with the vtable, since 23518it always requires a copy. 23519 23520Local static variables and string constants used in an inline function 23521are also considered to have vague linkage, since they must be shared 23522between all inlined and out-of-line instances of the function. 23523 23524@item VTables 23525@cindex vtable 23526C++ virtual functions are implemented in most compilers using a lookup 23527table, known as a vtable. The vtable contains pointers to the virtual 23528functions provided by a class, and each object of the class contains a 23529pointer to its vtable (or vtables, in some multiple-inheritance 23530situations). If the class declares any non-inline, non-pure virtual 23531functions, the first one is chosen as the ``key method'' for the class, 23532and the vtable is only emitted in the translation unit where the key 23533method is defined. 23534 23535@emph{Note:} If the chosen key method is later defined as inline, the 23536vtable is still emitted in every translation unit that defines it. 23537Make sure that any inline virtuals are declared inline in the class 23538body, even if they are not defined there. 23539 23540@item @code{type_info} objects 23541@cindex @code{type_info} 23542@cindex RTTI 23543C++ requires information about types to be written out in order to 23544implement @samp{dynamic_cast}, @samp{typeid} and exception handling. 23545For polymorphic classes (classes with virtual functions), the @samp{type_info} 23546object is written out along with the vtable so that @samp{dynamic_cast} 23547can determine the dynamic type of a class object at run time. For all 23548other types, we write out the @samp{type_info} object when it is used: when 23549applying @samp{typeid} to an expression, throwing an object, or 23550referring to a type in a catch clause or exception specification. 23551 23552@item Template Instantiations 23553Most everything in this section also applies to template instantiations, 23554but there are other options as well. 23555@xref{Template Instantiation,,Where's the Template?}. 23556 23557@end table 23558 23559When used with GNU ld version 2.8 or later on an ELF system such as 23560GNU/Linux or Solaris 2, or on Microsoft Windows, duplicate copies of 23561these constructs will be discarded at link time. This is known as 23562COMDAT support. 23563 23564On targets that don't support COMDAT, but do support weak symbols, GCC 23565uses them. This way one copy overrides all the others, but 23566the unused copies still take up space in the executable. 23567 23568For targets that do not support either COMDAT or weak symbols, 23569most entities with vague linkage are emitted as local symbols to 23570avoid duplicate definition errors from the linker. This does not happen 23571for local statics in inlines, however, as having multiple copies 23572almost certainly breaks things. 23573 23574@xref{C++ Interface,,Declarations and Definitions in One Header}, for 23575another way to control placement of these constructs. 23576 23577@node C++ Interface 23578@section C++ Interface and Implementation Pragmas 23579 23580@cindex interface and implementation headers, C++ 23581@cindex C++ interface and implementation headers 23582@cindex pragmas, interface and implementation 23583 23584@code{#pragma interface} and @code{#pragma implementation} provide the 23585user with a way of explicitly directing the compiler to emit entities 23586with vague linkage (and debugging information) in a particular 23587translation unit. 23588 23589@emph{Note:} These @code{#pragma}s have been superceded as of GCC 2.7.2 23590by COMDAT support and the ``key method'' heuristic 23591mentioned in @ref{Vague Linkage}. Using them can actually cause your 23592program to grow due to unnecessary out-of-line copies of inline 23593functions. 23594 23595@table @code 23596@item #pragma interface 23597@itemx #pragma interface "@var{subdir}/@var{objects}.h" 23598@kindex #pragma interface 23599Use this directive in @emph{header files} that define object classes, to save 23600space in most of the object files that use those classes. Normally, 23601local copies of certain information (backup copies of inline member 23602functions, debugging information, and the internal tables that implement 23603virtual functions) must be kept in each object file that includes class 23604definitions. You can use this pragma to avoid such duplication. When a 23605header file containing @samp{#pragma interface} is included in a 23606compilation, this auxiliary information is not generated (unless 23607the main input source file itself uses @samp{#pragma implementation}). 23608Instead, the object files contain references to be resolved at link 23609time. 23610 23611The second form of this directive is useful for the case where you have 23612multiple headers with the same name in different directories. If you 23613use this form, you must specify the same string to @samp{#pragma 23614implementation}. 23615 23616@item #pragma implementation 23617@itemx #pragma implementation "@var{objects}.h" 23618@kindex #pragma implementation 23619Use this pragma in a @emph{main input file}, when you want full output from 23620included header files to be generated (and made globally visible). The 23621included header file, in turn, should use @samp{#pragma interface}. 23622Backup copies of inline member functions, debugging information, and the 23623internal tables used to implement virtual functions are all generated in 23624implementation files. 23625 23626@cindex implied @code{#pragma implementation} 23627@cindex @code{#pragma implementation}, implied 23628@cindex naming convention, implementation headers 23629If you use @samp{#pragma implementation} with no argument, it applies to 23630an include file with the same basename@footnote{A file's @dfn{basename} 23631is the name stripped of all leading path information and of trailing 23632suffixes, such as @samp{.h} or @samp{.C} or @samp{.cc}.} as your source 23633file. For example, in @file{allclass.cc}, giving just 23634@samp{#pragma implementation} 23635by itself is equivalent to @samp{#pragma implementation "allclass.h"}. 23636 23637Use the string argument if you want a single implementation file to 23638include code from multiple header files. (You must also use 23639@samp{#include} to include the header file; @samp{#pragma 23640implementation} only specifies how to use the file---it doesn't actually 23641include it.) 23642 23643There is no way to split up the contents of a single header file into 23644multiple implementation files. 23645@end table 23646 23647@cindex inlining and C++ pragmas 23648@cindex C++ pragmas, effect on inlining 23649@cindex pragmas in C++, effect on inlining 23650@samp{#pragma implementation} and @samp{#pragma interface} also have an 23651effect on function inlining. 23652 23653If you define a class in a header file marked with @samp{#pragma 23654interface}, the effect on an inline function defined in that class is 23655similar to an explicit @code{extern} declaration---the compiler emits 23656no code at all to define an independent version of the function. Its 23657definition is used only for inlining with its callers. 23658 23659@opindex fno-implement-inlines 23660Conversely, when you include the same header file in a main source file 23661that declares it as @samp{#pragma implementation}, the compiler emits 23662code for the function itself; this defines a version of the function 23663that can be found via pointers (or by callers compiled without 23664inlining). If all calls to the function can be inlined, you can avoid 23665emitting the function by compiling with @option{-fno-implement-inlines}. 23666If any calls are not inlined, you will get linker errors. 23667 23668@node Template Instantiation 23669@section Where's the Template? 23670@cindex template instantiation 23671 23672C++ templates were the first language feature to require more 23673intelligence from the environment than was traditionally found on a UNIX 23674system. Somehow the compiler and linker have to make sure that each 23675template instance occurs exactly once in the executable if it is needed, 23676and not at all otherwise. There are two basic approaches to this 23677problem, which are referred to as the Borland model and the Cfront model. 23678 23679@table @asis 23680@item Borland model 23681Borland C++ solved the template instantiation problem by adding the code 23682equivalent of common blocks to their linker; the compiler emits template 23683instances in each translation unit that uses them, and the linker 23684collapses them together. The advantage of this model is that the linker 23685only has to consider the object files themselves; there is no external 23686complexity to worry about. The disadvantage is that compilation time 23687is increased because the template code is being compiled repeatedly. 23688Code written for this model tends to include definitions of all 23689templates in the header file, since they must be seen to be 23690instantiated. 23691 23692@item Cfront model 23693The AT&T C++ translator, Cfront, solved the template instantiation 23694problem by creating the notion of a template repository, an 23695automatically maintained place where template instances are stored. A 23696more modern version of the repository works as follows: As individual 23697object files are built, the compiler places any template definitions and 23698instantiations encountered in the repository. At link time, the link 23699wrapper adds in the objects in the repository and compiles any needed 23700instances that were not previously emitted. The advantages of this 23701model are more optimal compilation speed and the ability to use the 23702system linker; to implement the Borland model a compiler vendor also 23703needs to replace the linker. The disadvantages are vastly increased 23704complexity, and thus potential for error; for some code this can be 23705just as transparent, but in practice it can been very difficult to build 23706multiple programs in one directory and one program in multiple 23707directories. Code written for this model tends to separate definitions 23708of non-inline member templates into a separate file, which should be 23709compiled separately. 23710@end table 23711 23712G++ implements the Borland model on targets where the linker supports it, 23713including ELF targets (such as GNU/Linux), Mac OS X and Microsoft Windows. 23714Otherwise G++ implements neither automatic model. 23715 23716You have the following options for dealing with template instantiations: 23717 23718@enumerate 23719@item 23720Do nothing. Code written for the Borland model works fine, but 23721each translation unit contains instances of each of the templates it 23722uses. The duplicate instances will be discarded by the linker, but in 23723a large program, this can lead to an unacceptable amount of code 23724duplication in object files or shared libraries. 23725 23726Duplicate instances of a template can be avoided by defining an explicit 23727instantiation in one object file, and preventing the compiler from doing 23728implicit instantiations in any other object files by using an explicit 23729instantiation declaration, using the @code{extern template} syntax: 23730 23731@smallexample 23732extern template int max (int, int); 23733@end smallexample 23734 23735This syntax is defined in the C++ 2011 standard, but has been supported by 23736G++ and other compilers since well before 2011. 23737 23738Explicit instantiations can be used for the largest or most frequently 23739duplicated instances, without having to know exactly which other instances 23740are used in the rest of the program. You can scatter the explicit 23741instantiations throughout your program, perhaps putting them in the 23742translation units where the instances are used or the translation units 23743that define the templates themselves; you can put all of the explicit 23744instantiations you need into one big file; or you can create small files 23745like 23746 23747@smallexample 23748#include "Foo.h" 23749#include "Foo.cc" 23750 23751template class Foo<int>; 23752template ostream& operator << 23753 (ostream&, const Foo<int>&); 23754@end smallexample 23755 23756@noindent 23757for each of the instances you need, and create a template instantiation 23758library from those. 23759 23760This is the simplest option, but also offers flexibility and 23761fine-grained control when necessary. It is also the most portable 23762alternative and programs using this approach will work with most modern 23763compilers. 23764 23765@item 23766@opindex frepo 23767Compile your template-using code with @option{-frepo}. The compiler 23768generates files with the extension @samp{.rpo} listing all of the 23769template instantiations used in the corresponding object files that 23770could be instantiated there; the link wrapper, @samp{collect2}, 23771then updates the @samp{.rpo} files to tell the compiler where to place 23772those instantiations and rebuild any affected object files. The 23773link-time overhead is negligible after the first pass, as the compiler 23774continues to place the instantiations in the same files. 23775 23776This can be a suitable option for application code written for the Borland 23777model, as it usually just works. Code written for the Cfront model 23778needs to be modified so that the template definitions are available at 23779one or more points of instantiation; usually this is as simple as adding 23780@code{#include <tmethods.cc>} to the end of each template header. 23781 23782For library code, if you want the library to provide all of the template 23783instantiations it needs, just try to link all of its object files 23784together; the link will fail, but cause the instantiations to be 23785generated as a side effect. Be warned, however, that this may cause 23786conflicts if multiple libraries try to provide the same instantiations. 23787For greater control, use explicit instantiation as described in the next 23788option. 23789 23790@item 23791@opindex fno-implicit-templates 23792Compile your code with @option{-fno-implicit-templates} to disable the 23793implicit generation of template instances, and explicitly instantiate 23794all the ones you use. This approach requires more knowledge of exactly 23795which instances you need than do the others, but it's less 23796mysterious and allows greater control if you want to ensure that only 23797the intended instances are used. 23798 23799If you are using Cfront-model code, you can probably get away with not 23800using @option{-fno-implicit-templates} when compiling files that don't 23801@samp{#include} the member template definitions. 23802 23803If you use one big file to do the instantiations, you may want to 23804compile it without @option{-fno-implicit-templates} so you get all of the 23805instances required by your explicit instantiations (but not by any 23806other files) without having to specify them as well. 23807 23808In addition to forward declaration of explicit instantiations 23809(with @code{extern}), G++ has extended the template instantiation 23810syntax to support instantiation of the compiler support data for a 23811template class (i.e.@: the vtable) without instantiating any of its 23812members (with @code{inline}), and instantiation of only the static data 23813members of a template class, without the support data or member 23814functions (with @code{static}): 23815 23816@smallexample 23817inline template class Foo<int>; 23818static template class Foo<int>; 23819@end smallexample 23820@end enumerate 23821 23822@node Bound member functions 23823@section Extracting the Function Pointer from a Bound Pointer to Member Function 23824@cindex pmf 23825@cindex pointer to member function 23826@cindex bound pointer to member function 23827 23828In C++, pointer to member functions (PMFs) are implemented using a wide 23829pointer of sorts to handle all the possible call mechanisms; the PMF 23830needs to store information about how to adjust the @samp{this} pointer, 23831and if the function pointed to is virtual, where to find the vtable, and 23832where in the vtable to look for the member function. If you are using 23833PMFs in an inner loop, you should really reconsider that decision. If 23834that is not an option, you can extract the pointer to the function that 23835would be called for a given object/PMF pair and call it directly inside 23836the inner loop, to save a bit of time. 23837 23838Note that you still pay the penalty for the call through a 23839function pointer; on most modern architectures, such a call defeats the 23840branch prediction features of the CPU@. This is also true of normal 23841virtual function calls. 23842 23843The syntax for this extension is 23844 23845@smallexample 23846extern A a; 23847extern int (A::*fp)(); 23848typedef int (*fptr)(A *); 23849 23850fptr p = (fptr)(a.*fp); 23851@end smallexample 23852 23853For PMF constants (i.e.@: expressions of the form @samp{&Klasse::Member}), 23854no object is needed to obtain the address of the function. They can be 23855converted to function pointers directly: 23856 23857@smallexample 23858fptr p1 = (fptr)(&A::foo); 23859@end smallexample 23860 23861@opindex Wno-pmf-conversions 23862You must specify @option{-Wno-pmf-conversions} to use this extension. 23863 23864@node C++ Attributes 23865@section C++-Specific Variable, Function, and Type Attributes 23866 23867Some attributes only make sense for C++ programs. 23868 23869@table @code 23870@item abi_tag ("@var{tag}", ...) 23871@cindex @code{abi_tag} function attribute 23872@cindex @code{abi_tag} variable attribute 23873@cindex @code{abi_tag} type attribute 23874The @code{abi_tag} attribute can be applied to a function, variable, or class 23875declaration. It modifies the mangled name of the entity to 23876incorporate the tag name, in order to distinguish the function or 23877class from an earlier version with a different ABI; perhaps the class 23878has changed size, or the function has a different return type that is 23879not encoded in the mangled name. 23880 23881The attribute can also be applied to an inline namespace, but does not 23882affect the mangled name of the namespace; in this case it is only used 23883for @option{-Wabi-tag} warnings and automatic tagging of functions and 23884variables. Tagging inline namespaces is generally preferable to 23885tagging individual declarations, but the latter is sometimes 23886necessary, such as when only certain members of a class need to be 23887tagged. 23888 23889The argument can be a list of strings of arbitrary length. The 23890strings are sorted on output, so the order of the list is 23891unimportant. 23892 23893A redeclaration of an entity must not add new ABI tags, 23894since doing so would change the mangled name. 23895 23896The ABI tags apply to a name, so all instantiations and 23897specializations of a template have the same tags. The attribute will 23898be ignored if applied to an explicit specialization or instantiation. 23899 23900The @option{-Wabi-tag} flag enables a warning about a class which does 23901not have all the ABI tags used by its subobjects and virtual functions; for users with code 23902that needs to coexist with an earlier ABI, using this option can help 23903to find all affected types that need to be tagged. 23904 23905When a type involving an ABI tag is used as the type of a variable or 23906return type of a function where that tag is not already present in the 23907signature of the function, the tag is automatically applied to the 23908variable or function. @option{-Wabi-tag} also warns about this 23909situation; this warning can be avoided by explicitly tagging the 23910variable or function or moving it into a tagged inline namespace. 23911 23912@item init_priority (@var{priority}) 23913@cindex @code{init_priority} variable attribute 23914 23915In Standard C++, objects defined at namespace scope are guaranteed to be 23916initialized in an order in strict accordance with that of their definitions 23917@emph{in a given translation unit}. No guarantee is made for initializations 23918across translation units. However, GNU C++ allows users to control the 23919order of initialization of objects defined at namespace scope with the 23920@code{init_priority} attribute by specifying a relative @var{priority}, 23921a constant integral expression currently bounded between 101 and 65535 23922inclusive. Lower numbers indicate a higher priority. 23923 23924In the following example, @code{A} would normally be created before 23925@code{B}, but the @code{init_priority} attribute reverses that order: 23926 23927@smallexample 23928Some_Class A __attribute__ ((init_priority (2000))); 23929Some_Class B __attribute__ ((init_priority (543))); 23930@end smallexample 23931 23932@noindent 23933Note that the particular values of @var{priority} do not matter; only their 23934relative ordering. 23935 23936@item warn_unused 23937@cindex @code{warn_unused} type attribute 23938 23939For C++ types with non-trivial constructors and/or destructors it is 23940impossible for the compiler to determine whether a variable of this 23941type is truly unused if it is not referenced. This type attribute 23942informs the compiler that variables of this type should be warned 23943about if they appear to be unused, just like variables of fundamental 23944types. 23945 23946This attribute is appropriate for types which just represent a value, 23947such as @code{std::string}; it is not appropriate for types which 23948control a resource, such as @code{std::lock_guard}. 23949 23950This attribute is also accepted in C, but it is unnecessary because C 23951does not have constructors or destructors. 23952 23953@end table 23954 23955@node Function Multiversioning 23956@section Function Multiversioning 23957@cindex function versions 23958 23959With the GNU C++ front end, for x86 targets, you may specify multiple 23960versions of a function, where each function is specialized for a 23961specific target feature. At runtime, the appropriate version of the 23962function is automatically executed depending on the characteristics of 23963the execution platform. Here is an example. 23964 23965@smallexample 23966__attribute__ ((target ("default"))) 23967int foo () 23968@{ 23969 // The default version of foo. 23970 return 0; 23971@} 23972 23973__attribute__ ((target ("sse4.2"))) 23974int foo () 23975@{ 23976 // foo version for SSE4.2 23977 return 1; 23978@} 23979 23980__attribute__ ((target ("arch=atom"))) 23981int foo () 23982@{ 23983 // foo version for the Intel ATOM processor 23984 return 2; 23985@} 23986 23987__attribute__ ((target ("arch=amdfam10"))) 23988int foo () 23989@{ 23990 // foo version for the AMD Family 0x10 processors. 23991 return 3; 23992@} 23993 23994int main () 23995@{ 23996 int (*p)() = &foo; 23997 assert ((*p) () == foo ()); 23998 return 0; 23999@} 24000@end smallexample 24001 24002In the above example, four versions of function foo are created. The 24003first version of foo with the target attribute "default" is the default 24004version. This version gets executed when no other target specific 24005version qualifies for execution on a particular platform. A new version 24006of foo is created by using the same function signature but with a 24007different target string. Function foo is called or a pointer to it is 24008taken just like a regular function. GCC takes care of doing the 24009dispatching to call the right version at runtime. Refer to the 24010@uref{http://gcc.gnu.org/wiki/FunctionMultiVersioning, GCC wiki on 24011Function Multiversioning} for more details. 24012 24013@node Type Traits 24014@section Type Traits 24015 24016The C++ front end implements syntactic extensions that allow 24017compile-time determination of 24018various characteristics of a type (or of a 24019pair of types). 24020 24021@table @code 24022@item __has_nothrow_assign (type) 24023If @code{type} is const qualified or is a reference type then the trait is 24024false. Otherwise if @code{__has_trivial_assign (type)} is true then the trait 24025is true, else if @code{type} is a cv class or union type with copy assignment 24026operators that are known not to throw an exception then the trait is true, 24027else it is false. Requires: @code{type} shall be a complete type, 24028(possibly cv-qualified) @code{void}, or an array of unknown bound. 24029 24030@item __has_nothrow_copy (type) 24031If @code{__has_trivial_copy (type)} is true then the trait is true, else if 24032@code{type} is a cv class or union type with copy constructors that 24033are known not to throw an exception then the trait is true, else it is false. 24034Requires: @code{type} shall be a complete type, (possibly cv-qualified) 24035@code{void}, or an array of unknown bound. 24036 24037@item __has_nothrow_constructor (type) 24038If @code{__has_trivial_constructor (type)} is true then the trait is 24039true, else if @code{type} is a cv class or union type (or array 24040thereof) with a default constructor that is known not to throw an 24041exception then the trait is true, else it is false. Requires: 24042@code{type} shall be a complete type, (possibly cv-qualified) 24043@code{void}, or an array of unknown bound. 24044 24045@item __has_trivial_assign (type) 24046If @code{type} is const qualified or is a reference type then the trait is 24047false. Otherwise if @code{__is_pod (type)} is true then the trait is 24048true, else if @code{type} is a cv class or union type with a trivial 24049copy assignment ([class.copy]) then the trait is true, else it is 24050false. Requires: @code{type} shall be a complete type, (possibly 24051cv-qualified) @code{void}, or an array of unknown bound. 24052 24053@item __has_trivial_copy (type) 24054If @code{__is_pod (type)} is true or @code{type} is a reference type 24055then the trait is true, else if @code{type} is a cv class or union type 24056with a trivial copy constructor ([class.copy]) then the trait 24057is true, else it is false. Requires: @code{type} shall be a complete 24058type, (possibly cv-qualified) @code{void}, or an array of unknown bound. 24059 24060@item __has_trivial_constructor (type) 24061If @code{__is_pod (type)} is true then the trait is true, else if 24062@code{type} is a cv class or union type (or array thereof) with a 24063trivial default constructor ([class.ctor]) then the trait is true, 24064else it is false. Requires: @code{type} shall be a complete 24065type, (possibly cv-qualified) @code{void}, or an array of unknown bound. 24066 24067@item __has_trivial_destructor (type) 24068If @code{__is_pod (type)} is true or @code{type} is a reference type then 24069the trait is true, else if @code{type} is a cv class or union type (or 24070array thereof) with a trivial destructor ([class.dtor]) then the trait 24071is true, else it is false. Requires: @code{type} shall be a complete 24072type, (possibly cv-qualified) @code{void}, or an array of unknown bound. 24073 24074@item __has_virtual_destructor (type) 24075If @code{type} is a class type with a virtual destructor 24076([class.dtor]) then the trait is true, else it is false. Requires: 24077@code{type} shall be a complete type, (possibly cv-qualified) 24078@code{void}, or an array of unknown bound. 24079 24080@item __is_abstract (type) 24081If @code{type} is an abstract class ([class.abstract]) then the trait 24082is true, else it is false. Requires: @code{type} shall be a complete 24083type, (possibly cv-qualified) @code{void}, or an array of unknown bound. 24084 24085@item __is_base_of (base_type, derived_type) 24086If @code{base_type} is a base class of @code{derived_type} 24087([class.derived]) then the trait is true, otherwise it is false. 24088Top-level cv qualifications of @code{base_type} and 24089@code{derived_type} are ignored. For the purposes of this trait, a 24090class type is considered is own base. Requires: if @code{__is_class 24091(base_type)} and @code{__is_class (derived_type)} are true and 24092@code{base_type} and @code{derived_type} are not the same type 24093(disregarding cv-qualifiers), @code{derived_type} shall be a complete 24094type. A diagnostic is produced if this requirement is not met. 24095 24096@item __is_class (type) 24097If @code{type} is a cv class type, and not a union type 24098([basic.compound]) the trait is true, else it is false. 24099 24100@item __is_empty (type) 24101If @code{__is_class (type)} is false then the trait is false. 24102Otherwise @code{type} is considered empty if and only if: @code{type} 24103has no non-static data members, or all non-static data members, if 24104any, are bit-fields of length 0, and @code{type} has no virtual 24105members, and @code{type} has no virtual base classes, and @code{type} 24106has no base classes @code{base_type} for which 24107@code{__is_empty (base_type)} is false. Requires: @code{type} shall 24108be a complete type, (possibly cv-qualified) @code{void}, or an array 24109of unknown bound. 24110 24111@item __is_enum (type) 24112If @code{type} is a cv enumeration type ([basic.compound]) the trait is 24113true, else it is false. 24114 24115@item __is_literal_type (type) 24116If @code{type} is a literal type ([basic.types]) the trait is 24117true, else it is false. Requires: @code{type} shall be a complete type, 24118(possibly cv-qualified) @code{void}, or an array of unknown bound. 24119 24120@item __is_pod (type) 24121If @code{type} is a cv POD type ([basic.types]) then the trait is true, 24122else it is false. Requires: @code{type} shall be a complete type, 24123(possibly cv-qualified) @code{void}, or an array of unknown bound. 24124 24125@item __is_polymorphic (type) 24126If @code{type} is a polymorphic class ([class.virtual]) then the trait 24127is true, else it is false. Requires: @code{type} shall be a complete 24128type, (possibly cv-qualified) @code{void}, or an array of unknown bound. 24129 24130@item __is_standard_layout (type) 24131If @code{type} is a standard-layout type ([basic.types]) the trait is 24132true, else it is false. Requires: @code{type} shall be a complete 24133type, (possibly cv-qualified) @code{void}, or an array of unknown bound. 24134 24135@item __is_trivial (type) 24136If @code{type} is a trivial type ([basic.types]) the trait is 24137true, else it is false. Requires: @code{type} shall be a complete 24138type, (possibly cv-qualified) @code{void}, or an array of unknown bound. 24139 24140@item __is_union (type) 24141If @code{type} is a cv union type ([basic.compound]) the trait is 24142true, else it is false. 24143 24144@item __underlying_type (type) 24145The underlying type of @code{type}. Requires: @code{type} shall be 24146an enumeration type ([dcl.enum]). 24147 24148@item __integer_pack (length) 24149When used as the pattern of a pack expansion within a template 24150definition, expands to a template argument pack containing integers 24151from @code{0} to @code{length-1}. This is provided for efficient 24152implementation of @code{std::make_integer_sequence}. 24153 24154@end table 24155 24156 24157@node C++ Concepts 24158@section C++ Concepts 24159 24160C++ concepts provide much-improved support for generic programming. In 24161particular, they allow the specification of constraints on template arguments. 24162The constraints are used to extend the usual overloading and partial 24163specialization capabilities of the language, allowing generic data structures 24164and algorithms to be ``refined'' based on their properties rather than their 24165type names. 24166 24167The following keywords are reserved for concepts. 24168 24169@table @code 24170@item assumes 24171States an expression as an assumption, and if possible, verifies that the 24172assumption is valid. For example, @code{assume(n > 0)}. 24173 24174@item axiom 24175Introduces an axiom definition. Axioms introduce requirements on values. 24176 24177@item forall 24178Introduces a universally quantified object in an axiom. For example, 24179@code{forall (int n) n + 0 == n}). 24180 24181@item concept 24182Introduces a concept definition. Concepts are sets of syntactic and semantic 24183requirements on types and their values. 24184 24185@item requires 24186Introduces constraints on template arguments or requirements for a member 24187function of a class template. 24188 24189@end table 24190 24191The front end also exposes a number of internal mechanism that can be used 24192to simplify the writing of type traits. Note that some of these traits are 24193likely to be removed in the future. 24194 24195@table @code 24196@item __is_same (type1, type2) 24197A binary type trait: true whenever the type arguments are the same. 24198 24199@end table 24200 24201 24202@node Deprecated Features 24203@section Deprecated Features 24204 24205In the past, the GNU C++ compiler was extended to experiment with new 24206features, at a time when the C++ language was still evolving. Now that 24207the C++ standard is complete, some of those features are superseded by 24208superior alternatives. Using the old features might cause a warning in 24209some cases that the feature will be dropped in the future. In other 24210cases, the feature might be gone already. 24211 24212While the list below is not exhaustive, it documents some of the options 24213that are now deprecated or have been removed: 24214 24215@table @code 24216 24217@item -fno-for-scope 24218@itemx -ffriend-injection 24219These two options provide compatibility with pre-standard C++. 24220@xref{Backwards Compatibility}. 24221 24222@end table 24223 24224G++ allows a virtual function returning @samp{void *} to be overridden 24225by one returning a different pointer type. This extension to the 24226covariant return type rules is now deprecated and will be removed from a 24227future version. 24228 24229The use of default arguments in function pointers, function typedefs 24230and other places where they are not permitted by the standard is 24231deprecated and will be removed from a future version of G++. 24232 24233G++ allows floating-point literals to appear in integral constant expressions, 24234e.g.@: @samp{ enum E @{ e = int(2.2 * 3.7) @} } 24235This extension is deprecated and will be removed from a future version. 24236 24237G++ allows static data members of const floating-point type to be declared 24238with an initializer in a class definition. The standard only allows 24239initializers for static members of const integral types and const 24240enumeration types so this extension has been deprecated and will be removed 24241from a future version. 24242 24243G++ allows attributes to follow a parenthesized direct initializer, 24244e.g.@: @samp{ int f (0) __attribute__ ((something)); } This extension 24245has been ignored since G++ 3.3 and is deprecated. 24246 24247G++ allows anonymous structs and unions to have members that are not 24248public non-static data members (i.e.@: fields). These extensions are 24249deprecated. 24250 24251@node Backwards Compatibility 24252@section Backwards Compatibility 24253@cindex Backwards Compatibility 24254@cindex ARM [Annotated C++ Reference Manual] 24255 24256Now that there is a definitive ISO standard C++, G++ has a specification 24257to adhere to. The C++ language evolved over time, and features that 24258used to be acceptable in previous drafts of the standard, such as the ARM 24259[Annotated C++ Reference Manual], are no longer accepted. In order to allow 24260compilation of C++ written to such drafts, G++ contains some backwards 24261compatibilities. @emph{All such backwards compatibility features are 24262liable to disappear in future versions of G++.} They should be considered 24263deprecated. @xref{Deprecated Features}. 24264 24265@table @code 24266@item For scope 24267If a variable is declared at for scope, it used to remain in scope 24268until the end of the scope that contained the for statement (rather 24269than just within the for scope). The deprecated 24270@option{-fno-for-scope} option enables this non-standard behavior. 24271Without the option, G++ retains this, but issues a warning, if such a 24272variable is accessed outside the for scope. 24273 24274The behavior is deprecated, only available with @option{-std=c++98} 24275@option{-std=gnu++98} languages and you must use the 24276@option{-fpermissive} option to enable it. The behavior will be 24277removed. 24278 24279@item Friend Injection 24280The @option{-ffriend-injection} option makes injected friends visible 24281to regular name lookup, unlike standard C++. This option is 24282deprecated and will be removed. 24283 24284@item Implicit C language 24285Old C system header files did not contain an @code{extern "C" @{@dots{}@}} 24286scope to set the language. On such systems, all header files are 24287implicitly scoped inside a C language scope. Also, an empty prototype 24288@code{()} is treated as an unspecified number of arguments, rather 24289than no arguments, as C++ demands. 24290@end table 24291 24292@c LocalWords: emph deftypefn builtin ARCv2EM SIMD builtins msimd 24293@c LocalWords: typedef v4si v8hi DMA dma vdiwr vdowr 24294