1@c Copyright (C) 1988-2015 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* Label Attributes:: Specifying attributes on labels. 60* Attribute Syntax:: Formal syntax for attributes. 61* Function Prototypes:: Prototype declarations and old-style definitions. 62* C++ Comments:: C++ comments are recognized. 63* Dollar Signs:: Dollar sign is allowed in identifiers. 64* Character Escapes:: @samp{\e} stands for the character @key{ESC}. 65* Variable Attributes:: Specifying attributes of variables. 66* Type Attributes:: Specifying attributes of types. 67* Alignment:: Inquiring about the alignment of a type or variable. 68* Inline:: Defining inline functions (as fast as macros). 69* Volatiles:: What constitutes an access to a volatile object. 70* Using Assembly Language with C:: Instructions and extensions for interfacing C with assembler. 71* Alternate Keywords:: @code{__const__}, @code{__asm__}, etc., for header files. 72* Incomplete Enums:: @code{enum foo;}, with details to follow. 73* Function Names:: Printable strings which are the name of the current 74 function. 75* Return Address:: Getting the return or frame address of a function. 76* Vector Extensions:: Using vector instructions through built-in functions. 77* Offsetof:: Special syntax for implementing @code{offsetof}. 78* __sync Builtins:: Legacy built-in functions for atomic memory access. 79* __atomic Builtins:: Atomic built-in functions with memory model. 80* Integer Overflow Builtins:: Built-in functions to perform arithmetics and 81 arithmetic overflow checking. 82* x86 specific memory model extensions for transactional memory:: x86 memory models. 83* Object Size Checking:: Built-in functions for limited buffer overflow 84 checking. 85* Pointer Bounds Checker builtins:: Built-in functions for Pointer Bounds Checker. 86* Cilk Plus Builtins:: Built-in functions for the Cilk Plus language extension. 87* Other Builtins:: Other built-in functions. 88* Target Builtins:: Built-in functions specific to particular targets. 89* Target Format Checks:: Format checks specific to particular targets. 90* Pragmas:: Pragmas accepted by GCC. 91* Unnamed Fields:: Unnamed struct/union fields within structs/unions. 92* Thread-Local:: Per-thread variables. 93* Binary constants:: Binary constants using the @samp{0b} prefix. 94@end menu 95 96@node Statement Exprs 97@section Statements and Declarations in Expressions 98@cindex statements inside expressions 99@cindex declarations inside expressions 100@cindex expressions containing statements 101@cindex macros, statements in expressions 102 103@c the above section title wrapped and causes an underfull hbox.. i 104@c changed it from "within" to "in". --mew 4feb93 105A compound statement enclosed in parentheses may appear as an expression 106in GNU C@. This allows you to use loops, switches, and local variables 107within an expression. 108 109Recall that a compound statement is a sequence of statements surrounded 110by braces; in this construct, parentheses go around the braces. For 111example: 112 113@smallexample 114(@{ int y = foo (); int z; 115 if (y > 0) z = y; 116 else z = - y; 117 z; @}) 118@end smallexample 119 120@noindent 121is a valid (though slightly more complex than necessary) expression 122for the absolute value of @code{foo ()}. 123 124The last thing in the compound statement should be an expression 125followed by a semicolon; the value of this subexpression serves as the 126value of the entire construct. (If you use some other kind of statement 127last within the braces, the construct has type @code{void}, and thus 128effectively no value.) 129 130This feature is especially useful in making macro definitions ``safe'' (so 131that they evaluate each operand exactly once). For example, the 132``maximum'' function is commonly defined as a macro in standard C as 133follows: 134 135@smallexample 136#define max(a,b) ((a) > (b) ? (a) : (b)) 137@end smallexample 138 139@noindent 140@cindex side effects, macro argument 141But this definition computes either @var{a} or @var{b} twice, with bad 142results if the operand has side effects. In GNU C, if you know the 143type of the operands (here taken as @code{int}), you can define 144the macro safely as follows: 145 146@smallexample 147#define maxint(a,b) \ 148 (@{int _a = (a), _b = (b); _a > _b ? _a : _b; @}) 149@end smallexample 150 151Embedded statements are not allowed in constant expressions, such as 152the value of an enumeration constant, the width of a bit-field, or 153the initial value of a static variable. 154 155If you don't know the type of the operand, you can still do this, but you 156must use @code{typeof} or @code{__auto_type} (@pxref{Typeof}). 157 158In G++, the result value of a statement expression undergoes array and 159function pointer decay, and is returned by value to the enclosing 160expression. For instance, if @code{A} is a class, then 161 162@smallexample 163 A a; 164 165 (@{a;@}).Foo () 166@end smallexample 167 168@noindent 169constructs a temporary @code{A} object to hold the result of the 170statement expression, and that is used to invoke @code{Foo}. 171Therefore the @code{this} pointer observed by @code{Foo} is not the 172address of @code{a}. 173 174In a statement expression, any temporaries created within a statement 175are destroyed at that statement's end. This makes statement 176expressions inside macros slightly different from function calls. In 177the latter case temporaries introduced during argument evaluation are 178destroyed at the end of the statement that includes the function 179call. In the statement expression case they are destroyed during 180the statement expression. For instance, 181 182@smallexample 183#define macro(a) (@{__typeof__(a) b = (a); b + 3; @}) 184template<typename T> T function(T a) @{ T b = a; return b + 3; @} 185 186void foo () 187@{ 188 macro (X ()); 189 function (X ()); 190@} 191@end smallexample 192 193@noindent 194has different places where temporaries are destroyed. For the 195@code{macro} case, the temporary @code{X} is destroyed just after 196the initialization of @code{b}. In the @code{function} case that 197temporary is destroyed when the function returns. 198 199These considerations mean that it is probably a bad idea to use 200statement expressions of this form in header files that are designed to 201work with C++. (Note that some versions of the GNU C Library contained 202header files using statement expressions that lead to precisely this 203bug.) 204 205Jumping into a statement expression with @code{goto} or using a 206@code{switch} statement outside the statement expression with a 207@code{case} or @code{default} label inside the statement expression is 208not permitted. Jumping into a statement expression with a computed 209@code{goto} (@pxref{Labels as Values}) has undefined behavior. 210Jumping out of a statement expression is permitted, but if the 211statement expression is part of a larger expression then it is 212unspecified which other subexpressions of that expression have been 213evaluated except where the language definition requires certain 214subexpressions to be evaluated before or after the statement 215expression. In any case, as with a function call, the evaluation of a 216statement expression is not interleaved with the evaluation of other 217parts of the containing expression. For example, 218 219@smallexample 220 foo (), ((@{ bar1 (); goto a; 0; @}) + bar2 ()), baz(); 221@end smallexample 222 223@noindent 224calls @code{foo} and @code{bar1} and does not call @code{baz} but 225may or may not call @code{bar2}. If @code{bar2} is called, it is 226called after @code{foo} and before @code{bar1}. 227 228@node Local Labels 229@section Locally Declared Labels 230@cindex local labels 231@cindex macros, local labels 232 233GCC allows you to declare @dfn{local labels} in any nested block 234scope. A local label is just like an ordinary label, but you can 235only reference it (with a @code{goto} statement, or by taking its 236address) within the block in which it is declared. 237 238A local label declaration looks like this: 239 240@smallexample 241__label__ @var{label}; 242@end smallexample 243 244@noindent 245or 246 247@smallexample 248__label__ @var{label1}, @var{label2}, /* @r{@dots{}} */; 249@end smallexample 250 251Local label declarations must come at the beginning of the block, 252before any ordinary declarations or statements. 253 254The label declaration defines the label @emph{name}, but does not define 255the label itself. You must do this in the usual way, with 256@code{@var{label}:}, within the statements of the statement expression. 257 258The local label feature is useful for complex macros. If a macro 259contains nested loops, a @code{goto} can be useful for breaking out of 260them. However, an ordinary label whose scope is the whole function 261cannot be used: if the macro can be expanded several times in one 262function, the label is multiply defined in that function. A 263local label avoids this problem. For example: 264 265@smallexample 266#define SEARCH(value, array, target) \ 267do @{ \ 268 __label__ found; \ 269 typeof (target) _SEARCH_target = (target); \ 270 typeof (*(array)) *_SEARCH_array = (array); \ 271 int i, j; \ 272 int value; \ 273 for (i = 0; i < max; i++) \ 274 for (j = 0; j < max; j++) \ 275 if (_SEARCH_array[i][j] == _SEARCH_target) \ 276 @{ (value) = i; goto found; @} \ 277 (value) = -1; \ 278 found:; \ 279@} while (0) 280@end smallexample 281 282This could also be written using a statement expression: 283 284@smallexample 285#define SEARCH(array, target) \ 286(@{ \ 287 __label__ found; \ 288 typeof (target) _SEARCH_target = (target); \ 289 typeof (*(array)) *_SEARCH_array = (array); \ 290 int i, j; \ 291 int value; \ 292 for (i = 0; i < max; i++) \ 293 for (j = 0; j < max; j++) \ 294 if (_SEARCH_array[i][j] == _SEARCH_target) \ 295 @{ value = i; goto found; @} \ 296 value = -1; \ 297 found: \ 298 value; \ 299@}) 300@end smallexample 301 302Local label declarations also make the labels they declare visible to 303nested functions, if there are any. @xref{Nested Functions}, for details. 304 305@node Labels as Values 306@section Labels as Values 307@cindex labels as values 308@cindex computed gotos 309@cindex goto with computed label 310@cindex address of a label 311 312You can get the address of a label defined in the current function 313(or a containing function) with the unary operator @samp{&&}. The 314value has type @code{void *}. This value is a constant and can be used 315wherever a constant of that type is valid. For example: 316 317@smallexample 318void *ptr; 319/* @r{@dots{}} */ 320ptr = &&foo; 321@end smallexample 322 323To use these values, you need to be able to jump to one. This is done 324with the computed goto statement@footnote{The analogous feature in 325Fortran is called an assigned goto, but that name seems inappropriate in 326C, where one can do more than simply store label addresses in label 327variables.}, @code{goto *@var{exp};}. For example, 328 329@smallexample 330goto *ptr; 331@end smallexample 332 333@noindent 334Any expression of type @code{void *} is allowed. 335 336One way of using these constants is in initializing a static array that 337serves as a jump table: 338 339@smallexample 340static void *array[] = @{ &&foo, &&bar, &&hack @}; 341@end smallexample 342 343@noindent 344Then you can select a label with indexing, like this: 345 346@smallexample 347goto *array[i]; 348@end smallexample 349 350@noindent 351Note that this does not check whether the subscript is in bounds---array 352indexing in C never does that. 353 354Such an array of label values serves a purpose much like that of the 355@code{switch} statement. The @code{switch} statement is cleaner, so 356use that rather than an array unless the problem does not fit a 357@code{switch} statement very well. 358 359Another use of label values is in an interpreter for threaded code. 360The labels within the interpreter function can be stored in the 361threaded code for super-fast dispatching. 362 363You may not use this mechanism to jump to code in a different function. 364If you do that, totally unpredictable things happen. The best way to 365avoid this is to store the label address only in automatic variables and 366never pass it as an argument. 367 368An alternate way to write the above example is 369 370@smallexample 371static const int array[] = @{ &&foo - &&foo, &&bar - &&foo, 372 &&hack - &&foo @}; 373goto *(&&foo + array[i]); 374@end smallexample 375 376@noindent 377This is more friendly to code living in shared libraries, as it reduces 378the number of dynamic relocations that are needed, and by consequence, 379allows the data to be read-only. 380This alternative with label differences is not supported for the AVR target, 381please use the first approach for AVR programs. 382 383The @code{&&foo} expressions for the same label might have different 384values if the containing function is inlined or cloned. If a program 385relies on them being always the same, 386@code{__attribute__((__noinline__,__noclone__))} should be used to 387prevent inlining and cloning. If @code{&&foo} is used in a static 388variable initializer, inlining and cloning is forbidden. 389 390@node Nested Functions 391@section Nested Functions 392@cindex nested functions 393@cindex downward funargs 394@cindex thunks 395 396A @dfn{nested function} is a function defined inside another function. 397Nested functions are supported as an extension in GNU C, but are not 398supported by GNU C++. 399 400The nested function's name is local to the block where it is defined. 401For example, here we define a nested function named @code{square}, and 402call it twice: 403 404@smallexample 405@group 406foo (double a, double b) 407@{ 408 double square (double z) @{ return z * z; @} 409 410 return square (a) + square (b); 411@} 412@end group 413@end smallexample 414 415The nested function can access all the variables of the containing 416function that are visible at the point of its definition. This is 417called @dfn{lexical scoping}. For example, here we show a nested 418function which uses an inherited variable named @code{offset}: 419 420@smallexample 421@group 422bar (int *array, int offset, int size) 423@{ 424 int access (int *array, int index) 425 @{ return array[index + offset]; @} 426 int i; 427 /* @r{@dots{}} */ 428 for (i = 0; i < size; i++) 429 /* @r{@dots{}} */ access (array, i) /* @r{@dots{}} */ 430@} 431@end group 432@end smallexample 433 434Nested function definitions are permitted within functions in the places 435where variable definitions are allowed; that is, in any block, mixed 436with the other declarations and statements in the block. 437 438It is possible to call the nested function from outside the scope of its 439name by storing its address or passing the address to another function: 440 441@smallexample 442hack (int *array, int size) 443@{ 444 void store (int index, int value) 445 @{ array[index] = value; @} 446 447 intermediate (store, size); 448@} 449@end smallexample 450 451Here, the function @code{intermediate} receives the address of 452@code{store} as an argument. If @code{intermediate} calls @code{store}, 453the arguments given to @code{store} are used to store into @code{array}. 454But this technique works only so long as the containing function 455(@code{hack}, in this example) does not exit. 456 457If you try to call the nested function through its address after the 458containing function exits, all hell breaks loose. If you try 459to call it after a containing scope level exits, and if it refers 460to some of the variables that are no longer in scope, you may be lucky, 461but it's not wise to take the risk. If, however, the nested function 462does not refer to anything that has gone out of scope, you should be 463safe. 464 465GCC implements taking the address of a nested function using a technique 466called @dfn{trampolines}. This technique was described in 467@cite{Lexical Closures for C++} (Thomas M. Breuel, USENIX 468C++ Conference Proceedings, October 17-21, 1988). 469 470A nested function can jump to a label inherited from a containing 471function, provided the label is explicitly declared in the containing 472function (@pxref{Local Labels}). Such a jump returns instantly to the 473containing function, exiting the nested function that did the 474@code{goto} and any intermediate functions as well. Here is an example: 475 476@smallexample 477@group 478bar (int *array, int offset, int size) 479@{ 480 __label__ failure; 481 int access (int *array, int index) 482 @{ 483 if (index > size) 484 goto failure; 485 return array[index + offset]; 486 @} 487 int i; 488 /* @r{@dots{}} */ 489 for (i = 0; i < size; i++) 490 /* @r{@dots{}} */ access (array, i) /* @r{@dots{}} */ 491 /* @r{@dots{}} */ 492 return 0; 493 494 /* @r{Control comes here from @code{access} 495 if it detects an error.} */ 496 failure: 497 return -1; 498@} 499@end group 500@end smallexample 501 502A nested function always has no linkage. Declaring one with 503@code{extern} or @code{static} is erroneous. If you need to declare the nested function 504before its definition, use @code{auto} (which is otherwise meaningless 505for function declarations). 506 507@smallexample 508bar (int *array, int offset, int size) 509@{ 510 __label__ failure; 511 auto int access (int *, int); 512 /* @r{@dots{}} */ 513 int access (int *array, int index) 514 @{ 515 if (index > size) 516 goto failure; 517 return array[index + offset]; 518 @} 519 /* @r{@dots{}} */ 520@} 521@end smallexample 522 523@node Constructing Calls 524@section Constructing Function Calls 525@cindex constructing calls 526@cindex forwarding calls 527 528Using the built-in functions described below, you can record 529the arguments a function received, and call another function 530with the same arguments, without knowing the number or types 531of the arguments. 532 533You can also record the return value of that function call, 534and later return that value, without knowing what data type 535the function tried to return (as long as your caller expects 536that data type). 537 538However, these built-in functions may interact badly with some 539sophisticated features or other extensions of the language. It 540is, therefore, not recommended to use them outside very simple 541functions acting as mere forwarders for their arguments. 542 543@deftypefn {Built-in Function} {void *} __builtin_apply_args () 544This built-in function returns a pointer to data 545describing how to perform a call with the same arguments as are passed 546to the current function. 547 548The function saves the arg pointer register, structure value address, 549and all registers that might be used to pass arguments to a function 550into a block of memory allocated on the stack. Then it returns the 551address of that block. 552@end deftypefn 553 554@deftypefn {Built-in Function} {void *} __builtin_apply (void (*@var{function})(), void *@var{arguments}, size_t @var{size}) 555This built-in function invokes @var{function} 556with a copy of the parameters described by @var{arguments} 557and @var{size}. 558 559The value of @var{arguments} should be the value returned by 560@code{__builtin_apply_args}. The argument @var{size} specifies the size 561of the stack argument data, in bytes. 562 563This function returns a pointer to data describing 564how to return whatever value is returned by @var{function}. The data 565is saved in a block of memory allocated on the stack. 566 567It is not always simple to compute the proper value for @var{size}. The 568value is used by @code{__builtin_apply} to compute the amount of data 569that should be pushed on the stack and copied from the incoming argument 570area. 571@end deftypefn 572 573@deftypefn {Built-in Function} {void} __builtin_return (void *@var{result}) 574This built-in function returns the value described by @var{result} from 575the containing function. You should specify, for @var{result}, a value 576returned by @code{__builtin_apply}. 577@end deftypefn 578 579@deftypefn {Built-in Function} {} __builtin_va_arg_pack () 580This built-in function represents all anonymous arguments of an inline 581function. It can be used only in inline functions that are always 582inlined, never compiled as a separate function, such as those using 583@code{__attribute__ ((__always_inline__))} or 584@code{__attribute__ ((__gnu_inline__))} extern inline functions. 585It must be only passed as last argument to some other function 586with variable arguments. This is useful for writing small wrapper 587inlines for variable argument functions, when using preprocessor 588macros is undesirable. For example: 589@smallexample 590extern int myprintf (FILE *f, const char *format, ...); 591extern inline __attribute__ ((__gnu_inline__)) int 592myprintf (FILE *f, const char *format, ...) 593@{ 594 int r = fprintf (f, "myprintf: "); 595 if (r < 0) 596 return r; 597 int s = fprintf (f, format, __builtin_va_arg_pack ()); 598 if (s < 0) 599 return s; 600 return r + s; 601@} 602@end smallexample 603@end deftypefn 604 605@deftypefn {Built-in Function} {size_t} __builtin_va_arg_pack_len () 606This built-in function returns the number of anonymous arguments of 607an inline function. It can be used only in inline functions that 608are always inlined, never compiled as a separate function, such 609as those using @code{__attribute__ ((__always_inline__))} or 610@code{__attribute__ ((__gnu_inline__))} extern inline functions. 611For example following does link- or run-time checking of open 612arguments for optimized code: 613@smallexample 614#ifdef __OPTIMIZE__ 615extern inline __attribute__((__gnu_inline__)) int 616myopen (const char *path, int oflag, ...) 617@{ 618 if (__builtin_va_arg_pack_len () > 1) 619 warn_open_too_many_arguments (); 620 621 if (__builtin_constant_p (oflag)) 622 @{ 623 if ((oflag & O_CREAT) != 0 && __builtin_va_arg_pack_len () < 1) 624 @{ 625 warn_open_missing_mode (); 626 return __open_2 (path, oflag); 627 @} 628 return open (path, oflag, __builtin_va_arg_pack ()); 629 @} 630 631 if (__builtin_va_arg_pack_len () < 1) 632 return __open_2 (path, oflag); 633 634 return open (path, oflag, __builtin_va_arg_pack ()); 635@} 636#endif 637@end smallexample 638@end deftypefn 639 640@node Typeof 641@section Referring to a Type with @code{typeof} 642@findex typeof 643@findex sizeof 644@cindex macros, types of arguments 645 646Another way to refer to the type of an expression is with @code{typeof}. 647The syntax of using of this keyword looks like @code{sizeof}, but the 648construct acts semantically like a type name defined with @code{typedef}. 649 650There are two ways of writing the argument to @code{typeof}: with an 651expression or with a type. Here is an example with an expression: 652 653@smallexample 654typeof (x[0](1)) 655@end smallexample 656 657@noindent 658This assumes that @code{x} is an array of pointers to functions; 659the type described is that of the values of the functions. 660 661Here is an example with a typename as the argument: 662 663@smallexample 664typeof (int *) 665@end smallexample 666 667@noindent 668Here the type described is that of pointers to @code{int}. 669 670If you are writing a header file that must work when included in ISO C 671programs, write @code{__typeof__} instead of @code{typeof}. 672@xref{Alternate Keywords}. 673 674A @code{typeof} construct can be used anywhere a typedef name can be 675used. For example, you can use it in a declaration, in a cast, or inside 676of @code{sizeof} or @code{typeof}. 677 678The operand of @code{typeof} is evaluated for its side effects if and 679only if it is an expression of variably modified type or the name of 680such a type. 681 682@code{typeof} is often useful in conjunction with 683statement expressions (@pxref{Statement Exprs}). 684Here is how the two together can 685be used to define a safe ``maximum'' macro which operates on any 686arithmetic type and evaluates each of its arguments exactly once: 687 688@smallexample 689#define max(a,b) \ 690 (@{ typeof (a) _a = (a); \ 691 typeof (b) _b = (b); \ 692 _a > _b ? _a : _b; @}) 693@end smallexample 694 695@cindex underscores in variables in macros 696@cindex @samp{_} in variables in macros 697@cindex local variables in macros 698@cindex variables, local, in macros 699@cindex macros, local variables in 700 701The reason for using names that start with underscores for the local 702variables is to avoid conflicts with variable names that occur within the 703expressions that are substituted for @code{a} and @code{b}. Eventually we 704hope to design a new form of declaration syntax that allows you to declare 705variables whose scopes start only after their initializers; this will be a 706more reliable way to prevent such conflicts. 707 708@noindent 709Some more examples of the use of @code{typeof}: 710 711@itemize @bullet 712@item 713This declares @code{y} with the type of what @code{x} points to. 714 715@smallexample 716typeof (*x) y; 717@end smallexample 718 719@item 720This declares @code{y} as an array of such values. 721 722@smallexample 723typeof (*x) y[4]; 724@end smallexample 725 726@item 727This declares @code{y} as an array of pointers to characters: 728 729@smallexample 730typeof (typeof (char *)[4]) y; 731@end smallexample 732 733@noindent 734It is equivalent to the following traditional C declaration: 735 736@smallexample 737char *y[4]; 738@end smallexample 739 740To see the meaning of the declaration using @code{typeof}, and why it 741might be a useful way to write, rewrite it with these macros: 742 743@smallexample 744#define pointer(T) typeof(T *) 745#define array(T, N) typeof(T [N]) 746@end smallexample 747 748@noindent 749Now the declaration can be rewritten this way: 750 751@smallexample 752array (pointer (char), 4) y; 753@end smallexample 754 755@noindent 756Thus, @code{array (pointer (char), 4)} is the type of arrays of 4 757pointers to @code{char}. 758@end itemize 759 760In GNU C, but not GNU C++, you may also declare the type of a variable 761as @code{__auto_type}. In that case, the declaration must declare 762only one variable, whose declarator must just be an identifier, the 763declaration must be initialized, and the type of the variable is 764determined by the initializer; the name of the variable is not in 765scope until after the initializer. (In C++, you should use C++11 766@code{auto} for this purpose.) Using @code{__auto_type}, the 767``maximum'' macro above could be written as: 768 769@smallexample 770#define max(a,b) \ 771 (@{ __auto_type _a = (a); \ 772 __auto_type _b = (b); \ 773 _a > _b ? _a : _b; @}) 774@end smallexample 775 776Using @code{__auto_type} instead of @code{typeof} has two advantages: 777 778@itemize @bullet 779@item Each argument to the macro appears only once in the expansion of 780the macro. This prevents the size of the macro expansion growing 781exponentially when calls to such macros are nested inside arguments of 782such macros. 783 784@item If the argument to the macro has variably modified type, it is 785evaluated only once when using @code{__auto_type}, but twice if 786@code{typeof} is used. 787@end itemize 788 789@node Conditionals 790@section Conditionals with Omitted Operands 791@cindex conditional expressions, extensions 792@cindex omitted middle-operands 793@cindex middle-operands, omitted 794@cindex extensions, @code{?:} 795@cindex @code{?:} extensions 796 797The middle operand in a conditional expression may be omitted. Then 798if the first operand is nonzero, its value is the value of the conditional 799expression. 800 801Therefore, the expression 802 803@smallexample 804x ? : y 805@end smallexample 806 807@noindent 808has the value of @code{x} if that is nonzero; otherwise, the value of 809@code{y}. 810 811This example is perfectly equivalent to 812 813@smallexample 814x ? x : y 815@end smallexample 816 817@cindex side effect in @code{?:} 818@cindex @code{?:} side effect 819@noindent 820In this simple case, the ability to omit the middle operand is not 821especially useful. When it becomes useful is when the first operand does, 822or may (if it is a macro argument), contain a side effect. Then repeating 823the operand in the middle would perform the side effect twice. Omitting 824the middle operand uses the value already computed without the undesirable 825effects of recomputing it. 826 827@node __int128 828@section 128-bit Integers 829@cindex @code{__int128} data types 830 831As an extension the integer scalar type @code{__int128} is supported for 832targets which have an integer mode wide enough to hold 128 bits. 833Simply write @code{__int128} for a signed 128-bit integer, or 834@code{unsigned __int128} for an unsigned 128-bit integer. There is no 835support in GCC for expressing an integer constant of type @code{__int128} 836for targets with @code{long long} integer less than 128 bits wide. 837 838@node Long Long 839@section Double-Word Integers 840@cindex @code{long long} data types 841@cindex double-word arithmetic 842@cindex multiprecision arithmetic 843@cindex @code{LL} integer suffix 844@cindex @code{ULL} integer suffix 845 846ISO C99 supports data types for integers that are at least 64 bits wide, 847and as an extension GCC supports them in C90 mode and in C++. 848Simply write @code{long long int} for a signed integer, or 849@code{unsigned long long int} for an unsigned integer. To make an 850integer constant of type @code{long long int}, add the suffix @samp{LL} 851to the integer. To make an integer constant of type @code{unsigned long 852long int}, add the suffix @samp{ULL} to the integer. 853 854You can use these types in arithmetic like any other integer types. 855Addition, subtraction, and bitwise boolean operations on these types 856are open-coded on all types of machines. Multiplication is open-coded 857if the machine supports a fullword-to-doubleword widening multiply 858instruction. Division and shifts are open-coded only on machines that 859provide special support. The operations that are not open-coded use 860special library routines that come with GCC@. 861 862There may be pitfalls when you use @code{long long} types for function 863arguments without function prototypes. If a function 864expects type @code{int} for its argument, and you pass a value of type 865@code{long long int}, confusion results because the caller and the 866subroutine disagree about the number of bytes for the argument. 867Likewise, if the function expects @code{long long int} and you pass 868@code{int}. The best way to avoid such problems is to use prototypes. 869 870@node Complex 871@section Complex Numbers 872@cindex complex numbers 873@cindex @code{_Complex} keyword 874@cindex @code{__complex__} keyword 875 876ISO C99 supports complex floating data types, and as an extension GCC 877supports them in C90 mode and in C++. GCC also supports complex integer data 878types which are not part of ISO C99. You can declare complex types 879using the keyword @code{_Complex}. As an extension, the older GNU 880keyword @code{__complex__} is also supported. 881 882For example, @samp{_Complex double x;} declares @code{x} as a 883variable whose real part and imaginary part are both of type 884@code{double}. @samp{_Complex short int y;} declares @code{y} to 885have real and imaginary parts of type @code{short int}; this is not 886likely to be useful, but it shows that the set of complex types is 887complete. 888 889To write a constant with a complex data type, use the suffix @samp{i} or 890@samp{j} (either one; they are equivalent). For example, @code{2.5fi} 891has type @code{_Complex float} and @code{3i} has type 892@code{_Complex int}. Such a constant always has a pure imaginary 893value, but you can form any complex value you like by adding one to a 894real constant. This is a GNU extension; if you have an ISO C99 895conforming C library (such as the GNU C Library), and want to construct complex 896constants of floating type, you should include @code{<complex.h>} and 897use the macros @code{I} or @code{_Complex_I} instead. 898 899@cindex @code{__real__} keyword 900@cindex @code{__imag__} keyword 901To extract the real part of a complex-valued expression @var{exp}, write 902@code{__real__ @var{exp}}. Likewise, use @code{__imag__} to 903extract the imaginary part. This is a GNU extension; for values of 904floating type, you should use the ISO C99 functions @code{crealf}, 905@code{creal}, @code{creall}, @code{cimagf}, @code{cimag} and 906@code{cimagl}, declared in @code{<complex.h>} and also provided as 907built-in functions by GCC@. 908 909@cindex complex conjugation 910The operator @samp{~} performs complex conjugation when used on a value 911with a complex type. This is a GNU extension; for values of 912floating type, you should use the ISO C99 functions @code{conjf}, 913@code{conj} and @code{conjl}, declared in @code{<complex.h>} and also 914provided as built-in functions by GCC@. 915 916GCC can allocate complex automatic variables in a noncontiguous 917fashion; it's even possible for the real part to be in a register while 918the imaginary part is on the stack (or vice versa). Only the DWARF 2 919debug info format can represent this, so use of DWARF 2 is recommended. 920If you are using the stabs debug info format, GCC describes a noncontiguous 921complex variable as if it were two separate variables of noncomplex type. 922If the variable's actual name is @code{foo}, the two fictitious 923variables are named @code{foo$real} and @code{foo$imag}. You can 924examine and set these two fictitious variables with your debugger. 925 926@node Floating Types 927@section Additional Floating Types 928@cindex additional floating types 929@cindex @code{__float80} data type 930@cindex @code{__float128} data type 931@cindex @code{w} floating point suffix 932@cindex @code{q} floating point suffix 933@cindex @code{W} floating point suffix 934@cindex @code{Q} floating point suffix 935 936As an extension, GNU C supports additional floating 937types, @code{__float80} and @code{__float128} to support 80-bit 938(@code{XFmode}) and 128-bit (@code{TFmode}) floating types. 939Support for additional types includes the arithmetic operators: 940add, subtract, multiply, divide; unary arithmetic operators; 941relational operators; equality operators; and conversions to and from 942integer and other floating types. Use a suffix @samp{w} or @samp{W} 943in a literal constant of type @code{__float80} and @samp{q} or @samp{Q} 944for @code{_float128}. You can declare complex types using the 945corresponding internal complex type, @code{XCmode} for @code{__float80} 946type and @code{TCmode} for @code{__float128} type: 947 948@smallexample 949typedef _Complex float __attribute__((mode(TC))) _Complex128; 950typedef _Complex float __attribute__((mode(XC))) _Complex80; 951@end smallexample 952 953Not all targets support additional floating-point types. @code{__float80} 954and @code{__float128} types are supported on x86 and IA-64 targets. 955The @code{__float128} type is supported on hppa HP-UX targets. 956 957@node Half-Precision 958@section Half-Precision Floating Point 959@cindex half-precision floating point 960@cindex @code{__fp16} data type 961 962On ARM targets, GCC supports half-precision (16-bit) floating point via 963the @code{__fp16} type. You must enable this type explicitly 964with the @option{-mfp16-format} command-line option in order to use it. 965 966ARM supports two incompatible representations for half-precision 967floating-point values. You must choose one of the representations and 968use it consistently in your program. 969 970Specifying @option{-mfp16-format=ieee} selects the IEEE 754-2008 format. 971This format can represent normalized values in the range of @math{2^{-14}} to 65504. 972There are 11 bits of significand precision, approximately 3 973decimal digits. 974 975Specifying @option{-mfp16-format=alternative} selects the ARM 976alternative format. This representation is similar to the IEEE 977format, but does not support infinities or NaNs. Instead, the range 978of exponents is extended, so that this format can represent normalized 979values in the range of @math{2^{-14}} to 131008. 980 981The @code{__fp16} type is a storage format only. For purposes 982of arithmetic and other operations, @code{__fp16} values in C or C++ 983expressions are automatically promoted to @code{float}. In addition, 984you cannot declare a function with a return value or parameters 985of type @code{__fp16}. 986 987Note that conversions from @code{double} to @code{__fp16} 988involve an intermediate conversion to @code{float}. Because 989of rounding, this can sometimes produce a different result than a 990direct conversion. 991 992ARM provides hardware support for conversions between 993@code{__fp16} and @code{float} values 994as an extension to VFP and NEON (Advanced SIMD). GCC generates 995code using these hardware instructions if you compile with 996options to select an FPU that provides them; 997for example, @option{-mfpu=neon-fp16 -mfloat-abi=softfp}, 998in addition to the @option{-mfp16-format} option to select 999a half-precision format. 1000 1001Language-level support for the @code{__fp16} data type is 1002independent of whether GCC generates code using hardware floating-point 1003instructions. In cases where hardware support is not specified, GCC 1004implements conversions between @code{__fp16} and @code{float} values 1005as library calls. 1006 1007@node Decimal Float 1008@section Decimal Floating Types 1009@cindex decimal floating types 1010@cindex @code{_Decimal32} data type 1011@cindex @code{_Decimal64} data type 1012@cindex @code{_Decimal128} data type 1013@cindex @code{df} integer suffix 1014@cindex @code{dd} integer suffix 1015@cindex @code{dl} integer suffix 1016@cindex @code{DF} integer suffix 1017@cindex @code{DD} integer suffix 1018@cindex @code{DL} integer suffix 1019 1020As an extension, GNU C supports decimal floating types as 1021defined in the N1312 draft of ISO/IEC WDTR24732. Support for decimal 1022floating types in GCC will evolve as the draft technical report changes. 1023Calling conventions for any target might also change. Not all targets 1024support decimal floating types. 1025 1026The decimal floating types are @code{_Decimal32}, @code{_Decimal64}, and 1027@code{_Decimal128}. They use a radix of ten, unlike the floating types 1028@code{float}, @code{double}, and @code{long double} whose radix is not 1029specified by the C standard but is usually two. 1030 1031Support for decimal floating types includes the arithmetic operators 1032add, subtract, multiply, divide; unary arithmetic operators; 1033relational operators; equality operators; and conversions to and from 1034integer and other floating types. Use a suffix @samp{df} or 1035@samp{DF} in a literal constant of type @code{_Decimal32}, @samp{dd} 1036or @samp{DD} for @code{_Decimal64}, and @samp{dl} or @samp{DL} for 1037@code{_Decimal128}. 1038 1039GCC support of decimal float as specified by the draft technical report 1040is incomplete: 1041 1042@itemize @bullet 1043@item 1044When the value of a decimal floating type cannot be represented in the 1045integer type to which it is being converted, the result is undefined 1046rather than the result value specified by the draft technical report. 1047 1048@item 1049GCC does not provide the C library functionality associated with 1050@file{math.h}, @file{fenv.h}, @file{stdio.h}, @file{stdlib.h}, and 1051@file{wchar.h}, which must come from a separate C library implementation. 1052Because of this the GNU C compiler does not define macro 1053@code{__STDC_DEC_FP__} to indicate that the implementation conforms to 1054the technical report. 1055@end itemize 1056 1057Types @code{_Decimal32}, @code{_Decimal64}, and @code{_Decimal128} 1058are supported by the DWARF 2 debug information format. 1059 1060@node Hex Floats 1061@section Hex Floats 1062@cindex hex floats 1063 1064ISO C99 supports floating-point numbers written not only in the usual 1065decimal notation, such as @code{1.55e1}, but also numbers such as 1066@code{0x1.fp3} written in hexadecimal format. As a GNU extension, GCC 1067supports this in C90 mode (except in some cases when strictly 1068conforming) and in C++. In that format the 1069@samp{0x} hex introducer and the @samp{p} or @samp{P} exponent field are 1070mandatory. The exponent is a decimal number that indicates the power of 10712 by which the significant part is multiplied. Thus @samp{0x1.f} is 1072@tex 1073$1 {15\over16}$, 1074@end tex 1075@ifnottex 10761 15/16, 1077@end ifnottex 1078@samp{p3} multiplies it by 8, and the value of @code{0x1.fp3} 1079is the same as @code{1.55e1}. 1080 1081Unlike for floating-point numbers in the decimal notation the exponent 1082is always required in the hexadecimal notation. Otherwise the compiler 1083would not be able to resolve the ambiguity of, e.g., @code{0x1.f}. This 1084could mean @code{1.0f} or @code{1.9375} since @samp{f} is also the 1085extension for floating-point constants of type @code{float}. 1086 1087@node Fixed-Point 1088@section Fixed-Point Types 1089@cindex fixed-point types 1090@cindex @code{_Fract} data type 1091@cindex @code{_Accum} data type 1092@cindex @code{_Sat} data type 1093@cindex @code{hr} fixed-suffix 1094@cindex @code{r} fixed-suffix 1095@cindex @code{lr} fixed-suffix 1096@cindex @code{llr} fixed-suffix 1097@cindex @code{uhr} fixed-suffix 1098@cindex @code{ur} fixed-suffix 1099@cindex @code{ulr} fixed-suffix 1100@cindex @code{ullr} fixed-suffix 1101@cindex @code{hk} fixed-suffix 1102@cindex @code{k} fixed-suffix 1103@cindex @code{lk} fixed-suffix 1104@cindex @code{llk} fixed-suffix 1105@cindex @code{uhk} fixed-suffix 1106@cindex @code{uk} fixed-suffix 1107@cindex @code{ulk} fixed-suffix 1108@cindex @code{ullk} fixed-suffix 1109@cindex @code{HR} fixed-suffix 1110@cindex @code{R} fixed-suffix 1111@cindex @code{LR} fixed-suffix 1112@cindex @code{LLR} fixed-suffix 1113@cindex @code{UHR} fixed-suffix 1114@cindex @code{UR} fixed-suffix 1115@cindex @code{ULR} fixed-suffix 1116@cindex @code{ULLR} fixed-suffix 1117@cindex @code{HK} fixed-suffix 1118@cindex @code{K} fixed-suffix 1119@cindex @code{LK} fixed-suffix 1120@cindex @code{LLK} fixed-suffix 1121@cindex @code{UHK} fixed-suffix 1122@cindex @code{UK} fixed-suffix 1123@cindex @code{ULK} fixed-suffix 1124@cindex @code{ULLK} fixed-suffix 1125 1126As an extension, GNU C supports fixed-point types as 1127defined in the N1169 draft of ISO/IEC DTR 18037. Support for fixed-point 1128types in GCC will evolve as the draft technical report changes. 1129Calling conventions for any target might also change. Not all targets 1130support fixed-point types. 1131 1132The fixed-point types are 1133@code{short _Fract}, 1134@code{_Fract}, 1135@code{long _Fract}, 1136@code{long long _Fract}, 1137@code{unsigned short _Fract}, 1138@code{unsigned _Fract}, 1139@code{unsigned long _Fract}, 1140@code{unsigned long long _Fract}, 1141@code{_Sat short _Fract}, 1142@code{_Sat _Fract}, 1143@code{_Sat long _Fract}, 1144@code{_Sat long long _Fract}, 1145@code{_Sat unsigned short _Fract}, 1146@code{_Sat unsigned _Fract}, 1147@code{_Sat unsigned long _Fract}, 1148@code{_Sat unsigned long long _Fract}, 1149@code{short _Accum}, 1150@code{_Accum}, 1151@code{long _Accum}, 1152@code{long long _Accum}, 1153@code{unsigned short _Accum}, 1154@code{unsigned _Accum}, 1155@code{unsigned long _Accum}, 1156@code{unsigned long long _Accum}, 1157@code{_Sat short _Accum}, 1158@code{_Sat _Accum}, 1159@code{_Sat long _Accum}, 1160@code{_Sat long long _Accum}, 1161@code{_Sat unsigned short _Accum}, 1162@code{_Sat unsigned _Accum}, 1163@code{_Sat unsigned long _Accum}, 1164@code{_Sat unsigned long long _Accum}. 1165 1166Fixed-point data values contain fractional and optional integral parts. 1167The format of fixed-point data varies and depends on the target machine. 1168 1169Support for fixed-point types includes: 1170@itemize @bullet 1171@item 1172prefix and postfix increment and decrement operators (@code{++}, @code{--}) 1173@item 1174unary arithmetic operators (@code{+}, @code{-}, @code{!}) 1175@item 1176binary arithmetic operators (@code{+}, @code{-}, @code{*}, @code{/}) 1177@item 1178binary shift operators (@code{<<}, @code{>>}) 1179@item 1180relational operators (@code{<}, @code{<=}, @code{>=}, @code{>}) 1181@item 1182equality operators (@code{==}, @code{!=}) 1183@item 1184assignment operators (@code{+=}, @code{-=}, @code{*=}, @code{/=}, 1185@code{<<=}, @code{>>=}) 1186@item 1187conversions to and from integer, floating-point, or fixed-point types 1188@end itemize 1189 1190Use a suffix in a fixed-point literal constant: 1191@itemize 1192@item @samp{hr} or @samp{HR} for @code{short _Fract} and 1193@code{_Sat short _Fract} 1194@item @samp{r} or @samp{R} for @code{_Fract} and @code{_Sat _Fract} 1195@item @samp{lr} or @samp{LR} for @code{long _Fract} and 1196@code{_Sat long _Fract} 1197@item @samp{llr} or @samp{LLR} for @code{long long _Fract} and 1198@code{_Sat long long _Fract} 1199@item @samp{uhr} or @samp{UHR} for @code{unsigned short _Fract} and 1200@code{_Sat unsigned short _Fract} 1201@item @samp{ur} or @samp{UR} for @code{unsigned _Fract} and 1202@code{_Sat unsigned _Fract} 1203@item @samp{ulr} or @samp{ULR} for @code{unsigned long _Fract} and 1204@code{_Sat unsigned long _Fract} 1205@item @samp{ullr} or @samp{ULLR} for @code{unsigned long long _Fract} 1206and @code{_Sat unsigned long long _Fract} 1207@item @samp{hk} or @samp{HK} for @code{short _Accum} and 1208@code{_Sat short _Accum} 1209@item @samp{k} or @samp{K} for @code{_Accum} and @code{_Sat _Accum} 1210@item @samp{lk} or @samp{LK} for @code{long _Accum} and 1211@code{_Sat long _Accum} 1212@item @samp{llk} or @samp{LLK} for @code{long long _Accum} and 1213@code{_Sat long long _Accum} 1214@item @samp{uhk} or @samp{UHK} for @code{unsigned short _Accum} and 1215@code{_Sat unsigned short _Accum} 1216@item @samp{uk} or @samp{UK} for @code{unsigned _Accum} and 1217@code{_Sat unsigned _Accum} 1218@item @samp{ulk} or @samp{ULK} for @code{unsigned long _Accum} and 1219@code{_Sat unsigned long _Accum} 1220@item @samp{ullk} or @samp{ULLK} for @code{unsigned long long _Accum} 1221and @code{_Sat unsigned long long _Accum} 1222@end itemize 1223 1224GCC support of fixed-point types as specified by the draft technical report 1225is incomplete: 1226 1227@itemize @bullet 1228@item 1229Pragmas to control overflow and rounding behaviors are not implemented. 1230@end itemize 1231 1232Fixed-point types are supported by the DWARF 2 debug information format. 1233 1234@node Named Address Spaces 1235@section Named Address Spaces 1236@cindex Named Address Spaces 1237 1238As an extension, GNU C supports named address spaces as 1239defined in the N1275 draft of ISO/IEC DTR 18037. Support for named 1240address spaces in GCC will evolve as the draft technical report 1241changes. Calling conventions for any target might also change. At 1242present, only the AVR, SPU, M32C, and RL78 targets support address 1243spaces other than the generic address space. 1244 1245Address space identifiers may be used exactly like any other C type 1246qualifier (e.g., @code{const} or @code{volatile}). See the N1275 1247document for more details. 1248 1249@anchor{AVR Named Address Spaces} 1250@subsection AVR Named Address Spaces 1251 1252On the AVR target, there are several address spaces that can be used 1253in order to put read-only data into the flash memory and access that 1254data by means of the special instructions @code{LPM} or @code{ELPM} 1255needed to read from flash. 1256 1257Per default, any data including read-only data is located in RAM 1258(the generic address space) so that non-generic address spaces are 1259needed to locate read-only data in flash memory 1260@emph{and} to generate the right instructions to access this data 1261without using (inline) assembler code. 1262 1263@table @code 1264@item __flash 1265@cindex @code{__flash} AVR Named Address Spaces 1266The @code{__flash} qualifier locates data in the 1267@code{.progmem.data} section. Data is read using the @code{LPM} 1268instruction. Pointers to this address space are 16 bits wide. 1269 1270@item __flash1 1271@itemx __flash2 1272@itemx __flash3 1273@itemx __flash4 1274@itemx __flash5 1275@cindex @code{__flash1} AVR Named Address Spaces 1276@cindex @code{__flash2} AVR Named Address Spaces 1277@cindex @code{__flash3} AVR Named Address Spaces 1278@cindex @code{__flash4} AVR Named Address Spaces 1279@cindex @code{__flash5} AVR Named Address Spaces 1280These are 16-bit address spaces locating data in section 1281@code{.progmem@var{N}.data} where @var{N} refers to 1282address space @code{__flash@var{N}}. 1283The compiler sets the @code{RAMPZ} segment register appropriately 1284before reading data by means of the @code{ELPM} instruction. 1285 1286@item __memx 1287@cindex @code{__memx} AVR Named Address Spaces 1288This is a 24-bit address space that linearizes flash and RAM: 1289If the high bit of the address is set, data is read from 1290RAM using the lower two bytes as RAM address. 1291If the high bit of the address is clear, data is read from flash 1292with @code{RAMPZ} set according to the high byte of the address. 1293@xref{AVR Built-in Functions,,@code{__builtin_avr_flash_segment}}. 1294 1295Objects in this address space are located in @code{.progmemx.data}. 1296@end table 1297 1298@b{Example} 1299 1300@smallexample 1301char my_read (const __flash char ** p) 1302@{ 1303 /* p is a pointer to RAM that points to a pointer to flash. 1304 The first indirection of p reads that flash pointer 1305 from RAM and the second indirection reads a char from this 1306 flash address. */ 1307 1308 return **p; 1309@} 1310 1311/* Locate array[] in flash memory */ 1312const __flash int array[] = @{ 3, 5, 7, 11, 13, 17, 19 @}; 1313 1314int i = 1; 1315 1316int main (void) 1317@{ 1318 /* Return 17 by reading from flash memory */ 1319 return array[array[i]]; 1320@} 1321@end smallexample 1322 1323@noindent 1324For each named address space supported by avr-gcc there is an equally 1325named but uppercase built-in macro defined. 1326The purpose is to facilitate testing if respective address space 1327support is available or not: 1328 1329@smallexample 1330#ifdef __FLASH 1331const __flash int var = 1; 1332 1333int read_var (void) 1334@{ 1335 return var; 1336@} 1337#else 1338#include <avr/pgmspace.h> /* From AVR-LibC */ 1339 1340const int var PROGMEM = 1; 1341 1342int read_var (void) 1343@{ 1344 return (int) pgm_read_word (&var); 1345@} 1346#endif /* __FLASH */ 1347@end smallexample 1348 1349@noindent 1350Notice that attribute @ref{AVR Variable Attributes,,@code{progmem}} 1351locates data in flash but 1352accesses to these data read from generic address space, i.e.@: 1353from RAM, 1354so that you need special accessors like @code{pgm_read_byte} 1355from @w{@uref{http://nongnu.org/avr-libc/user-manual/,AVR-LibC}} 1356together with attribute @code{progmem}. 1357 1358@noindent 1359@b{Limitations and caveats} 1360 1361@itemize 1362@item 1363Reading across the 64@tie{}KiB section boundary of 1364the @code{__flash} or @code{__flash@var{N}} address spaces 1365shows undefined behavior. The only address space that 1366supports reading across the 64@tie{}KiB flash segment boundaries is 1367@code{__memx}. 1368 1369@item 1370If you use one of the @code{__flash@var{N}} address spaces 1371you must arrange your linker script to locate the 1372@code{.progmem@var{N}.data} sections according to your needs. 1373 1374@item 1375Any data or pointers to the non-generic address spaces must 1376be qualified as @code{const}, i.e.@: as read-only data. 1377This still applies if the data in one of these address 1378spaces like software version number or calibration lookup table are intended to 1379be changed after load time by, say, a boot loader. In this case 1380the right qualification is @code{const} @code{volatile} so that the compiler 1381must not optimize away known values or insert them 1382as immediates into operands of instructions. 1383 1384@item 1385The following code initializes a variable @code{pfoo} 1386located in static storage with a 24-bit address: 1387@smallexample 1388extern const __memx char foo; 1389const __memx void *pfoo = &foo; 1390@end smallexample 1391 1392@noindent 1393Such code requires at least binutils 2.23, see 1394@w{@uref{http://sourceware.org/PR13503,PR13503}}. 1395 1396@end itemize 1397 1398@subsection M32C Named Address Spaces 1399@cindex @code{__far} M32C Named Address Spaces 1400 1401On the M32C target, with the R8C and M16C CPU variants, variables 1402qualified with @code{__far} are accessed using 32-bit addresses in 1403order to access memory beyond the first 64@tie{}Ki bytes. If 1404@code{__far} is used with the M32CM or M32C CPU variants, it has no 1405effect. 1406 1407@subsection RL78 Named Address Spaces 1408@cindex @code{__far} RL78 Named Address Spaces 1409 1410On the RL78 target, variables qualified with @code{__far} are accessed 1411with 32-bit pointers (20-bit addresses) rather than the default 16-bit 1412addresses. Non-far variables are assumed to appear in the topmost 141364@tie{}KiB of the address space. 1414 1415@subsection SPU Named Address Spaces 1416@cindex @code{__ea} SPU Named Address Spaces 1417 1418On the SPU target variables may be declared as 1419belonging to another address space by qualifying the type with the 1420@code{__ea} address space identifier: 1421 1422@smallexample 1423extern int __ea i; 1424@end smallexample 1425 1426@noindent 1427The compiler generates special code to access the variable @code{i}. 1428It may use runtime library 1429support, or generate special machine instructions to access that address 1430space. 1431 1432@node Zero Length 1433@section Arrays of Length Zero 1434@cindex arrays of length zero 1435@cindex zero-length arrays 1436@cindex length-zero arrays 1437@cindex flexible array members 1438 1439Zero-length arrays are allowed in GNU C@. They are very useful as the 1440last element of a structure that is really a header for a variable-length 1441object: 1442 1443@smallexample 1444struct line @{ 1445 int length; 1446 char contents[0]; 1447@}; 1448 1449struct line *thisline = (struct line *) 1450 malloc (sizeof (struct line) + this_length); 1451thisline->length = this_length; 1452@end smallexample 1453 1454In ISO C90, you would have to give @code{contents} a length of 1, which 1455means either you waste space or complicate the argument to @code{malloc}. 1456 1457In ISO C99, you would use a @dfn{flexible array member}, which is 1458slightly different in syntax and semantics: 1459 1460@itemize @bullet 1461@item 1462Flexible array members are written as @code{contents[]} without 1463the @code{0}. 1464 1465@item 1466Flexible array members have incomplete type, and so the @code{sizeof} 1467operator may not be applied. As a quirk of the original implementation 1468of zero-length arrays, @code{sizeof} evaluates to zero. 1469 1470@item 1471Flexible array members may only appear as the last member of a 1472@code{struct} that is otherwise non-empty. 1473 1474@item 1475A structure containing a flexible array member, or a union containing 1476such a structure (possibly recursively), may not be a member of a 1477structure or an element of an array. (However, these uses are 1478permitted by GCC as extensions.) 1479@end itemize 1480 1481Non-empty initialization of zero-length 1482arrays is treated like any case where there are more initializer 1483elements than the array holds, in that a suitable warning about ``excess 1484elements in array'' is given, and the excess elements (all of them, in 1485this case) are ignored. 1486 1487GCC allows static initialization of flexible array members. 1488This is equivalent to defining a new structure containing the original 1489structure followed by an array of sufficient size to contain the data. 1490E.g.@: in the following, @code{f1} is constructed as if it were declared 1491like @code{f2}. 1492 1493@smallexample 1494struct f1 @{ 1495 int x; int y[]; 1496@} f1 = @{ 1, @{ 2, 3, 4 @} @}; 1497 1498struct f2 @{ 1499 struct f1 f1; int data[3]; 1500@} f2 = @{ @{ 1 @}, @{ 2, 3, 4 @} @}; 1501@end smallexample 1502 1503@noindent 1504The convenience of this extension is that @code{f1} has the desired 1505type, eliminating the need to consistently refer to @code{f2.f1}. 1506 1507This has symmetry with normal static arrays, in that an array of 1508unknown size is also written with @code{[]}. 1509 1510Of course, this extension only makes sense if the extra data comes at 1511the end of a top-level object, as otherwise we would be overwriting 1512data at subsequent offsets. To avoid undue complication and confusion 1513with initialization of deeply nested arrays, we simply disallow any 1514non-empty initialization except when the structure is the top-level 1515object. For example: 1516 1517@smallexample 1518struct foo @{ int x; int y[]; @}; 1519struct bar @{ struct foo z; @}; 1520 1521struct foo a = @{ 1, @{ 2, 3, 4 @} @}; // @r{Valid.} 1522struct bar b = @{ @{ 1, @{ 2, 3, 4 @} @} @}; // @r{Invalid.} 1523struct bar c = @{ @{ 1, @{ @} @} @}; // @r{Valid.} 1524struct foo d[1] = @{ @{ 1, @{ 2, 3, 4 @} @} @}; // @r{Invalid.} 1525@end smallexample 1526 1527@node Empty Structures 1528@section Structures with No Members 1529@cindex empty structures 1530@cindex zero-size structures 1531 1532GCC permits a C structure to have no members: 1533 1534@smallexample 1535struct empty @{ 1536@}; 1537@end smallexample 1538 1539The structure has size zero. In C++, empty structures are part 1540of the language. G++ treats empty structures as if they had a single 1541member of type @code{char}. 1542 1543@node Variable Length 1544@section Arrays of Variable Length 1545@cindex variable-length arrays 1546@cindex arrays of variable length 1547@cindex VLAs 1548 1549Variable-length automatic arrays are allowed in ISO C99, and as an 1550extension GCC accepts them in C90 mode and in C++. These arrays are 1551declared like any other automatic arrays, but with a length that is not 1552a constant expression. The storage is allocated at the point of 1553declaration and deallocated when the block scope containing the declaration 1554exits. For 1555example: 1556 1557@smallexample 1558FILE * 1559concat_fopen (char *s1, char *s2, char *mode) 1560@{ 1561 char str[strlen (s1) + strlen (s2) + 1]; 1562 strcpy (str, s1); 1563 strcat (str, s2); 1564 return fopen (str, mode); 1565@} 1566@end smallexample 1567 1568@cindex scope of a variable length array 1569@cindex variable-length array scope 1570@cindex deallocating variable length arrays 1571Jumping or breaking out of the scope of the array name deallocates the 1572storage. Jumping into the scope is not allowed; you get an error 1573message for it. 1574 1575@cindex variable-length array in a structure 1576As an extension, GCC accepts variable-length arrays as a member of 1577a structure or a union. For example: 1578 1579@smallexample 1580void 1581foo (int n) 1582@{ 1583 struct S @{ int x[n]; @}; 1584@} 1585@end smallexample 1586 1587@cindex @code{alloca} vs variable-length arrays 1588You can use the function @code{alloca} to get an effect much like 1589variable-length arrays. The function @code{alloca} is available in 1590many other C implementations (but not in all). On the other hand, 1591variable-length arrays are more elegant. 1592 1593There are other differences between these two methods. Space allocated 1594with @code{alloca} exists until the containing @emph{function} returns. 1595The space for a variable-length array is deallocated as soon as the array 1596name's scope ends. (If you use both variable-length arrays and 1597@code{alloca} in the same function, deallocation of a variable-length array 1598also deallocates anything more recently allocated with @code{alloca}.) 1599 1600You can also use variable-length arrays as arguments to functions: 1601 1602@smallexample 1603struct entry 1604tester (int len, char data[len][len]) 1605@{ 1606 /* @r{@dots{}} */ 1607@} 1608@end smallexample 1609 1610The length of an array is computed once when the storage is allocated 1611and is remembered for the scope of the array in case you access it with 1612@code{sizeof}. 1613 1614If you want to pass the array first and the length afterward, you can 1615use a forward declaration in the parameter list---another GNU extension. 1616 1617@smallexample 1618struct entry 1619tester (int len; char data[len][len], int len) 1620@{ 1621 /* @r{@dots{}} */ 1622@} 1623@end smallexample 1624 1625@cindex parameter forward declaration 1626The @samp{int len} before the semicolon is a @dfn{parameter forward 1627declaration}, and it serves the purpose of making the name @code{len} 1628known when the declaration of @code{data} is parsed. 1629 1630You can write any number of such parameter forward declarations in the 1631parameter list. They can be separated by commas or semicolons, but the 1632last one must end with a semicolon, which is followed by the ``real'' 1633parameter declarations. Each forward declaration must match a ``real'' 1634declaration in parameter name and data type. ISO C99 does not support 1635parameter forward declarations. 1636 1637@node Variadic Macros 1638@section Macros with a Variable Number of Arguments. 1639@cindex variable number of arguments 1640@cindex macro with variable arguments 1641@cindex rest argument (in macro) 1642@cindex variadic macros 1643 1644In the ISO C standard of 1999, a macro can be declared to accept a 1645variable number of arguments much as a function can. The syntax for 1646defining the macro is similar to that of a function. Here is an 1647example: 1648 1649@smallexample 1650#define debug(format, ...) fprintf (stderr, format, __VA_ARGS__) 1651@end smallexample 1652 1653@noindent 1654Here @samp{@dots{}} is a @dfn{variable argument}. In the invocation of 1655such a macro, it represents the zero or more tokens until the closing 1656parenthesis that ends the invocation, including any commas. This set of 1657tokens replaces the identifier @code{__VA_ARGS__} in the macro body 1658wherever it appears. See the CPP manual for more information. 1659 1660GCC has long supported variadic macros, and used a different syntax that 1661allowed you to give a name to the variable arguments just like any other 1662argument. Here is an example: 1663 1664@smallexample 1665#define debug(format, args...) fprintf (stderr, format, args) 1666@end smallexample 1667 1668@noindent 1669This is in all ways equivalent to the ISO C example above, but arguably 1670more readable and descriptive. 1671 1672GNU CPP has two further variadic macro extensions, and permits them to 1673be used with either of the above forms of macro definition. 1674 1675In standard C, you are not allowed to leave the variable argument out 1676entirely; but you are allowed to pass an empty argument. For example, 1677this invocation is invalid in ISO C, because there is no comma after 1678the string: 1679 1680@smallexample 1681debug ("A message") 1682@end smallexample 1683 1684GNU CPP permits you to completely omit the variable arguments in this 1685way. In the above examples, the compiler would complain, though since 1686the expansion of the macro still has the extra comma after the format 1687string. 1688 1689To help solve this problem, CPP behaves specially for variable arguments 1690used with the token paste operator, @samp{##}. If instead you write 1691 1692@smallexample 1693#define debug(format, ...) fprintf (stderr, format, ## __VA_ARGS__) 1694@end smallexample 1695 1696@noindent 1697and if the variable arguments are omitted or empty, the @samp{##} 1698operator causes the preprocessor to remove the comma before it. If you 1699do provide some variable arguments in your macro invocation, GNU CPP 1700does not complain about the paste operation and instead places the 1701variable arguments after the comma. Just like any other pasted macro 1702argument, these arguments are not macro expanded. 1703 1704@node Escaped Newlines 1705@section Slightly Looser Rules for Escaped Newlines 1706@cindex escaped newlines 1707@cindex newlines (escaped) 1708 1709The preprocessor treatment of escaped newlines is more relaxed 1710than that specified by the C90 standard, which requires the newline 1711to immediately follow a backslash. 1712GCC's implementation allows whitespace in the form 1713of spaces, horizontal and vertical tabs, and form feeds between the 1714backslash and the subsequent newline. The preprocessor issues a 1715warning, but treats it as a valid escaped newline and combines the two 1716lines to form a single logical line. This works within comments and 1717tokens, as well as between tokens. Comments are @emph{not} treated as 1718whitespace for the purposes of this relaxation, since they have not 1719yet been replaced with spaces. 1720 1721@node Subscripting 1722@section Non-Lvalue Arrays May Have Subscripts 1723@cindex subscripting 1724@cindex arrays, non-lvalue 1725 1726@cindex subscripting and function values 1727In ISO C99, arrays that are not lvalues still decay to pointers, and 1728may be subscripted, although they may not be modified or used after 1729the next sequence point and the unary @samp{&} operator may not be 1730applied to them. As an extension, GNU C allows such arrays to be 1731subscripted in C90 mode, though otherwise they do not decay to 1732pointers outside C99 mode. For example, 1733this is valid in GNU C though not valid in C90: 1734 1735@smallexample 1736@group 1737struct foo @{int a[4];@}; 1738 1739struct foo f(); 1740 1741bar (int index) 1742@{ 1743 return f().a[index]; 1744@} 1745@end group 1746@end smallexample 1747 1748@node Pointer Arith 1749@section Arithmetic on @code{void}- and Function-Pointers 1750@cindex void pointers, arithmetic 1751@cindex void, size of pointer to 1752@cindex function pointers, arithmetic 1753@cindex function, size of pointer to 1754 1755In GNU C, addition and subtraction operations are supported on pointers to 1756@code{void} and on pointers to functions. This is done by treating the 1757size of a @code{void} or of a function as 1. 1758 1759A consequence of this is that @code{sizeof} is also allowed on @code{void} 1760and on function types, and returns 1. 1761 1762@opindex Wpointer-arith 1763The option @option{-Wpointer-arith} requests a warning if these extensions 1764are used. 1765 1766@node Pointers to Arrays 1767@section Pointers to Arrays with Qualifiers Work as Expected 1768@cindex pointers to arrays 1769@cindex const qualifier 1770 1771In GNU C, pointers to arrays with qualifiers work similar to pointers 1772to other qualified types. For example, a value of type @code{int (*)[5]} 1773can be used to initialize a variable of type @code{const int (*)[5]}. 1774These types are incompatible in ISO C because the @code{const} qualifier 1775is formally attached to the element type of the array and not the 1776array itself. 1777 1778@smallexample 1779extern void 1780transpose (int N, int M, double out[M][N], const double in[N][M]); 1781double x[3][2]; 1782double y[2][3]; 1783@r{@dots{}} 1784transpose(3, 2, y, x); 1785@end smallexample 1786 1787@node Initializers 1788@section Non-Constant Initializers 1789@cindex initializers, non-constant 1790@cindex non-constant initializers 1791 1792As in standard C++ and ISO C99, the elements of an aggregate initializer for an 1793automatic variable are not required to be constant expressions in GNU C@. 1794Here is an example of an initializer with run-time varying elements: 1795 1796@smallexample 1797foo (float f, float g) 1798@{ 1799 float beat_freqs[2] = @{ f-g, f+g @}; 1800 /* @r{@dots{}} */ 1801@} 1802@end smallexample 1803 1804@node Compound Literals 1805@section Compound Literals 1806@cindex constructor expressions 1807@cindex initializations in expressions 1808@cindex structures, constructor expression 1809@cindex expressions, constructor 1810@cindex compound literals 1811@c The GNU C name for what C99 calls compound literals was "constructor expressions". 1812 1813ISO C99 supports compound literals. A compound literal looks like 1814a cast containing an initializer. Its value is an object of the 1815type specified in the cast, containing the elements specified in 1816the initializer; it is an lvalue. As an extension, GCC supports 1817compound literals in C90 mode and in C++, though the semantics are 1818somewhat different in C++. 1819 1820Usually, the specified type is a structure. Assume that 1821@code{struct foo} and @code{structure} are declared as shown: 1822 1823@smallexample 1824struct foo @{int a; char b[2];@} structure; 1825@end smallexample 1826 1827@noindent 1828Here is an example of constructing a @code{struct foo} with a compound literal: 1829 1830@smallexample 1831structure = ((struct foo) @{x + y, 'a', 0@}); 1832@end smallexample 1833 1834@noindent 1835This is equivalent to writing the following: 1836 1837@smallexample 1838@{ 1839 struct foo temp = @{x + y, 'a', 0@}; 1840 structure = temp; 1841@} 1842@end smallexample 1843 1844You can also construct an array, though this is dangerous in C++, as 1845explained below. If all the elements of the compound literal are 1846(made up of) simple constant expressions, suitable for use in 1847initializers of objects of static storage duration, then the compound 1848literal can be coerced to a pointer to its first element and used in 1849such an initializer, as shown here: 1850 1851@smallexample 1852char **foo = (char *[]) @{ "x", "y", "z" @}; 1853@end smallexample 1854 1855Compound literals for scalar types and union types are 1856also allowed, but then the compound literal is equivalent 1857to a cast. 1858 1859As a GNU extension, GCC allows initialization of objects with static storage 1860duration by compound literals (which is not possible in ISO C99, because 1861the initializer is not a constant). 1862It is handled as if the object is initialized only with the bracket 1863enclosed list if the types of the compound literal and the object match. 1864The initializer list of the compound literal must be constant. 1865If the object being initialized has array type of unknown size, the size is 1866determined by compound literal size. 1867 1868@smallexample 1869static struct foo x = (struct foo) @{1, 'a', 'b'@}; 1870static int y[] = (int []) @{1, 2, 3@}; 1871static int z[] = (int [3]) @{1@}; 1872@end smallexample 1873 1874@noindent 1875The above lines are equivalent to the following: 1876@smallexample 1877static struct foo x = @{1, 'a', 'b'@}; 1878static int y[] = @{1, 2, 3@}; 1879static int z[] = @{1, 0, 0@}; 1880@end smallexample 1881 1882In C, a compound literal designates an unnamed object with static or 1883automatic storage duration. In C++, a compound literal designates a 1884temporary object, which only lives until the end of its 1885full-expression. As a result, well-defined C code that takes the 1886address of a subobject of a compound literal can be undefined in C++, 1887so the C++ compiler rejects the conversion of a temporary array to a pointer. 1888For instance, if the array compound literal example above appeared 1889inside a function, any subsequent use of @samp{foo} in C++ has 1890undefined behavior because the lifetime of the array ends after the 1891declaration of @samp{foo}. 1892 1893As an optimization, the C++ compiler sometimes gives array compound 1894literals longer lifetimes: when the array either appears outside a 1895function or has const-qualified type. If @samp{foo} and its 1896initializer had elements of @samp{char *const} type rather than 1897@samp{char *}, or if @samp{foo} were a global variable, the array 1898would have static storage duration. But it is probably safest just to 1899avoid the use of array compound literals in code compiled as C++. 1900 1901@node Designated Inits 1902@section Designated Initializers 1903@cindex initializers with labeled elements 1904@cindex labeled elements in initializers 1905@cindex case labels in initializers 1906@cindex designated initializers 1907 1908Standard C90 requires the elements of an initializer to appear in a fixed 1909order, the same as the order of the elements in the array or structure 1910being initialized. 1911 1912In ISO C99 you can give the elements in any order, specifying the array 1913indices or structure field names they apply to, and GNU C allows this as 1914an extension in C90 mode as well. This extension is not 1915implemented in GNU C++. 1916 1917To specify an array index, write 1918@samp{[@var{index}] =} before the element value. For example, 1919 1920@smallexample 1921int a[6] = @{ [4] = 29, [2] = 15 @}; 1922@end smallexample 1923 1924@noindent 1925is equivalent to 1926 1927@smallexample 1928int a[6] = @{ 0, 0, 15, 0, 29, 0 @}; 1929@end smallexample 1930 1931@noindent 1932The index values must be constant expressions, even if the array being 1933initialized is automatic. 1934 1935An alternative syntax for this that has been obsolete since GCC 2.5 but 1936GCC still accepts is to write @samp{[@var{index}]} before the element 1937value, with no @samp{=}. 1938 1939To initialize a range of elements to the same value, write 1940@samp{[@var{first} ... @var{last}] = @var{value}}. This is a GNU 1941extension. For example, 1942 1943@smallexample 1944int widths[] = @{ [0 ... 9] = 1, [10 ... 99] = 2, [100] = 3 @}; 1945@end smallexample 1946 1947@noindent 1948If the value in it has side-effects, the side-effects happen only once, 1949not for each initialized field by the range initializer. 1950 1951@noindent 1952Note that the length of the array is the highest value specified 1953plus one. 1954 1955In a structure initializer, specify the name of a field to initialize 1956with @samp{.@var{fieldname} =} before the element value. For example, 1957given the following structure, 1958 1959@smallexample 1960struct point @{ int x, y; @}; 1961@end smallexample 1962 1963@noindent 1964the following initialization 1965 1966@smallexample 1967struct point p = @{ .y = yvalue, .x = xvalue @}; 1968@end smallexample 1969 1970@noindent 1971is equivalent to 1972 1973@smallexample 1974struct point p = @{ xvalue, yvalue @}; 1975@end smallexample 1976 1977Another syntax that has the same meaning, obsolete since GCC 2.5, is 1978@samp{@var{fieldname}:}, as shown here: 1979 1980@smallexample 1981struct point p = @{ y: yvalue, x: xvalue @}; 1982@end smallexample 1983 1984Omitted field members are implicitly initialized the same as objects 1985that have static storage duration. 1986 1987@cindex designators 1988The @samp{[@var{index}]} or @samp{.@var{fieldname}} is known as a 1989@dfn{designator}. You can also use a designator (or the obsolete colon 1990syntax) when initializing a union, to specify which element of the union 1991should be used. For example, 1992 1993@smallexample 1994union foo @{ int i; double d; @}; 1995 1996union foo f = @{ .d = 4 @}; 1997@end smallexample 1998 1999@noindent 2000converts 4 to a @code{double} to store it in the union using 2001the second element. By contrast, casting 4 to type @code{union foo} 2002stores it into the union as the integer @code{i}, since it is 2003an integer. (@xref{Cast to Union}.) 2004 2005You can combine this technique of naming elements with ordinary C 2006initialization of successive elements. Each initializer element that 2007does not have a designator applies to the next consecutive element of the 2008array or structure. For example, 2009 2010@smallexample 2011int a[6] = @{ [1] = v1, v2, [4] = v4 @}; 2012@end smallexample 2013 2014@noindent 2015is equivalent to 2016 2017@smallexample 2018int a[6] = @{ 0, v1, v2, 0, v4, 0 @}; 2019@end smallexample 2020 2021Labeling the elements of an array initializer is especially useful 2022when the indices are characters or belong to an @code{enum} type. 2023For example: 2024 2025@smallexample 2026int whitespace[256] 2027 = @{ [' '] = 1, ['\t'] = 1, ['\h'] = 1, 2028 ['\f'] = 1, ['\n'] = 1, ['\r'] = 1 @}; 2029@end smallexample 2030 2031@cindex designator lists 2032You can also write a series of @samp{.@var{fieldname}} and 2033@samp{[@var{index}]} designators before an @samp{=} to specify a 2034nested subobject to initialize; the list is taken relative to the 2035subobject corresponding to the closest surrounding brace pair. For 2036example, with the @samp{struct point} declaration above: 2037 2038@smallexample 2039struct point ptarray[10] = @{ [2].y = yv2, [2].x = xv2, [0].x = xv0 @}; 2040@end smallexample 2041 2042@noindent 2043If the same field is initialized multiple times, it has the value from 2044the last initialization. If any such overridden initialization has 2045side-effect, it is unspecified whether the side-effect happens or not. 2046Currently, GCC discards them and issues a warning. 2047 2048@node Case Ranges 2049@section Case Ranges 2050@cindex case ranges 2051@cindex ranges in case statements 2052 2053You can specify a range of consecutive values in a single @code{case} label, 2054like this: 2055 2056@smallexample 2057case @var{low} ... @var{high}: 2058@end smallexample 2059 2060@noindent 2061This has the same effect as the proper number of individual @code{case} 2062labels, one for each integer value from @var{low} to @var{high}, inclusive. 2063 2064This feature is especially useful for ranges of ASCII character codes: 2065 2066@smallexample 2067case 'A' ... 'Z': 2068@end smallexample 2069 2070@strong{Be careful:} Write spaces around the @code{...}, for otherwise 2071it may be parsed wrong when you use it with integer values. For example, 2072write this: 2073 2074@smallexample 2075case 1 ... 5: 2076@end smallexample 2077 2078@noindent 2079rather than this: 2080 2081@smallexample 2082case 1...5: 2083@end smallexample 2084 2085@node Cast to Union 2086@section Cast to a Union Type 2087@cindex cast to a union 2088@cindex union, casting to a 2089 2090A cast to union type is similar to other casts, except that the type 2091specified is a union type. You can specify the type either with 2092@code{union @var{tag}} or with a typedef name. A cast to union is actually 2093a constructor, not a cast, and hence does not yield an lvalue like 2094normal casts. (@xref{Compound Literals}.) 2095 2096The types that may be cast to the union type are those of the members 2097of the union. Thus, given the following union and variables: 2098 2099@smallexample 2100union foo @{ int i; double d; @}; 2101int x; 2102double y; 2103@end smallexample 2104 2105@noindent 2106both @code{x} and @code{y} can be cast to type @code{union foo}. 2107 2108Using the cast as the right-hand side of an assignment to a variable of 2109union type is equivalent to storing in a member of the union: 2110 2111@smallexample 2112union foo u; 2113/* @r{@dots{}} */ 2114u = (union foo) x @equiv{} u.i = x 2115u = (union foo) y @equiv{} u.d = y 2116@end smallexample 2117 2118You can also use the union cast as a function argument: 2119 2120@smallexample 2121void hack (union foo); 2122/* @r{@dots{}} */ 2123hack ((union foo) x); 2124@end smallexample 2125 2126@node Mixed Declarations 2127@section Mixed Declarations and Code 2128@cindex mixed declarations and code 2129@cindex declarations, mixed with code 2130@cindex code, mixed with declarations 2131 2132ISO C99 and ISO C++ allow declarations and code to be freely mixed 2133within compound statements. As an extension, GNU C also allows this in 2134C90 mode. For example, you could do: 2135 2136@smallexample 2137int i; 2138/* @r{@dots{}} */ 2139i++; 2140int j = i + 2; 2141@end smallexample 2142 2143Each identifier is visible from where it is declared until the end of 2144the enclosing block. 2145 2146@node Function Attributes 2147@section Declaring Attributes of Functions 2148@cindex function attributes 2149@cindex declaring attributes of functions 2150@cindex functions that never return 2151@cindex functions that return more than once 2152@cindex functions that have no side effects 2153@cindex functions in arbitrary sections 2154@cindex functions that behave like malloc 2155@cindex @code{volatile} applied to function 2156@cindex @code{const} applied to function 2157@cindex functions with @code{printf}, @code{scanf}, @code{strftime} or @code{strfmon} style arguments 2158@cindex functions with non-null pointer arguments 2159@cindex functions that are passed arguments in registers on x86-32 2160@cindex functions that pop the argument stack on x86-32 2161@cindex functions that do not pop the argument stack on x86-32 2162@cindex functions that have different compilation options on x86-32 2163@cindex functions that have different optimization options 2164@cindex functions that are dynamically resolved 2165 2166In GNU C, you declare certain things about functions called in your program 2167which help the compiler optimize function calls and check your code more 2168carefully. 2169 2170The keyword @code{__attribute__} allows you to specify special 2171attributes when making a declaration. This keyword is followed by an 2172attribute specification inside double parentheses. The following 2173attributes are currently defined for functions on all targets: 2174@code{aligned}, @code{alloc_size}, @code{alloc_align}, @code{assume_aligned}, 2175@code{noreturn}, @code{returns_twice}, @code{noinline}, @code{noclone}, 2176@code{no_icf}, 2177@code{always_inline}, @code{flatten}, @code{pure}, @code{const}, 2178@code{nothrow}, @code{sentinel}, @code{format}, @code{format_arg}, 2179@code{no_instrument_function}, @code{no_split_stack}, 2180@code{section}, @code{constructor}, 2181@code{destructor}, @code{used}, @code{unused}, @code{deprecated}, 2182@code{weak}, @code{malloc}, @code{alias}, @code{ifunc}, 2183@code{warn_unused_result}, @code{nonnull}, 2184@code{returns_nonnull}, @code{gnu_inline}, 2185@code{externally_visible}, @code{hot}, @code{cold}, @code{artificial}, 2186@code{no_sanitize_address}, @code{no_address_safety_analysis}, 2187@code{no_sanitize_thread}, 2188@code{no_sanitize_undefined}, @code{no_reorder}, @code{bnd_legacy}, 2189@code{bnd_instrument}, @code{stack_protect}, 2190@code{error} and @code{warning}. 2191Several other attributes are defined for functions on particular 2192target systems. Other attributes, including @code{section} are 2193supported for variables declarations (@pxref{Variable Attributes}), 2194labels (@pxref{Label Attributes}) 2195and for types (@pxref{Type Attributes}). 2196 2197GCC plugins may provide their own attributes. 2198 2199You may also specify attributes with @samp{__} preceding and following 2200each keyword. This allows you to use them in header files without 2201being concerned about a possible macro of the same name. For example, 2202you may use @code{__noreturn__} instead of @code{noreturn}. 2203 2204@xref{Attribute Syntax}, for details of the exact syntax for using 2205attributes. 2206 2207@table @code 2208@c Keep this table alphabetized by attribute name. Treat _ as space. 2209 2210@item alias ("@var{target}") 2211@cindex @code{alias} function attribute 2212The @code{alias} attribute causes the declaration to be emitted as an 2213alias for another symbol, which must be specified. For instance, 2214 2215@smallexample 2216void __f () @{ /* @r{Do something.} */; @} 2217void f () __attribute__ ((weak, alias ("__f"))); 2218@end smallexample 2219 2220@noindent 2221defines @samp{f} to be a weak alias for @samp{__f}. In C++, the 2222mangled name for the target must be used. It is an error if @samp{__f} 2223is not defined in the same translation unit. 2224 2225Not all target machines support this attribute. 2226 2227@item aligned (@var{alignment}) 2228@cindex @code{aligned} function attribute 2229This attribute specifies a minimum alignment for the function, 2230measured in bytes. 2231 2232You cannot use this attribute to decrease the alignment of a function, 2233only to increase it. However, when you explicitly specify a function 2234alignment this overrides the effect of the 2235@option{-falign-functions} (@pxref{Optimize Options}) option for this 2236function. 2237 2238Note that the effectiveness of @code{aligned} attributes may be 2239limited by inherent limitations in your linker. On many systems, the 2240linker is only able to arrange for functions to be aligned up to a 2241certain maximum alignment. (For some linkers, the maximum supported 2242alignment may be very very small.) See your linker documentation for 2243further information. 2244 2245The @code{aligned} attribute can also be used for variables and fields 2246(@pxref{Variable Attributes}.) 2247 2248@item alloc_size 2249@cindex @code{alloc_size} function attribute 2250The @code{alloc_size} attribute is used to tell the compiler that the 2251function return value points to memory, where the size is given by 2252one or two of the functions parameters. GCC uses this 2253information to improve the correctness of @code{__builtin_object_size}. 2254 2255The function parameter(s) denoting the allocated size are specified by 2256one or two integer arguments supplied to the attribute. The allocated size 2257is either the value of the single function argument specified or the product 2258of the two function arguments specified. Argument numbering starts at 2259one. 2260 2261For instance, 2262 2263@smallexample 2264void* my_calloc(size_t, size_t) __attribute__((alloc_size(1,2))) 2265void* my_realloc(void*, size_t) __attribute__((alloc_size(2))) 2266@end smallexample 2267 2268@noindent 2269declares that @code{my_calloc} returns memory of the size given by 2270the product of parameter 1 and 2 and that @code{my_realloc} returns memory 2271of the size given by parameter 2. 2272 2273@item alloc_align 2274@cindex @code{alloc_align} function attribute 2275The @code{alloc_align} attribute is used to tell the compiler that the 2276function return value points to memory, where the returned pointer minimum 2277alignment is given by one of the functions parameters. GCC uses this 2278information to improve pointer alignment analysis. 2279 2280The function parameter denoting the allocated alignment is specified by 2281one integer argument, whose number is the argument of the attribute. 2282Argument numbering starts at one. 2283 2284For instance, 2285 2286@smallexample 2287void* my_memalign(size_t, size_t) __attribute__((alloc_align(1))) 2288@end smallexample 2289 2290@noindent 2291declares that @code{my_memalign} returns memory with minimum alignment 2292given by parameter 1. 2293 2294@item assume_aligned 2295@cindex @code{assume_aligned} function attribute 2296The @code{assume_aligned} attribute is used to tell the compiler that the 2297function return value points to memory, where the returned pointer minimum 2298alignment is given by the first argument. 2299If the attribute has two arguments, the second argument is misalignment offset. 2300 2301For instance 2302 2303@smallexample 2304void* my_alloc1(size_t) __attribute__((assume_aligned(16))) 2305void* my_alloc2(size_t) __attribute__((assume_aligned(32, 8))) 2306@end smallexample 2307 2308@noindent 2309declares that @code{my_alloc1} returns 16-byte aligned pointer and 2310that @code{my_alloc2} returns a pointer whose value modulo 32 is equal 2311to 8. 2312 2313@item always_inline 2314@cindex @code{always_inline} function attribute 2315Generally, functions are not inlined unless optimization is specified. 2316For functions declared inline, this attribute inlines the function 2317independent of any restrictions that otherwise apply to inlining. 2318Failure to inline such a function is diagnosed as an error. 2319Note that if such a function is called indirectly the compiler may 2320or may not inline it depending on optimization level and a failure 2321to inline an indirect call may or may not be diagnosed. 2322 2323@item gnu_inline 2324@cindex @code{gnu_inline} function attribute 2325This attribute should be used with a function that is also declared 2326with the @code{inline} keyword. It directs GCC to treat the function 2327as if it were defined in gnu90 mode even when compiling in C99 or 2328gnu99 mode. 2329 2330If the function is declared @code{extern}, then this definition of the 2331function is used only for inlining. In no case is the function 2332compiled as a standalone function, not even if you take its address 2333explicitly. Such an address becomes an external reference, as if you 2334had only declared the function, and had not defined it. This has 2335almost the effect of a macro. The way to use this is to put a 2336function definition in a header file with this attribute, and put 2337another copy of the function, without @code{extern}, in a library 2338file. The definition in the header file causes most calls to the 2339function to be inlined. If any uses of the function remain, they 2340refer to the single copy in the library. Note that the two 2341definitions of the functions need not be precisely the same, although 2342if they do not have the same effect your program may behave oddly. 2343 2344In C, if the function is neither @code{extern} nor @code{static}, then 2345the function is compiled as a standalone function, as well as being 2346inlined where possible. 2347 2348This is how GCC traditionally handled functions declared 2349@code{inline}. Since ISO C99 specifies a different semantics for 2350@code{inline}, this function attribute is provided as a transition 2351measure and as a useful feature in its own right. This attribute is 2352available in GCC 4.1.3 and later. It is available if either of the 2353preprocessor macros @code{__GNUC_GNU_INLINE__} or 2354@code{__GNUC_STDC_INLINE__} are defined. @xref{Inline,,An Inline 2355Function is As Fast As a Macro}. 2356 2357In C++, this attribute does not depend on @code{extern} in any way, 2358but it still requires the @code{inline} keyword to enable its special 2359behavior. 2360 2361@item artificial 2362@cindex @code{artificial} function attribute 2363This attribute is useful for small inline wrappers that if possible 2364should appear during debugging as a unit. Depending on the debug 2365info format it either means marking the function as artificial 2366or using the caller location for all instructions within the inlined 2367body. 2368 2369@item bank_switch 2370@cindex @code{bank_switch} function attribute, M32C 2371When added to an interrupt handler with the M32C port, causes the 2372prologue and epilogue to use bank switching to preserve the registers 2373rather than saving them on the stack. 2374 2375@item flatten 2376@cindex @code{flatten} function attribute 2377Generally, inlining into a function is limited. For a function marked with 2378this attribute, every call inside this function is inlined, if possible. 2379Whether the function itself is considered for inlining depends on its size and 2380the current inlining parameters. 2381 2382@item error ("@var{message}") 2383@cindex @code{error} function attribute 2384If this attribute is used on a function declaration and a call to such a function 2385is not eliminated through dead code elimination or other optimizations, an error 2386that includes @var{message} is diagnosed. This is useful 2387for compile-time checking, especially together with @code{__builtin_constant_p} 2388and inline functions where checking the inline function arguments is not 2389possible through @code{extern char [(condition) ? 1 : -1];} tricks. 2390While it is possible to leave the function undefined and thus invoke 2391a link failure, when using this attribute the problem is diagnosed 2392earlier and with exact location of the call even in presence of inline 2393functions or when not emitting debugging information. 2394 2395@item warning ("@var{message}") 2396@cindex @code{warning} function attribute 2397If this attribute is used on a function declaration and a call to such a function 2398is not eliminated through dead code elimination or other optimizations, a warning 2399that includes @var{message} is diagnosed. This is useful 2400for compile-time checking, especially together with @code{__builtin_constant_p} 2401and inline functions. While it is possible to define the function with 2402a message in @code{.gnu.warning*} section, when using this attribute the problem 2403is diagnosed earlier and with exact location of the call even in presence 2404of inline functions or when not emitting debugging information. 2405 2406@item cdecl 2407@cindex @code{cdecl} function attribute, x86-32 2408@cindex functions that do pop the argument stack on x86-32 2409@opindex mrtd 2410On the x86-32 targets, the @code{cdecl} attribute causes the compiler to 2411assume that the calling function pops off the stack space used to 2412pass arguments. This is 2413useful to override the effects of the @option{-mrtd} switch. 2414 2415@item const 2416@cindex @code{const} function attribute 2417Many functions do not examine any values except their arguments, and 2418have no effects except the return value. Basically this is just slightly 2419more strict class than the @code{pure} attribute below, since function is not 2420allowed to read global memory. 2421 2422@cindex pointer arguments 2423Note that a function that has pointer arguments and examines the data 2424pointed to must @emph{not} be declared @code{const}. Likewise, a 2425function that calls a non-@code{const} function usually must not be 2426@code{const}. It does not make sense for a @code{const} function to 2427return @code{void}. 2428 2429@item constructor 2430@itemx destructor 2431@itemx constructor (@var{priority}) 2432@itemx destructor (@var{priority}) 2433@cindex @code{constructor} function attribute 2434@cindex @code{destructor} function attribute 2435The @code{constructor} attribute causes the function to be called 2436automatically before execution enters @code{main ()}. Similarly, the 2437@code{destructor} attribute causes the function to be called 2438automatically after @code{main ()} completes or @code{exit ()} is 2439called. Functions with these attributes are useful for 2440initializing data that is used implicitly during the execution of 2441the program. 2442 2443You may provide an optional integer priority to control the order in 2444which constructor and destructor functions are run. A constructor 2445with a smaller priority number runs before a constructor with a larger 2446priority number; the opposite relationship holds for destructors. So, 2447if you have a constructor that allocates a resource and a destructor 2448that deallocates the same resource, both functions typically have the 2449same priority. The priorities for constructor and destructor 2450functions are the same as those specified for namespace-scope C++ 2451objects (@pxref{C++ Attributes}). 2452 2453These attributes are not currently implemented for Objective-C@. 2454 2455@item deprecated 2456@itemx deprecated (@var{msg}) 2457@cindex @code{deprecated} function attribute 2458The @code{deprecated} attribute results in a warning if the function 2459is used anywhere in the source file. This is useful when identifying 2460functions that are expected to be removed in a future version of a 2461program. The warning also includes the location of the declaration 2462of the deprecated function, to enable users to easily find further 2463information about why the function is deprecated, or what they should 2464do instead. Note that the warnings only occurs for uses: 2465 2466@smallexample 2467int old_fn () __attribute__ ((deprecated)); 2468int old_fn (); 2469int (*fn_ptr)() = old_fn; 2470@end smallexample 2471 2472@noindent 2473results in a warning on line 3 but not line 2. The optional @var{msg} 2474argument, which must be a string, is printed in the warning if 2475present. 2476 2477The @code{deprecated} attribute can also be used for variables and 2478types (@pxref{Variable Attributes}, @pxref{Type Attributes}.) 2479 2480@item disinterrupt 2481@cindex @code{disinterrupt} function attribute, Epiphany 2482@cindex @code{disinterrupt} function attribute, MeP 2483On Epiphany and MeP targets, this attribute causes the compiler to emit 2484instructions to disable interrupts for the duration of the given 2485function. 2486 2487@item dllexport 2488@cindex @code{dllexport} function attribute 2489@cindex @code{__declspec(dllexport)} 2490On Microsoft Windows targets and Symbian OS targets the 2491@code{dllexport} attribute causes the compiler to provide a global 2492pointer to a pointer in a DLL, so that it can be referenced with the 2493@code{dllimport} attribute. On Microsoft Windows targets, the pointer 2494name is formed by combining @code{_imp__} and the function or variable 2495name. 2496 2497You can use @code{__declspec(dllexport)} as a synonym for 2498@code{__attribute__ ((dllexport))} for compatibility with other 2499compilers. 2500 2501On systems that support the @code{visibility} attribute, this 2502attribute also implies ``default'' visibility. It is an error to 2503explicitly specify any other visibility. 2504 2505GCC's default behavior is to emit all inline functions with the 2506@code{dllexport} attribute. Since this can cause object file-size bloat, 2507you can use @option{-fno-keep-inline-dllexport}, which tells GCC to 2508ignore the attribute for inlined functions unless the 2509@option{-fkeep-inline-functions} flag is used instead. 2510 2511The attribute is ignored for undefined symbols. 2512 2513When applied to C++ classes, the attribute marks defined non-inlined 2514member functions and static data members as exports. Static consts 2515initialized in-class are not marked unless they are also defined 2516out-of-class. 2517 2518For Microsoft Windows targets there are alternative methods for 2519including the symbol in the DLL's export table such as using a 2520@file{.def} file with an @code{EXPORTS} section or, with GNU ld, using 2521the @option{--export-all} linker flag. 2522 2523@item dllimport 2524@cindex @code{dllimport} function attribute 2525@cindex @code{__declspec(dllimport)} 2526On Microsoft Windows and Symbian OS targets, the @code{dllimport} 2527attribute causes the compiler to reference a function or variable via 2528a global pointer to a pointer that is set up by the DLL exporting the 2529symbol. The attribute implies @code{extern}. On Microsoft Windows 2530targets, the pointer name is formed by combining @code{_imp__} and the 2531function or variable name. 2532 2533You can use @code{__declspec(dllimport)} as a synonym for 2534@code{__attribute__ ((dllimport))} for compatibility with other 2535compilers. 2536 2537On systems that support the @code{visibility} attribute, this 2538attribute also implies ``default'' visibility. It is an error to 2539explicitly specify any other visibility. 2540 2541Currently, the attribute is ignored for inlined functions. If the 2542attribute is applied to a symbol @emph{definition}, an error is reported. 2543If a symbol previously declared @code{dllimport} is later defined, the 2544attribute is ignored in subsequent references, and a warning is emitted. 2545The attribute is also overridden by a subsequent declaration as 2546@code{dllexport}. 2547 2548When applied to C++ classes, the attribute marks non-inlined 2549member functions and static data members as imports. However, the 2550attribute is ignored for virtual methods to allow creation of vtables 2551using thunks. 2552 2553On the SH Symbian OS target the @code{dllimport} attribute also has 2554another affect---it can cause the vtable and run-time type information 2555for a class to be exported. This happens when the class has a 2556dllimported constructor or a non-inline, non-pure virtual function 2557and, for either of those two conditions, the class also has an inline 2558constructor or destructor and has a key function that is defined in 2559the current translation unit. 2560 2561For Microsoft Windows targets the use of the @code{dllimport} 2562attribute on functions is not necessary, but provides a small 2563performance benefit by eliminating a thunk in the DLL@. The use of the 2564@code{dllimport} attribute on imported variables can be avoided by passing the 2565@option{--enable-auto-import} switch to the GNU linker. As with 2566functions, using the attribute for a variable eliminates a thunk in 2567the DLL@. 2568 2569One drawback to using this attribute is that a pointer to a 2570@emph{variable} marked as @code{dllimport} cannot be used as a constant 2571address. However, a pointer to a @emph{function} with the 2572@code{dllimport} attribute can be used as a constant initializer; in 2573this case, the address of a stub function in the import lib is 2574referenced. On Microsoft Windows targets, the attribute can be disabled 2575for functions by setting the @option{-mnop-fun-dllimport} flag. 2576 2577@item exception 2578@cindex @code{exception} function attribute 2579@cindex exception handler functions, NDS32 2580Use this attribute on the NDS32 target to indicate that the specified function 2581is an exception handler. The compiler will generate corresponding sections 2582for use in an exception handler. 2583 2584@item exception_handler 2585@cindex @code{exception_handler} function attribute 2586@cindex exception handler functions, Blackfin 2587Use this attribute on the Blackfin to indicate that the specified function 2588is an exception handler. The compiler generates function entry and 2589exit sequences suitable for use in an exception handler when this 2590attribute is present. 2591 2592@item externally_visible 2593@cindex @code{externally_visible} function attribute 2594This attribute, attached to a global variable or function, nullifies 2595the effect of the @option{-fwhole-program} command-line option, so the 2596object remains visible outside the current compilation unit. 2597 2598If @option{-fwhole-program} is used together with @option{-flto} and 2599@command{gold} is used as the linker plugin, 2600@code{externally_visible} attributes are automatically added to functions 2601(not variable yet due to a current @command{gold} issue) 2602that are accessed outside of LTO objects according to resolution file 2603produced by @command{gold}. 2604For other linkers that cannot generate resolution file, 2605explicit @code{externally_visible} attributes are still necessary. 2606 2607@item far 2608@cindex @code{far} function attribute 2609 2610On MeP targets this causes the compiler to use a calling convention 2611that assumes the called function is too far away for the built-in 2612addressing modes. 2613 2614@item fast_interrupt 2615@cindex @code{fast_interrupt} function attribute, M32C 2616@cindex @code{fast_interrupt} function attribute, RX 2617Use this attribute on the M32C and RX ports to indicate that the specified 2618function is a fast interrupt handler. This is just like the 2619@code{interrupt} attribute, except that @code{freit} is used to return 2620instead of @code{reit}. 2621 2622@item fastcall 2623@cindex @code{fastcall} function attribute, x86-32 2624@cindex functions that pop the argument stack on x86-32 2625On x86-32 targets, the @code{fastcall} attribute causes the compiler to 2626pass the first argument (if of integral type) in the register ECX and 2627the second argument (if of integral type) in the register EDX@. Subsequent 2628and other typed arguments are passed on the stack. The called function 2629pops the arguments off the stack. If the number of arguments is variable all 2630arguments are pushed on the stack. 2631 2632@item thiscall 2633@cindex @code{thiscall} function attribute, x86-32 2634@cindex functions that pop the argument stack on x86-32 2635On x86-32 targets, the @code{thiscall} attribute causes the compiler to 2636pass the first argument (if of integral type) in the register ECX. 2637Subsequent and other typed arguments are passed on the stack. The called 2638function pops the arguments off the stack. 2639If the number of arguments is variable all arguments are pushed on the 2640stack. 2641The @code{thiscall} attribute is intended for C++ non-static member functions. 2642As a GCC extension, this calling convention can be used for C functions 2643and for static member methods. 2644 2645@item format (@var{archetype}, @var{string-index}, @var{first-to-check}) 2646@cindex @code{format} function attribute 2647@opindex Wformat 2648The @code{format} attribute specifies that a function takes @code{printf}, 2649@code{scanf}, @code{strftime} or @code{strfmon} style arguments that 2650should be type-checked against a format string. For example, the 2651declaration: 2652 2653@smallexample 2654extern int 2655my_printf (void *my_object, const char *my_format, ...) 2656 __attribute__ ((format (printf, 2, 3))); 2657@end smallexample 2658 2659@noindent 2660causes the compiler to check the arguments in calls to @code{my_printf} 2661for consistency with the @code{printf} style format string argument 2662@code{my_format}. 2663 2664The parameter @var{archetype} determines how the format string is 2665interpreted, and should be @code{printf}, @code{scanf}, @code{strftime}, 2666@code{gnu_printf}, @code{gnu_scanf}, @code{gnu_strftime} or 2667@code{strfmon}. (You can also use @code{__printf__}, 2668@code{__scanf__}, @code{__strftime__} or @code{__strfmon__}.) On 2669MinGW targets, @code{ms_printf}, @code{ms_scanf}, and 2670@code{ms_strftime} are also present. 2671@var{archetype} values such as @code{printf} refer to the formats accepted 2672by the system's C runtime library, 2673while values prefixed with @samp{gnu_} always refer 2674to the formats accepted by the GNU C Library. On Microsoft Windows 2675targets, values prefixed with @samp{ms_} refer to the formats accepted by the 2676@file{msvcrt.dll} library. 2677The parameter @var{string-index} 2678specifies which argument is the format string argument (starting 2679from 1), while @var{first-to-check} is the number of the first 2680argument to check against the format string. For functions 2681where the arguments are not available to be checked (such as 2682@code{vprintf}), specify the third parameter as zero. In this case the 2683compiler only checks the format string for consistency. For 2684@code{strftime} formats, the third parameter is required to be zero. 2685Since non-static C++ methods have an implicit @code{this} argument, the 2686arguments of such methods should be counted from two, not one, when 2687giving values for @var{string-index} and @var{first-to-check}. 2688 2689In the example above, the format string (@code{my_format}) is the second 2690argument of the function @code{my_print}, and the arguments to check 2691start with the third argument, so the correct parameters for the format 2692attribute are 2 and 3. 2693 2694@opindex ffreestanding 2695@opindex fno-builtin 2696The @code{format} attribute allows you to identify your own functions 2697that take format strings as arguments, so that GCC can check the 2698calls to these functions for errors. The compiler always (unless 2699@option{-ffreestanding} or @option{-fno-builtin} is used) checks formats 2700for the standard library functions @code{printf}, @code{fprintf}, 2701@code{sprintf}, @code{scanf}, @code{fscanf}, @code{sscanf}, @code{strftime}, 2702@code{vprintf}, @code{vfprintf} and @code{vsprintf} whenever such 2703warnings are requested (using @option{-Wformat}), so there is no need to 2704modify the header file @file{stdio.h}. In C99 mode, the functions 2705@code{snprintf}, @code{vsnprintf}, @code{vscanf}, @code{vfscanf} and 2706@code{vsscanf} are also checked. Except in strictly conforming C 2707standard modes, the X/Open function @code{strfmon} is also checked as 2708are @code{printf_unlocked} and @code{fprintf_unlocked}. 2709@xref{C Dialect Options,,Options Controlling C Dialect}. 2710 2711For Objective-C dialects, @code{NSString} (or @code{__NSString__}) is 2712recognized in the same context. Declarations including these format attributes 2713are parsed for correct syntax, however the result of checking of such format 2714strings is not yet defined, and is not carried out by this version of the 2715compiler. 2716 2717The target may also provide additional types of format checks. 2718@xref{Target Format Checks,,Format Checks Specific to Particular 2719Target Machines}. 2720 2721@item format_arg (@var{string-index}) 2722@cindex @code{format_arg} function attribute 2723@opindex Wformat-nonliteral 2724The @code{format_arg} attribute specifies that a function takes a format 2725string for a @code{printf}, @code{scanf}, @code{strftime} or 2726@code{strfmon} style function and modifies it (for example, to translate 2727it into another language), so the result can be passed to a 2728@code{printf}, @code{scanf}, @code{strftime} or @code{strfmon} style 2729function (with the remaining arguments to the format function the same 2730as they would have been for the unmodified string). For example, the 2731declaration: 2732 2733@smallexample 2734extern char * 2735my_dgettext (char *my_domain, const char *my_format) 2736 __attribute__ ((format_arg (2))); 2737@end smallexample 2738 2739@noindent 2740causes the compiler to check the arguments in calls to a @code{printf}, 2741@code{scanf}, @code{strftime} or @code{strfmon} type function, whose 2742format string argument is a call to the @code{my_dgettext} function, for 2743consistency with the format string argument @code{my_format}. If the 2744@code{format_arg} attribute had not been specified, all the compiler 2745could tell in such calls to format functions would be that the format 2746string argument is not constant; this would generate a warning when 2747@option{-Wformat-nonliteral} is used, but the calls could not be checked 2748without the attribute. 2749 2750The parameter @var{string-index} specifies which argument is the format 2751string argument (starting from one). Since non-static C++ methods have 2752an implicit @code{this} argument, the arguments of such methods should 2753be counted from two. 2754 2755The @code{format_arg} attribute allows you to identify your own 2756functions that modify format strings, so that GCC can check the 2757calls to @code{printf}, @code{scanf}, @code{strftime} or @code{strfmon} 2758type function whose operands are a call to one of your own function. 2759The compiler always treats @code{gettext}, @code{dgettext}, and 2760@code{dcgettext} in this manner except when strict ISO C support is 2761requested by @option{-ansi} or an appropriate @option{-std} option, or 2762@option{-ffreestanding} or @option{-fno-builtin} 2763is used. @xref{C Dialect Options,,Options 2764Controlling C Dialect}. 2765 2766For Objective-C dialects, the @code{format-arg} attribute may refer to an 2767@code{NSString} reference for compatibility with the @code{format} attribute 2768above. 2769 2770The target may also allow additional types in @code{format-arg} attributes. 2771@xref{Target Format Checks,,Format Checks Specific to Particular 2772Target Machines}. 2773 2774@item function_vector 2775@cindex @code{function_vector} function attribute, H8/300 2776@cindex @code{function_vector} function attribute, M16C/M32C 2777@cindex @code{function_vector} function attribute, SH 2778@cindex calling functions through the function vector on H8/300, M16C, M32C and SH2A processors 2779Use this attribute on the H8/300, H8/300H, and H8S to indicate that the specified 2780function should be called through the function vector. Calling a 2781function through the function vector reduces code size, however; 2782the function vector has a limited size (maximum 128 entries on the H8/300 2783and 64 entries on the H8/300H and H8S) and shares space with the interrupt vector. 2784 2785On SH2A targets, this attribute declares a function to be called using the 2786TBR relative addressing mode. The argument to this attribute is the entry 2787number of the same function in a vector table containing all the TBR 2788relative addressable functions. For correct operation the TBR must be setup 2789accordingly to point to the start of the vector table before any functions with 2790this attribute are invoked. Usually a good place to do the initialization is 2791the startup routine. The TBR relative vector table can have at max 256 function 2792entries. The jumps to these functions are generated using a SH2A specific, 2793non delayed branch instruction JSR/N @@(disp8,TBR). You must use GAS and GLD 2794from GNU binutils version 2.7 or later for this attribute to work correctly. 2795 2796Please refer the example of M16C target, to see the use of this 2797attribute while declaring a function, 2798 2799In an application, for a function being called once, this attribute 2800saves at least 8 bytes of code; and if other successive calls are being 2801made to the same function, it saves 2 bytes of code per each of these 2802calls. 2803 2804On M16C/M32C targets, the @code{function_vector} attribute declares a 2805special page subroutine call function. Use of this attribute reduces 2806the code size by 2 bytes for each call generated to the 2807subroutine. The argument to the attribute is the vector number entry 2808from the special page vector table which contains the 16 low-order 2809bits of the subroutine's entry address. Each vector table has special 2810page number (18 to 255) that is used in @code{jsrs} instructions. 2811Jump addresses of the routines are generated by adding 0x0F0000 (in 2812case of M16C targets) or 0xFF0000 (in case of M32C targets), to the 28132-byte addresses set in the vector table. Therefore you need to ensure 2814that all the special page vector routines should get mapped within the 2815address range 0x0F0000 to 0x0FFFFF (for M16C) and 0xFF0000 to 0xFFFFFF 2816(for M32C). 2817 2818In the following example 2 bytes are saved for each call to 2819function @code{foo}. 2820 2821@smallexample 2822void foo (void) __attribute__((function_vector(0x18))); 2823void foo (void) 2824@{ 2825@} 2826 2827void bar (void) 2828@{ 2829 foo(); 2830@} 2831@end smallexample 2832 2833If functions are defined in one file and are called in another file, 2834then be sure to write this declaration in both files. 2835 2836This attribute is ignored for R8C target. 2837 2838@item ifunc ("@var{resolver}") 2839@cindex @code{ifunc} function attribute 2840The @code{ifunc} attribute is used to mark a function as an indirect 2841function using the STT_GNU_IFUNC symbol type extension to the ELF 2842standard. This allows the resolution of the symbol value to be 2843determined dynamically at load time, and an optimized version of the 2844routine can be selected for the particular processor or other system 2845characteristics determined then. To use this attribute, first define 2846the implementation functions available, and a resolver function that 2847returns a pointer to the selected implementation function. The 2848implementation functions' declarations must match the API of the 2849function being implemented, the resolver's declaration is be a 2850function returning pointer to void function returning void: 2851 2852@smallexample 2853void *my_memcpy (void *dst, const void *src, size_t len) 2854@{ 2855 @dots{} 2856@} 2857 2858static void (*resolve_memcpy (void)) (void) 2859@{ 2860 return my_memcpy; // we'll just always select this routine 2861@} 2862@end smallexample 2863 2864@noindent 2865The exported header file declaring the function the user calls would 2866contain: 2867 2868@smallexample 2869extern void *memcpy (void *, const void *, size_t); 2870@end smallexample 2871 2872@noindent 2873allowing the user to call this as a regular function, unaware of the 2874implementation. Finally, the indirect function needs to be defined in 2875the same translation unit as the resolver function: 2876 2877@smallexample 2878void *memcpy (void *, const void *, size_t) 2879 __attribute__ ((ifunc ("resolve_memcpy"))); 2880@end smallexample 2881 2882Indirect functions cannot be weak. Binutils version 2.20.1 or higher 2883and GNU C Library version 2.11.1 are required to use this feature. 2884 2885@item interrupt 2886@cindex @code{interrupt} function attribute, ARC 2887@cindex @code{interrupt} function attribute, ARM 2888@cindex @code{interrupt} function attribute, AVR 2889@cindex @code{interrupt} function attribute, CR16 2890@cindex @code{interrupt} function attribute, Epiphany 2891@cindex @code{interrupt} function attribute, M32C 2892@cindex @code{interrupt} function attribute, M32R/D 2893@cindex @code{interrupt} function attribute, m68k 2894@cindex @code{interrupt} function attribute, MeP 2895@cindex @code{interrupt} function attribute, MIPS 2896@cindex @code{interrupt} function attribute, MSP430 2897@cindex @code{interrupt} function attribute, NDS32 2898@cindex @code{interrupt} function attribute, RL78 2899@cindex @code{interrupt} function attribute, RX 2900@cindex @code{interrupt} function attribute, Visium 2901@cindex @code{interrupt} function attribute, Xstormy16 2902Use this attribute on the ARC, ARM, AVR, CR16, Epiphany, M32C, M32R/D, 2903m68k, MeP, MIPS, MSP430, NDS32, RL78, RX, Visium and Xstormy16 ports to indicate 2904that the specified function is an interrupt handler. The compiler generates 2905function entry and exit sequences suitable for use in an interrupt handler 2906when this attribute is present. With Epiphany targets it may also generate 2907a special section with code to initialize the interrupt vector table. 2908 2909Note, interrupt handlers for the Blackfin, H8/300, H8/300H, H8S, MicroBlaze, 2910and SH processors can be specified via the @code{interrupt_handler} attribute. 2911 2912Note, on the ARC, you must specify the kind of interrupt to be handled 2913in a parameter to the interrupt attribute like this: 2914 2915@smallexample 2916void f () __attribute__ ((interrupt ("ilink1"))); 2917@end smallexample 2918 2919Permissible values for this parameter are: @w{@code{ilink1}} and 2920@w{@code{ilink2}}. 2921 2922Note, on the AVR, the hardware globally disables interrupts when an 2923interrupt is executed. The first instruction of an interrupt handler 2924declared with this attribute is a @code{SEI} instruction to 2925re-enable interrupts. See also the @code{signal} function attribute 2926that does not insert a @code{SEI} instruction. If both @code{signal} and 2927@code{interrupt} are specified for the same function, @code{signal} 2928is silently ignored. 2929 2930Note, for the ARM, you can specify the kind of interrupt to be handled by 2931adding an optional parameter to the interrupt attribute like this: 2932 2933@smallexample 2934void f () __attribute__ ((interrupt ("IRQ"))); 2935@end smallexample 2936 2937@noindent 2938Permissible values for this parameter are: @code{IRQ}, @code{FIQ}, 2939@code{SWI}, @code{ABORT} and @code{UNDEF}. 2940 2941On ARMv7-M the interrupt type is ignored, and the attribute means the function 2942may be called with a word-aligned stack pointer. 2943 2944Note, for the MSP430 you can provide an argument to the interrupt 2945attribute which specifies a name or number. If the argument is a 2946number it indicates the slot in the interrupt vector table (0 - 31) to 2947which this handler should be assigned. If the argument is a name it 2948is treated as a symbolic name for the vector slot. These names should 2949match up with appropriate entries in the linker script. By default 2950the names @code{watchdog} for vector 26, @code{nmi} for vector 30 and 2951@code{reset} for vector 31 are recognized. 2952 2953You can also use the following function attributes to modify how 2954normal functions interact with interrupt functions: 2955 2956@table @code 2957@item critical 2958@cindex @code{critical} function attribute, MSP430 2959Critical functions disable interrupts upon entry and restore the 2960previous interrupt state upon exit. Critical functions cannot also 2961have the @code{naked} or @code{reentrant} attributes. They can have 2962the @code{interrupt} attribute. 2963 2964@item reentrant 2965@cindex @code{reentrant} function attribute, MSP430 2966Reentrant functions disable interrupts upon entry and enable them 2967upon exit. Reentrant functions cannot also have the @code{naked} 2968or @code{critical} attributes. They can have the @code{interrupt} 2969attribute. 2970 2971@item wakeup 2972@cindex @code{wakeup} function attribute, MSP430 2973This attribute only applies to interrupt functions. It is silently 2974ignored if applied to a non-interrupt function. A wakeup interrupt 2975function will rouse the processor from any low-power state that it 2976might be in when the function exits. 2977 2978@end table 2979 2980On Epiphany targets one or more optional parameters can be added like this: 2981 2982@smallexample 2983void __attribute__ ((interrupt ("dma0, dma1"))) universal_dma_handler (); 2984@end smallexample 2985 2986Permissible values for these parameters are: @w{@code{reset}}, 2987@w{@code{software_exception}}, @w{@code{page_miss}}, 2988@w{@code{timer0}}, @w{@code{timer1}}, @w{@code{message}}, 2989@w{@code{dma0}}, @w{@code{dma1}}, @w{@code{wand}} and @w{@code{swi}}. 2990Multiple parameters indicate that multiple entries in the interrupt 2991vector table should be initialized for this function, i.e.@: for each 2992parameter @w{@var{name}}, a jump to the function is emitted in 2993the section @w{ivt_entry_@var{name}}. The parameter(s) may be omitted 2994entirely, in which case no interrupt vector table entry is provided. 2995 2996Note, on Epiphany targets, interrupts are enabled inside the function 2997unless the @code{disinterrupt} attribute is also specified. 2998 2999On Epiphany targets, you can also use the following attribute to 3000modify the behavior of an interrupt handler: 3001@table @code 3002@item forwarder_section 3003@cindex @code{forwarder_section} function attribute, Epiphany 3004The interrupt handler may be in external memory which cannot be 3005reached by a branch instruction, so generate a local memory trampoline 3006to transfer control. The single parameter identifies the section where 3007the trampoline is placed. 3008@end table 3009 3010The following examples are all valid uses of these attributes on 3011Epiphany targets: 3012@smallexample 3013void __attribute__ ((interrupt)) universal_handler (); 3014void __attribute__ ((interrupt ("dma1"))) dma1_handler (); 3015void __attribute__ ((interrupt ("dma0, dma1"))) universal_dma_handler (); 3016void __attribute__ ((interrupt ("timer0"), disinterrupt)) 3017 fast_timer_handler (); 3018void __attribute__ ((interrupt ("dma0, dma1"), forwarder_section ("tramp"))) 3019 external_dma_handler (); 3020@end smallexample 3021 3022On MIPS targets, you can use the following attributes to modify the behavior 3023of an interrupt handler: 3024@table @code 3025@item use_shadow_register_set 3026@cindex @code{use_shadow_register_set} function attribute, MIPS 3027Assume that the handler uses a shadow register set, instead of 3028the main general-purpose registers. 3029 3030@item keep_interrupts_masked 3031@cindex @code{keep_interrupts_masked} function attribute, MIPS 3032Keep interrupts masked for the whole function. Without this attribute, 3033GCC tries to reenable interrupts for as much of the function as it can. 3034 3035@item use_debug_exception_return 3036@cindex @code{use_debug_exception_return} function attribute, MIPS 3037Return using the @code{deret} instruction. Interrupt handlers that don't 3038have this attribute return using @code{eret} instead. 3039@end table 3040 3041You can use any combination of these attributes, as shown below: 3042@smallexample 3043void __attribute__ ((interrupt)) v0 (); 3044void __attribute__ ((interrupt, use_shadow_register_set)) v1 (); 3045void __attribute__ ((interrupt, keep_interrupts_masked)) v2 (); 3046void __attribute__ ((interrupt, use_debug_exception_return)) v3 (); 3047void __attribute__ ((interrupt, use_shadow_register_set, 3048 keep_interrupts_masked)) v4 (); 3049void __attribute__ ((interrupt, use_shadow_register_set, 3050 use_debug_exception_return)) v5 (); 3051void __attribute__ ((interrupt, keep_interrupts_masked, 3052 use_debug_exception_return)) v6 (); 3053void __attribute__ ((interrupt, use_shadow_register_set, 3054 keep_interrupts_masked, 3055 use_debug_exception_return)) v7 (); 3056@end smallexample 3057 3058On NDS32 target, this attribute indicates that the specified function 3059is an interrupt handler. The compiler generates corresponding sections 3060for use in an interrupt handler. You can use the following attributes 3061to modify the behavior: 3062@table @code 3063@item nested 3064@cindex @code{nested} function attribute, NDS32 3065This interrupt service routine is interruptible. 3066@item not_nested 3067@cindex @code{not_nested} function attribute, NDS32 3068This interrupt service routine is not interruptible. 3069@item nested_ready 3070@cindex @code{nested_ready} function attribute, NDS32 3071This interrupt service routine is interruptible after @code{PSW.GIE} 3072(global interrupt enable) is set. This allows interrupt service routine to 3073finish some short critical code before enabling interrupts. 3074@item save_all 3075@cindex @code{save_all} function attribute, NDS32 3076The system will help save all registers into stack before entering 3077interrupt handler. 3078@item partial_save 3079@cindex @code{partial_save} function attribute, NDS32 3080The system will help save caller registers into stack before entering 3081interrupt handler. 3082@end table 3083 3084@cindex @code{brk_interrupt} function attribute, RL78 3085On RL78, use @code{brk_interrupt} instead of @code{interrupt} for 3086handlers intended to be used with the @code{BRK} opcode (i.e.@: those 3087that must end with @code{RETB} instead of @code{RETI}). 3088 3089On RX targets, you may specify one or more vector numbers as arguments 3090to the attribute, as well as naming an alternate table name. 3091Parameters are handled sequentially, so one handler can be assigned to 3092multiple entries in multiple tables. One may also pass the magic 3093string @code{"$default"} which causes the function to be used for any 3094unfilled slots in the current table. 3095 3096This example shows a simple assignment of a function to one vector in 3097the default table (note that preprocessor macros may be used for 3098chip-specific symbolic vector names): 3099@smallexample 3100void __attribute__ ((interrupt (5))) txd1_handler (); 3101@end smallexample 3102 3103This example assigns a function to two slots in the default table 3104(using preprocessor macros defined elsewhere) and makes it the default 3105for the @code{dct} table: 3106@smallexample 3107void __attribute__ ((interrupt (RXD1_VECT,RXD2_VECT,"dct","$default"))) 3108 txd1_handler (); 3109@end smallexample 3110 3111@item interrupt_handler 3112@cindex @code{interrupt_handler} function attribute, Blackfin 3113@cindex @code{interrupt_handler} function attribute, m68k 3114@cindex @code{interrupt_handler} function attribute, H8/300 3115@cindex @code{interrupt_handler} function attribute, SH 3116Use this attribute on the Blackfin, m68k, H8/300, H8/300H, H8S, and SH to 3117indicate that the specified function is an interrupt handler. The compiler 3118generates function entry and exit sequences suitable for use in an 3119interrupt handler when this attribute is present. 3120 3121@item interrupt_thread 3122@cindex @code{interrupt_thread} function attribute, fido 3123Use this attribute on fido, a subarchitecture of the m68k, to indicate 3124that the specified function is an interrupt handler that is designed 3125to run as a thread. The compiler omits generate prologue/epilogue 3126sequences and replaces the return instruction with a @code{sleep} 3127instruction. This attribute is available only on fido. 3128 3129@item isr 3130@cindex @code{isr} function attribute, ARM 3131Use this attribute on ARM to write Interrupt Service Routines. This is an 3132alias to the @code{interrupt} attribute above. 3133 3134@item kspisusp 3135@cindex @code{kspisusp} function attribute, Blackfin 3136@cindex User stack pointer in interrupts on the Blackfin 3137When used together with @code{interrupt_handler}, @code{exception_handler} 3138or @code{nmi_handler}, code is generated to load the stack pointer 3139from the USP register in the function prologue. 3140 3141@item l1_text 3142@cindex @code{l1_text} function attribute, Blackfin 3143This attribute specifies a function to be placed into L1 Instruction 3144SRAM@. The function is put into a specific section named @code{.l1.text}. 3145With @option{-mfdpic}, function calls with a such function as the callee 3146or caller uses inlined PLT. 3147 3148@item l2 3149@cindex @code{l2} function attribute, Blackfin 3150On the Blackfin, this attribute specifies a function to be placed into L2 3151SRAM. The function is put into a specific section named 3152@code{.l1.text}. With @option{-mfdpic}, callers of such functions use 3153an inlined PLT. 3154 3155@item leaf 3156@cindex @code{leaf} function attribute 3157Calls to external functions with this attribute must return to the current 3158compilation unit only by return or by exception handling. In particular, leaf 3159functions are not allowed to call callback function passed to it from the current 3160compilation unit or directly call functions exported by the unit or longjmp 3161into the unit. Leaf function might still call functions from other compilation 3162units and thus they are not necessarily leaf in the sense that they contain no 3163function calls at all. 3164 3165The attribute is intended for library functions to improve dataflow analysis. 3166The compiler takes the hint that any data not escaping the current compilation unit can 3167not be used or modified by the leaf function. For example, the @code{sin} function 3168is a leaf function, but @code{qsort} is not. 3169 3170Note that leaf functions might invoke signals and signal handlers might be 3171defined in the current compilation unit and use static variables. The only 3172compliant way to write such a signal handler is to declare such variables 3173@code{volatile}. 3174 3175The attribute has no effect on functions defined within the current compilation 3176unit. This is to allow easy merging of multiple compilation units into one, 3177for example, by using the link-time optimization. For this reason the 3178attribute is not allowed on types to annotate indirect calls. 3179 3180@item long_call 3181@itemx medium_call 3182@itemx short_call 3183@cindex @code{long_call} function attribute, ARC 3184@cindex @code{long_call} function attribute, ARM 3185@cindex @code{long_call} function attribute, Epiphany 3186@cindex @code{medium_call} function attribute, ARC 3187@cindex @code{short_call} function attribute, ARC 3188@cindex @code{short_call} function attribute, ARM 3189@cindex @code{short_call} function attribute, Epiphany 3190@cindex indirect calls, ARC 3191@cindex indirect calls, ARM 3192@cindex indirect calls, Epiphany 3193These attributes specify how a particular function is called on 3194ARC, ARM and Epiphany - with @code{medium_call} being specific to ARC. 3195These attributes override the 3196@option{-mlong-calls} (@pxref{ARM Options} and @ref{ARC Options}) 3197and @option{-mmedium-calls} (@pxref{ARC Options}) 3198command-line switches and @code{#pragma long_calls} settings. For ARM, the 3199@code{long_call} attribute indicates that the function might be far 3200away from the call site and require a different (more expensive) 3201calling sequence. The @code{short_call} attribute always places 3202the offset to the function from the call site into the @samp{BL} 3203instruction directly. 3204 3205For ARC, a function marked with the @code{long_call} attribute is 3206always called using register-indirect jump-and-link instructions, 3207thereby enabling the called function to be placed anywhere within the 320832-bit address space. A function marked with the @code{medium_call} 3209attribute will always be close enough to be called with an unconditional 3210branch-and-link instruction, which has a 25-bit offset from 3211the call site. A function marked with the @code{short_call} 3212attribute will always be close enough to be called with a conditional 3213branch-and-link instruction, which has a 21-bit offset from 3214the call site. 3215 3216@item longcall 3217@itemx shortcall 3218@cindex indirect calls, Blackfin 3219@cindex indirect calls, PowerPC 3220@cindex @code{longcall} function attribute, Blackfin 3221@cindex @code{longcall} function attribute, PowerPC 3222@cindex @code{shortcall} function attribute, Blackfin 3223@cindex @code{shortcall} function attribute, PowerPC 3224On Blackfin and PowerPC, the @code{longcall} attribute 3225indicates that the function might be far away from the call site and 3226require a different (more expensive) calling sequence. The 3227@code{shortcall} attribute indicates that the function is always close 3228enough for the shorter calling sequence to be used. These attributes 3229override both the @option{-mlongcall} switch and, on the RS/6000 and 3230PowerPC, the @code{#pragma longcall} setting. 3231 3232@xref{RS/6000 and PowerPC Options}, for more information on whether long 3233calls are necessary. 3234 3235@item long_call 3236@itemx near 3237@itemx far 3238@cindex indirect calls, MIPS 3239@cindex @code{long_call} function attribute, MIPS 3240@cindex @code{near} function attribute, MIPS 3241@cindex @code{far} function attribute, MIPS 3242These attributes specify how a particular function is called on MIPS@. 3243The attributes override the @option{-mlong-calls} (@pxref{MIPS Options}) 3244command-line switch. The @code{long_call} and @code{far} attributes are 3245synonyms, and cause the compiler to always call 3246the function by first loading its address into a register, and then using 3247the contents of that register. The @code{near} attribute has the opposite 3248effect; it specifies that non-PIC calls should be made using the more 3249efficient @code{jal} instruction. 3250 3251@item malloc 3252@cindex @code{malloc} function attribute 3253This tells the compiler that a function is @code{malloc}-like, i.e., 3254that the pointer @var{P} returned by the function cannot alias any 3255other pointer valid when the function returns, and moreover no 3256pointers to valid objects occur in any storage addressed by @var{P}. 3257 3258Using this attribute can improve optimization. Functions like 3259@code{malloc} and @code{calloc} have this property because they return 3260a pointer to uninitialized or zeroed-out storage. However, functions 3261like @code{realloc} do not have this property, as they can return a 3262pointer to storage containing pointers. 3263 3264@item mips16 3265@itemx nomips16 3266@cindex @code{mips16} function attribute, MIPS 3267@cindex @code{nomips16} function attribute, MIPS 3268 3269On MIPS targets, you can use the @code{mips16} and @code{nomips16} 3270function attributes to locally select or turn off MIPS16 code generation. 3271A function with the @code{mips16} attribute is emitted as MIPS16 code, 3272while MIPS16 code generation is disabled for functions with the 3273@code{nomips16} attribute. These attributes override the 3274@option{-mips16} and @option{-mno-mips16} options on the command line 3275(@pxref{MIPS Options}). 3276 3277When compiling files containing mixed MIPS16 and non-MIPS16 code, the 3278preprocessor symbol @code{__mips16} reflects the setting on the command line, 3279not that within individual functions. Mixed MIPS16 and non-MIPS16 code 3280may interact badly with some GCC extensions such as @code{__builtin_apply} 3281(@pxref{Constructing Calls}). 3282 3283@item micromips, MIPS 3284@itemx nomicromips, MIPS 3285@cindex @code{micromips} function attribute 3286@cindex @code{nomicromips} function attribute 3287 3288On MIPS targets, you can use the @code{micromips} and @code{nomicromips} 3289function attributes to locally select or turn off microMIPS code generation. 3290A function with the @code{micromips} attribute is emitted as microMIPS code, 3291while microMIPS code generation is disabled for functions with the 3292@code{nomicromips} attribute. These attributes override the 3293@option{-mmicromips} and @option{-mno-micromips} options on the command line 3294(@pxref{MIPS Options}). 3295 3296When compiling files containing mixed microMIPS and non-microMIPS code, the 3297preprocessor symbol @code{__mips_micromips} reflects the setting on the 3298command line, 3299not that within individual functions. Mixed microMIPS and non-microMIPS code 3300may interact badly with some GCC extensions such as @code{__builtin_apply} 3301(@pxref{Constructing Calls}). 3302 3303@item model (@var{model-name}) 3304@cindex @code{model} function attribute, M32R/D 3305@cindex function addressability on the M32R/D 3306 3307On the M32R/D, use this attribute to set the addressability of an 3308object, and of the code generated for a function. The identifier 3309@var{model-name} is one of @code{small}, @code{medium}, or 3310@code{large}, representing each of the code models. 3311 3312Small model objects live in the lower 16MB of memory (so that their 3313addresses can be loaded with the @code{ld24} instruction), and are 3314callable with the @code{bl} instruction. 3315 3316Medium model objects may live anywhere in the 32-bit address space (the 3317compiler generates @code{seth/add3} instructions to load their addresses), 3318and are callable with the @code{bl} instruction. 3319 3320Large model objects may live anywhere in the 32-bit address space (the 3321compiler generates @code{seth/add3} instructions to load their addresses), 3322and may not be reachable with the @code{bl} instruction (the compiler 3323generates the much slower @code{seth/add3/jl} instruction sequence). 3324 3325@item ms_abi 3326@itemx sysv_abi 3327@cindex @code{ms_abi} function attribute, x86 3328@cindex @code{sysv_abi} function attribute, x86 3329 3330On 32-bit and 64-bit x86 targets, you can use an ABI attribute 3331to indicate which calling convention should be used for a function. The 3332@code{ms_abi} attribute tells the compiler to use the Microsoft ABI, 3333while the @code{sysv_abi} attribute tells the compiler to use the ABI 3334used on GNU/Linux and other systems. The default is to use the Microsoft ABI 3335when targeting Windows. On all other systems, the default is the x86/AMD ABI. 3336 3337Note, the @code{ms_abi} attribute for Microsoft Windows 64-bit targets currently 3338requires the @option{-maccumulate-outgoing-args} option. 3339 3340@item callee_pop_aggregate_return (@var{number}) 3341@cindex @code{callee_pop_aggregate_return} function attribute, x86 3342 3343On x86-32 targets, you can use this attribute to control how 3344aggregates are returned in memory. If the caller is responsible for 3345popping the hidden pointer together with the rest of the arguments, specify 3346@var{number} equal to zero. If callee is responsible for popping the 3347hidden pointer, specify @var{number} equal to one. 3348 3349The default x86-32 ABI assumes that the callee pops the 3350stack for hidden pointer. However, on x86-32 Microsoft Windows targets, 3351the compiler assumes that the 3352caller pops the stack for hidden pointer. 3353 3354@item ms_hook_prologue 3355@cindex @code{ms_hook_prologue} function attribute, x86 3356 3357On 32-bit and 64-bit x86 targets, you can use 3358this function attribute to make GCC generate the ``hot-patching'' function 3359prologue used in Win32 API functions in Microsoft Windows XP Service Pack 2 3360and newer. 3361 3362@item hotpatch (@var{halfwords-before-function-label},@var{halfwords-after-function-label}) 3363@cindex @code{hotpatch} function attribute, S/390 3364 3365On S/390 System z targets, you can use this function attribute to 3366make GCC generate a ``hot-patching'' function prologue. If the 3367@option{-mhotpatch=} command-line option is used at the same time, 3368the @code{hotpatch} attribute takes precedence. The first of the 3369two arguments specifies the number of halfwords to be added before 3370the function label. A second argument can be used to specify the 3371number of halfwords to be added after the function label. For 3372both arguments the maximum allowed value is 1000000. 3373 3374If both arguments are zero, hotpatching is disabled. 3375 3376@item naked 3377@cindex @code{naked} function attribute, ARM 3378@cindex @code{naked} function attribute, AVR 3379@cindex @code{naked} function attribute, MCORE 3380@cindex @code{naked} function attribute, MSP430 3381@cindex @code{naked} function attribute, NDS32 3382@cindex @code{naked} function attribute, RL78 3383@cindex @code{naked} function attribute, RX 3384@cindex @code{naked} function attribute, SPU 3385@cindex function without prologue/epilogue code 3386This attribute is available on the ARM, AVR, MCORE, MSP430, NDS32, 3387RL78, RX and SPU ports. It allows the compiler to construct the 3388requisite function declaration, while allowing the body of the 3389function to be assembly code. The specified function will not have 3390prologue/epilogue sequences generated by the compiler. Only basic 3391@code{asm} statements can safely be included in naked functions 3392(@pxref{Basic Asm}). While using extended @code{asm} or a mixture of 3393basic @code{asm} and C code may appear to work, they cannot be 3394depended upon to work reliably and are not supported. 3395 3396@item near 3397@cindex @code{near} function attribute, MeP 3398@cindex functions that do not handle memory bank switching on 68HC11/68HC12 3399On MeP targets this attribute causes the compiler to assume the called 3400function is close enough to use the normal calling convention, 3401overriding the @option{-mtf} command-line option. 3402 3403@item nesting 3404@cindex @code{nesting} function attribute, Blackfin 3405@cindex Allow nesting in an interrupt handler on the Blackfin processor 3406Use this attribute together with @code{interrupt_handler}, 3407@code{exception_handler} or @code{nmi_handler} to indicate that the function 3408entry code should enable nested interrupts or exceptions. 3409 3410@item nmi_handler 3411@cindex @code{nmi_handler} function attribute, Blackfin 3412@cindex NMI handler functions on the Blackfin processor 3413Use this attribute on the Blackfin to indicate that the specified function 3414is an NMI handler. The compiler generates function entry and 3415exit sequences suitable for use in an NMI handler when this 3416attribute is present. 3417 3418@item nocompression 3419@cindex @code{nocompression} function attribute, MIPS 3420On MIPS targets, you can use the @code{nocompression} function attribute 3421to locally turn off MIPS16 and microMIPS code generation. This attribute 3422overrides the @option{-mips16} and @option{-mmicromips} options on the 3423command line (@pxref{MIPS Options}). 3424 3425@item no_instrument_function 3426@cindex @code{no_instrument_function} function attribute 3427@opindex finstrument-functions 3428If @option{-finstrument-functions} is given, profiling function calls are 3429generated at entry and exit of most user-compiled functions. 3430Functions with this attribute are not so instrumented. 3431 3432@item no_split_stack 3433@cindex @code{no_split_stack} function attribute 3434@opindex fsplit-stack 3435If @option{-fsplit-stack} is given, functions have a small 3436prologue which decides whether to split the stack. Functions with the 3437@code{no_split_stack} attribute do not have that prologue, and thus 3438may run with only a small amount of stack space available. 3439 3440@item stack_protect 3441@cindex @code{stack_protect} function attribute 3442This function attribute make a stack protection of the function if 3443flags @option{fstack-protector} or @option{fstack-protector-strong} 3444or @option{fstack-protector-explicit} are set. 3445 3446@item noinline 3447@cindex @code{noinline} function attribute 3448This function attribute prevents a function from being considered for 3449inlining. 3450@c Don't enumerate the optimizations by name here; we try to be 3451@c future-compatible with this mechanism. 3452If the function does not have side-effects, there are optimizations 3453other than inlining that cause function calls to be optimized away, 3454although the function call is live. To keep such calls from being 3455optimized away, put 3456@smallexample 3457asm (""); 3458@end smallexample 3459 3460@noindent 3461(@pxref{Extended Asm}) in the called function, to serve as a special 3462side-effect. 3463 3464@item noclone 3465@cindex @code{noclone} function attribute 3466This function attribute prevents a function from being considered for 3467cloning---a mechanism that produces specialized copies of functions 3468and which is (currently) performed by interprocedural constant 3469propagation. 3470 3471@item no_icf 3472@cindex @code{no_icf} function attribute 3473This function attribute prevents a functions from being merged with another 3474semantically equivalent function. 3475 3476@item nonnull (@var{arg-index}, @dots{}) 3477@cindex @code{nonnull} function attribute 3478The @code{nonnull} attribute specifies that some function parameters should 3479be non-null pointers. For instance, the declaration: 3480 3481@smallexample 3482extern void * 3483my_memcpy (void *dest, const void *src, size_t len) 3484 __attribute__((nonnull (1, 2))); 3485@end smallexample 3486 3487@noindent 3488causes the compiler to check that, in calls to @code{my_memcpy}, 3489arguments @var{dest} and @var{src} are non-null. If the compiler 3490determines that a null pointer is passed in an argument slot marked 3491as non-null, and the @option{-Wnonnull} option is enabled, a warning 3492is issued. The compiler may also choose to make optimizations based 3493on the knowledge that certain function arguments will never be null. 3494 3495If no argument index list is given to the @code{nonnull} attribute, 3496all pointer arguments are marked as non-null. To illustrate, the 3497following declaration is equivalent to the previous example: 3498 3499@smallexample 3500extern void * 3501my_memcpy (void *dest, const void *src, size_t len) 3502 __attribute__((nonnull)); 3503@end smallexample 3504 3505@item no_reorder 3506@cindex @code{no_reorder} function attribute 3507Do not reorder functions or variables marked @code{no_reorder} 3508against each other or top level assembler statements the executable. 3509The actual order in the program will depend on the linker command 3510line. Static variables marked like this are also not removed. 3511This has a similar effect 3512as the @option{-fno-toplevel-reorder} option, but only applies to the 3513marked symbols. 3514 3515@item returns_nonnull 3516@cindex @code{returns_nonnull} function attribute 3517The @code{returns_nonnull} attribute specifies that the function 3518return value should be a non-null pointer. For instance, the declaration: 3519 3520@smallexample 3521extern void * 3522mymalloc (size_t len) __attribute__((returns_nonnull)); 3523@end smallexample 3524 3525@noindent 3526lets the compiler optimize callers based on the knowledge 3527that the return value will never be null. 3528 3529@item noreturn 3530@cindex @code{noreturn} function attribute 3531A few standard library functions, such as @code{abort} and @code{exit}, 3532cannot return. GCC knows this automatically. Some programs define 3533their own functions that never return. You can declare them 3534@code{noreturn} to tell the compiler this fact. For example, 3535 3536@smallexample 3537@group 3538void fatal () __attribute__ ((noreturn)); 3539 3540void 3541fatal (/* @r{@dots{}} */) 3542@{ 3543 /* @r{@dots{}} */ /* @r{Print error message.} */ /* @r{@dots{}} */ 3544 exit (1); 3545@} 3546@end group 3547@end smallexample 3548 3549The @code{noreturn} keyword tells the compiler to assume that 3550@code{fatal} cannot return. It can then optimize without regard to what 3551would happen if @code{fatal} ever did return. This makes slightly 3552better code. More importantly, it helps avoid spurious warnings of 3553uninitialized variables. 3554 3555The @code{noreturn} keyword does not affect the exceptional path when that 3556applies: a @code{noreturn}-marked function may still return to the caller 3557by throwing an exception or calling @code{longjmp}. 3558 3559Do not assume that registers saved by the calling function are 3560restored before calling the @code{noreturn} function. 3561 3562It does not make sense for a @code{noreturn} function to have a return 3563type other than @code{void}. 3564 3565@item nothrow 3566@cindex @code{nothrow} function attribute 3567The @code{nothrow} attribute is used to inform the compiler that a 3568function cannot throw an exception. For example, most functions in 3569the standard C library can be guaranteed not to throw an exception 3570with the notable exceptions of @code{qsort} and @code{bsearch} that 3571take function pointer arguments. 3572 3573@item nosave_low_regs 3574@cindex @code{nosave_low_regs} function attribute, SH 3575Use this attribute on SH targets to indicate that an @code{interrupt_handler} 3576function should not save and restore registers R0..R7. This can be used on SH3* 3577and SH4* targets that have a second R0..R7 register bank for non-reentrant 3578interrupt handlers. 3579 3580@item optimize 3581@cindex @code{optimize} function attribute 3582The @code{optimize} attribute is used to specify that a function is to 3583be compiled with different optimization options than specified on the 3584command line. Arguments can either be numbers or strings. Numbers 3585are assumed to be an optimization level. Strings that begin with 3586@code{O} are assumed to be an optimization option, while other options 3587are assumed to be used with a @code{-f} prefix. You can also use the 3588@samp{#pragma GCC optimize} pragma to set the optimization options 3589that affect more than one function. 3590@xref{Function Specific Option Pragmas}, for details about the 3591@samp{#pragma GCC optimize} pragma. 3592 3593This can be used for instance to have frequently-executed functions 3594compiled with more aggressive optimization options that produce faster 3595and larger code, while other functions can be compiled with less 3596aggressive options. 3597 3598@item OS_main 3599@itemx OS_task 3600@cindex @code{OS_main} function attribute, AVR 3601@cindex @code{OS_task} function attribute, AVR 3602On AVR, functions with the @code{OS_main} or @code{OS_task} attribute 3603do not save/restore any call-saved register in their prologue/epilogue. 3604 3605The @code{OS_main} attribute can be used when there @emph{is 3606guarantee} that interrupts are disabled at the time when the function 3607is entered. This saves resources when the stack pointer has to be 3608changed to set up a frame for local variables. 3609 3610The @code{OS_task} attribute can be used when there is @emph{no 3611guarantee} that interrupts are disabled at that time when the function 3612is entered like for, e@.g@. task functions in a multi-threading operating 3613system. In that case, changing the stack pointer register is 3614guarded by save/clear/restore of the global interrupt enable flag. 3615 3616The differences to the @code{naked} function attribute are: 3617@itemize @bullet 3618@item @code{naked} functions do not have a return instruction whereas 3619@code{OS_main} and @code{OS_task} functions have a @code{RET} or 3620@code{RETI} return instruction. 3621@item @code{naked} functions do not set up a frame for local variables 3622or a frame pointer whereas @code{OS_main} and @code{OS_task} do this 3623as needed. 3624@end itemize 3625 3626@item pcs 3627@cindex @code{pcs} function attribute, ARM 3628 3629The @code{pcs} attribute can be used to control the calling convention 3630used for a function on ARM. The attribute takes an argument that specifies 3631the calling convention to use. 3632 3633When compiling using the AAPCS ABI (or a variant of it) then valid 3634values for the argument are @code{"aapcs"} and @code{"aapcs-vfp"}. In 3635order to use a variant other than @code{"aapcs"} then the compiler must 3636be permitted to use the appropriate co-processor registers (i.e., the 3637VFP registers must be available in order to use @code{"aapcs-vfp"}). 3638For example, 3639 3640@smallexample 3641/* Argument passed in r0, and result returned in r0+r1. */ 3642double f2d (float) __attribute__((pcs("aapcs"))); 3643@end smallexample 3644 3645Variadic functions always use the @code{"aapcs"} calling convention and 3646the compiler rejects attempts to specify an alternative. 3647 3648@item pure 3649@cindex @code{pure} function attribute 3650Many functions have no effects except the return value and their 3651return value depends only on the parameters and/or global variables. 3652Such a function can be subject 3653to common subexpression elimination and loop optimization just as an 3654arithmetic operator would be. These functions should be declared 3655with the attribute @code{pure}. For example, 3656 3657@smallexample 3658int square (int) __attribute__ ((pure)); 3659@end smallexample 3660 3661@noindent 3662says that the hypothetical function @code{square} is safe to call 3663fewer times than the program says. 3664 3665Some of common examples of pure functions are @code{strlen} or @code{memcmp}. 3666Interesting non-pure functions are functions with infinite loops or those 3667depending on volatile memory or other system resource, that may change between 3668two consecutive calls (such as @code{feof} in a multithreading environment). 3669 3670@item hot 3671@cindex @code{hot} function attribute 3672The @code{hot} attribute on a function is used to inform the compiler that 3673the function is a hot spot of the compiled program. The function is 3674optimized more aggressively and on many targets it is placed into a special 3675subsection of the text section so all hot functions appear close together, 3676improving locality. 3677 3678When profile feedback is available, via @option{-fprofile-use}, hot functions 3679are automatically detected and this attribute is ignored. 3680 3681@item cold 3682@cindex @code{cold} function attribute 3683The @code{cold} attribute on functions is used to inform the compiler that 3684the function is unlikely to be executed. The function is optimized for 3685size rather than speed and on many targets it is placed into a special 3686subsection of the text section so all cold functions appear close together, 3687improving code locality of non-cold parts of program. The paths leading 3688to calls of cold functions within code are marked as unlikely by the branch 3689prediction mechanism. It is thus useful to mark functions used to handle 3690unlikely conditions, such as @code{perror}, as cold to improve optimization 3691of hot functions that do call marked functions in rare occasions. 3692 3693When profile feedback is available, via @option{-fprofile-use}, cold functions 3694are automatically detected and this attribute is ignored. 3695 3696@item no_sanitize_address 3697@itemx no_address_safety_analysis 3698@cindex @code{no_sanitize_address} function attribute 3699The @code{no_sanitize_address} attribute on functions is used 3700to inform the compiler that it should not instrument memory accesses 3701in the function when compiling with the @option{-fsanitize=address} option. 3702The @code{no_address_safety_analysis} is a deprecated alias of the 3703@code{no_sanitize_address} attribute, new code should use 3704@code{no_sanitize_address}. 3705 3706@item no_sanitize_thread 3707@cindex @code{no_sanitize_thread} function attribute 3708The @code{no_sanitize_thread} attribute on functions is used 3709to inform the compiler that it should not instrument memory accesses 3710in the function when compiling with the @option{-fsanitize=thread} option. 3711 3712@item no_sanitize_undefined 3713@cindex @code{no_sanitize_undefined} function attribute 3714The @code{no_sanitize_undefined} attribute on functions is used 3715to inform the compiler that it should not check for undefined behavior 3716in the function when compiling with the @option{-fsanitize=undefined} option. 3717 3718@item bnd_legacy 3719@cindex @code{bnd_legacy} function attribute 3720@cindex Pointer Bounds Checker attributes 3721The @code{bnd_legacy} attribute on functions is used to inform the 3722compiler that the function should not be instrumented when compiled 3723with the @option{-fcheck-pointer-bounds} option. 3724 3725@item bnd_instrument 3726@cindex @code{bnd_instrument} function attribute 3727The @code{bnd_instrument} attribute on functions is used to inform the 3728compiler that the function should be instrumented when compiled 3729with the @option{-fchkp-instrument-marked-only} option. 3730 3731@item regparm (@var{number}) 3732@cindex @code{regparm} function attribute, x86 3733@cindex functions that are passed arguments in registers on x86-32 3734On x86-32 targets, the @code{regparm} attribute causes the compiler to 3735pass arguments number one to @var{number} if they are of integral type 3736in registers EAX, EDX, and ECX instead of on the stack. Functions that 3737take a variable number of arguments continue to be passed all of their 3738arguments on the stack. 3739 3740Beware that on some ELF systems this attribute is unsuitable for 3741global functions in shared libraries with lazy binding (which is the 3742default). Lazy binding sends the first call via resolving code in 3743the loader, which might assume EAX, EDX and ECX can be clobbered, as 3744per the standard calling conventions. Solaris 8 is affected by this. 3745Systems with the GNU C Library version 2.1 or higher 3746and FreeBSD are believed to be 3747safe since the loaders there save EAX, EDX and ECX. (Lazy binding can be 3748disabled with the linker or the loader if desired, to avoid the 3749problem.) 3750 3751@item reset 3752@cindex @code{reset} function attribute, NDS32 3753@cindex reset handler functions 3754Use this attribute on the NDS32 target to indicate that the specified function 3755is a reset handler. The compiler will generate corresponding sections 3756for use in a reset handler. You can use the following attributes 3757to provide extra exception handling: 3758@table @code 3759@item nmi 3760@cindex @code{nmi} function attribute, NDS32 3761Provide a user-defined function to handle NMI exception. 3762@item warm 3763@cindex @code{warm} function attribute, NDS32 3764Provide a user-defined function to handle warm reset exception. 3765@end table 3766 3767@item sseregparm 3768@cindex @code{sseregparm} function attribute, x86 3769On x86-32 targets with SSE support, the @code{sseregparm} attribute 3770causes the compiler to pass up to 3 floating-point arguments in 3771SSE registers instead of on the stack. Functions that take a 3772variable number of arguments continue to pass all of their 3773floating-point arguments on the stack. 3774 3775@item force_align_arg_pointer 3776@cindex @code{force_align_arg_pointer} function attribute, x86 3777On x86 targets, the @code{force_align_arg_pointer} attribute may be 3778applied to individual function definitions, generating an alternate 3779prologue and epilogue that realigns the run-time stack if necessary. 3780This supports mixing legacy codes that run with a 4-byte aligned stack 3781with modern codes that keep a 16-byte stack for SSE compatibility. 3782 3783@item renesas 3784@cindex @code{renesas} function attribute, SH 3785On SH targets this attribute specifies that the function or struct follows the 3786Renesas ABI. 3787 3788@item resbank 3789@cindex @code{resbank} function attribute, SH 3790On the SH2A target, this attribute enables the high-speed register 3791saving and restoration using a register bank for @code{interrupt_handler} 3792routines. Saving to the bank is performed automatically after the CPU 3793accepts an interrupt that uses a register bank. 3794 3795The nineteen 32-bit registers comprising general register R0 to R14, 3796control register GBR, and system registers MACH, MACL, and PR and the 3797vector table address offset are saved into a register bank. Register 3798banks are stacked in first-in last-out (FILO) sequence. Restoration 3799from the bank is executed by issuing a RESBANK instruction. 3800 3801@item returns_twice 3802@cindex @code{returns_twice} function attribute 3803The @code{returns_twice} attribute tells the compiler that a function may 3804return more than one time. The compiler ensures that all registers 3805are dead before calling such a function and emits a warning about 3806the variables that may be clobbered after the second return from the 3807function. Examples of such functions are @code{setjmp} and @code{vfork}. 3808The @code{longjmp}-like counterpart of such function, if any, might need 3809to be marked with the @code{noreturn} attribute. 3810 3811@item saveall 3812@cindex @code{saveall} function attribute, Blackfin 3813@cindex @code{saveall} function attribute, H8/300 3814@cindex save all registers on the Blackfin, H8/300, H8/300H, and H8S 3815Use this attribute on the Blackfin, H8/300, H8/300H, and H8S to indicate that 3816all registers except the stack pointer should be saved in the prologue 3817regardless of whether they are used or not. 3818 3819@item save_volatiles 3820@cindex @code{save_volatiles} function attribute, MicroBlaze 3821Use this attribute on the MicroBlaze to indicate that the function is 3822an interrupt handler. All volatile registers (in addition to non-volatile 3823registers) are saved in the function prologue. If the function is a leaf 3824function, only volatiles used by the function are saved. A normal function 3825return is generated instead of a return from interrupt. 3826 3827@item break_handler 3828@cindex @code{break_handler} function attribute, MicroBlaze 3829@cindex break handler functions 3830Use this attribute on the MicroBlaze ports to indicate that 3831the specified function is a break handler. The compiler generates function 3832entry and exit sequences suitable for use in an break handler when this 3833attribute is present. The return from @code{break_handler} is done through 3834the @code{rtbd} instead of @code{rtsd}. 3835 3836@smallexample 3837void f () __attribute__ ((break_handler)); 3838@end smallexample 3839 3840@item section ("@var{section-name}") 3841@cindex @code{section} function attribute 3842Normally, the compiler places the code it generates in the @code{text} section. 3843Sometimes, however, you need additional sections, or you need certain 3844particular functions to appear in special sections. The @code{section} 3845attribute specifies that a function lives in a particular section. 3846For example, the declaration: 3847 3848@smallexample 3849extern void foobar (void) __attribute__ ((section ("bar"))); 3850@end smallexample 3851 3852@noindent 3853puts the function @code{foobar} in the @code{bar} section. 3854 3855Some file formats do not support arbitrary sections so the @code{section} 3856attribute is not available on all platforms. 3857If you need to map the entire contents of a module to a particular 3858section, consider using the facilities of the linker instead. 3859 3860@item sentinel 3861@cindex @code{sentinel} function attribute 3862This function attribute ensures that a parameter in a function call is 3863an explicit @code{NULL}. The attribute is only valid on variadic 3864functions. By default, the sentinel is located at position zero, the 3865last parameter of the function call. If an optional integer position 3866argument P is supplied to the attribute, the sentinel must be located at 3867position P counting backwards from the end of the argument list. 3868 3869@smallexample 3870__attribute__ ((sentinel)) 3871is equivalent to 3872__attribute__ ((sentinel(0))) 3873@end smallexample 3874 3875The attribute is automatically set with a position of 0 for the built-in 3876functions @code{execl} and @code{execlp}. The built-in function 3877@code{execle} has the attribute set with a position of 1. 3878 3879A valid @code{NULL} in this context is defined as zero with any pointer 3880type. If your system defines the @code{NULL} macro with an integer type 3881then you need to add an explicit cast. GCC replaces @code{stddef.h} 3882with a copy that redefines NULL appropriately. 3883 3884The warnings for missing or incorrect sentinels are enabled with 3885@option{-Wformat}. 3886 3887@item short_call 3888See @code{long_call}. 3889 3890@item shortcall 3891See @code{longcall}. 3892 3893@item signal 3894@cindex @code{signal} function attribute, AVR 3895Use this attribute on the AVR to indicate that the specified 3896function is an interrupt handler. The compiler generates function 3897entry and exit sequences suitable for use in an interrupt handler when this 3898attribute is present. 3899 3900See also the @code{interrupt} function attribute. 3901 3902The AVR hardware globally disables interrupts when an interrupt is executed. 3903Interrupt handler functions defined with the @code{signal} attribute 3904do not re-enable interrupts. It is save to enable interrupts in a 3905@code{signal} handler. This ``save'' only applies to the code 3906generated by the compiler and not to the IRQ layout of the 3907application which is responsibility of the application. 3908 3909If both @code{signal} and @code{interrupt} are specified for the same 3910function, @code{signal} is silently ignored. 3911 3912@item sp_switch 3913@cindex @code{sp_switch} function attribute, SH 3914Use this attribute on the SH to indicate an @code{interrupt_handler} 3915function should switch to an alternate stack. It expects a string 3916argument that names a global variable holding the address of the 3917alternate stack. 3918 3919@smallexample 3920void *alt_stack; 3921void f () __attribute__ ((interrupt_handler, 3922 sp_switch ("alt_stack"))); 3923@end smallexample 3924 3925@item stdcall 3926@cindex @code{stdcall} function attribute, x86-32 3927@cindex functions that pop the argument stack on x86-32 3928On x86-32 targets, the @code{stdcall} attribute causes the compiler to 3929assume that the called function pops off the stack space used to 3930pass arguments, unless it takes a variable number of arguments. 3931 3932@item syscall_linkage 3933@cindex @code{syscall_linkage} function attribute, IA-64 3934This attribute is used to modify the IA-64 calling convention by marking 3935all input registers as live at all function exits. This makes it possible 3936to restart a system call after an interrupt without having to save/restore 3937the input registers. This also prevents kernel data from leaking into 3938application code. 3939 3940@item target 3941@cindex @code{target} function attribute 3942The @code{target} attribute is used to specify that a function is to 3943be compiled with different target options than specified on the 3944command line. This can be used for instance to have functions 3945compiled with a different ISA (instruction set architecture) than the 3946default. You can also use the @samp{#pragma GCC target} pragma to set 3947more than one function to be compiled with specific target options. 3948@xref{Function Specific Option Pragmas}, for details about the 3949@samp{#pragma GCC target} pragma. 3950 3951For instance on an x86, you could compile one function with 3952@code{target("sse4.1,arch=core2")} and another with 3953@code{target("sse4a,arch=amdfam10")}. This is equivalent to 3954compiling the first function with @option{-msse4.1} and 3955@option{-march=core2} options, and the second function with 3956@option{-msse4a} and @option{-march=amdfam10} options. It is up to the 3957user to make sure that a function is only invoked on a machine that 3958supports the particular ISA it is compiled for (for example by using 3959@code{cpuid} on x86 to determine what feature bits and architecture 3960family are used). 3961 3962@smallexample 3963int core2_func (void) __attribute__ ((__target__ ("arch=core2"))); 3964int sse3_func (void) __attribute__ ((__target__ ("sse3"))); 3965@end smallexample 3966 3967You can either use multiple 3968strings to specify multiple options, or separate the options 3969with a comma (@samp{,}). 3970 3971The @code{target} attribute is presently implemented for 3972x86, PowerPC, and Nios II targets only. 3973The options supported are specific to each target. 3974 3975On the x86, the following options are allowed: 3976 3977@table @samp 3978@item abm 3979@itemx no-abm 3980@cindex @code{target("abm")} function attribute, x86 3981Enable/disable the generation of the advanced bit instructions. 3982 3983@item aes 3984@itemx no-aes 3985@cindex @code{target("aes")} function attribute, x86 3986Enable/disable the generation of the AES instructions. 3987 3988@item default 3989@cindex @code{target("default")} function attribute, x86 3990@xref{Function Multiversioning}, where it is used to specify the 3991default function version. 3992 3993@item mmx 3994@itemx no-mmx 3995@cindex @code{target("mmx")} function attribute, x86 3996Enable/disable the generation of the MMX instructions. 3997 3998@item pclmul 3999@itemx no-pclmul 4000@cindex @code{target("pclmul")} function attribute, x86 4001Enable/disable the generation of the PCLMUL instructions. 4002 4003@item popcnt 4004@itemx no-popcnt 4005@cindex @code{target("popcnt")} function attribute, x86 4006Enable/disable the generation of the POPCNT instruction. 4007 4008@item sse 4009@itemx no-sse 4010@cindex @code{target("sse")} function attribute, x86 4011Enable/disable the generation of the SSE instructions. 4012 4013@item sse2 4014@itemx no-sse2 4015@cindex @code{target("sse2")} function attribute, x86 4016Enable/disable the generation of the SSE2 instructions. 4017 4018@item sse3 4019@itemx no-sse3 4020@cindex @code{target("sse3")} function attribute, x86 4021Enable/disable the generation of the SSE3 instructions. 4022 4023@item sse4 4024@itemx no-sse4 4025@cindex @code{target("sse4")} function attribute, x86 4026Enable/disable the generation of the SSE4 instructions (both SSE4.1 4027and SSE4.2). 4028 4029@item sse4.1 4030@itemx no-sse4.1 4031@cindex @code{target("sse4.1")} function attribute, x86 4032Enable/disable the generation of the sse4.1 instructions. 4033 4034@item sse4.2 4035@itemx no-sse4.2 4036@cindex @code{target("sse4.2")} function attribute, x86 4037Enable/disable the generation of the sse4.2 instructions. 4038 4039@item sse4a 4040@itemx no-sse4a 4041@cindex @code{target("sse4a")} function attribute, x86 4042Enable/disable the generation of the SSE4A instructions. 4043 4044@item fma4 4045@itemx no-fma4 4046@cindex @code{target("fma4")} function attribute, x86 4047Enable/disable the generation of the FMA4 instructions. 4048 4049@item xop 4050@itemx no-xop 4051@cindex @code{target("xop")} function attribute, x86 4052Enable/disable the generation of the XOP instructions. 4053 4054@item lwp 4055@itemx no-lwp 4056@cindex @code{target("lwp")} function attribute, x86 4057Enable/disable the generation of the LWP instructions. 4058 4059@item ssse3 4060@itemx no-ssse3 4061@cindex @code{target("ssse3")} function attribute, x86 4062Enable/disable the generation of the SSSE3 instructions. 4063 4064@item cld 4065@itemx no-cld 4066@cindex @code{target("cld")} function attribute, x86 4067Enable/disable the generation of the CLD before string moves. 4068 4069@item fancy-math-387 4070@itemx no-fancy-math-387 4071@cindex @code{target("fancy-math-387")} function attribute, x86 4072Enable/disable the generation of the @code{sin}, @code{cos}, and 4073@code{sqrt} instructions on the 387 floating-point unit. 4074 4075@item fused-madd 4076@itemx no-fused-madd 4077@cindex @code{target("fused-madd")} function attribute, x86 4078Enable/disable the generation of the fused multiply/add instructions. 4079 4080@item ieee-fp 4081@itemx no-ieee-fp 4082@cindex @code{target("ieee-fp")} function attribute, x86 4083Enable/disable the generation of floating point that depends on IEEE arithmetic. 4084 4085@item inline-all-stringops 4086@itemx no-inline-all-stringops 4087@cindex @code{target("inline-all-stringops")} function attribute, x86 4088Enable/disable inlining of string operations. 4089 4090@item inline-stringops-dynamically 4091@itemx no-inline-stringops-dynamically 4092@cindex @code{target("inline-stringops-dynamically")} function attribute, x86 4093Enable/disable the generation of the inline code to do small string 4094operations and calling the library routines for large operations. 4095 4096@item align-stringops 4097@itemx no-align-stringops 4098@cindex @code{target("align-stringops")} function attribute, x86 4099Do/do not align destination of inlined string operations. 4100 4101@item recip 4102@itemx no-recip 4103@cindex @code{target("recip")} function attribute, x86 4104Enable/disable the generation of RCPSS, RCPPS, RSQRTSS and RSQRTPS 4105instructions followed an additional Newton-Raphson step instead of 4106doing a floating-point division. 4107 4108@item arch=@var{ARCH} 4109@cindex @code{target("arch=@var{ARCH}")} function attribute, x86 4110Specify the architecture to generate code for in compiling the function. 4111 4112@item tune=@var{TUNE} 4113@cindex @code{target("tune=@var{TUNE}")} function attribute, x86 4114Specify the architecture to tune for in compiling the function. 4115 4116@item fpmath=@var{FPMATH} 4117@cindex @code{target("fpmath=@var{FPMATH}")} function attribute, x86 4118Specify which floating-point unit to use. The 4119@code{target("fpmath=sse,387")} option must be specified as 4120@code{target("fpmath=sse+387")} because the comma would separate 4121different options. 4122@end table 4123 4124On the PowerPC, the following options are allowed: 4125 4126@table @samp 4127@item altivec 4128@itemx no-altivec 4129@cindex @code{target("altivec")} function attribute, PowerPC 4130Generate code that uses (does not use) AltiVec instructions. In 413132-bit code, you cannot enable AltiVec instructions unless 4132@option{-mabi=altivec} is used on the command line. 4133 4134@item cmpb 4135@itemx no-cmpb 4136@cindex @code{target("cmpb")} function attribute, PowerPC 4137Generate code that uses (does not use) the compare bytes instruction 4138implemented on the POWER6 processor and other processors that support 4139the PowerPC V2.05 architecture. 4140 4141@item dlmzb 4142@itemx no-dlmzb 4143@cindex @code{target("dlmzb")} function attribute, PowerPC 4144Generate code that uses (does not use) the string-search @samp{dlmzb} 4145instruction on the IBM 405, 440, 464 and 476 processors. This instruction is 4146generated by default when targeting those processors. 4147 4148@item fprnd 4149@itemx no-fprnd 4150@cindex @code{target("fprnd")} function attribute, PowerPC 4151Generate code that uses (does not use) the FP round to integer 4152instructions implemented on the POWER5+ processor and other processors 4153that support the PowerPC V2.03 architecture. 4154 4155@item hard-dfp 4156@itemx no-hard-dfp 4157@cindex @code{target("hard-dfp")} function attribute, PowerPC 4158Generate code that uses (does not use) the decimal floating-point 4159instructions implemented on some POWER processors. 4160 4161@item isel 4162@itemx no-isel 4163@cindex @code{target("isel")} function attribute, PowerPC 4164Generate code that uses (does not use) ISEL instruction. 4165 4166@item mfcrf 4167@itemx no-mfcrf 4168@cindex @code{target("mfcrf")} function attribute, PowerPC 4169Generate code that uses (does not use) the move from condition 4170register field instruction implemented on the POWER4 processor and 4171other processors that support the PowerPC V2.01 architecture. 4172 4173@item mfpgpr 4174@itemx no-mfpgpr 4175@cindex @code{target("mfpgpr")} function attribute, PowerPC 4176Generate code that uses (does not use) the FP move to/from general 4177purpose register instructions implemented on the POWER6X processor and 4178other processors that support the extended PowerPC V2.05 architecture. 4179 4180@item mulhw 4181@itemx no-mulhw 4182@cindex @code{target("mulhw")} function attribute, PowerPC 4183Generate code that uses (does not use) the half-word multiply and 4184multiply-accumulate instructions on the IBM 405, 440, 464 and 476 processors. 4185These instructions are generated by default when targeting those 4186processors. 4187 4188@item multiple 4189@itemx no-multiple 4190@cindex @code{target("multiple")} function attribute, PowerPC 4191Generate code that uses (does not use) the load multiple word 4192instructions and the store multiple word instructions. 4193 4194@item update 4195@itemx no-update 4196@cindex @code{target("update")} function attribute, PowerPC 4197Generate code that uses (does not use) the load or store instructions 4198that update the base register to the address of the calculated memory 4199location. 4200 4201@item popcntb 4202@itemx no-popcntb 4203@cindex @code{target("popcntb")} function attribute, PowerPC 4204Generate code that uses (does not use) the popcount and double-precision 4205FP reciprocal estimate instruction implemented on the POWER5 4206processor and other processors that support the PowerPC V2.02 4207architecture. 4208 4209@item popcntd 4210@itemx no-popcntd 4211@cindex @code{target("popcntd")} function attribute, PowerPC 4212Generate code that uses (does not use) the popcount instruction 4213implemented on the POWER7 processor and other processors that support 4214the PowerPC V2.06 architecture. 4215 4216@item powerpc-gfxopt 4217@itemx no-powerpc-gfxopt 4218@cindex @code{target("powerpc-gfxopt")} function attribute, PowerPC 4219Generate code that uses (does not use) the optional PowerPC 4220architecture instructions in the Graphics group, including 4221floating-point select. 4222 4223@item powerpc-gpopt 4224@itemx no-powerpc-gpopt 4225@cindex @code{target("powerpc-gpopt")} function attribute, PowerPC 4226Generate code that uses (does not use) the optional PowerPC 4227architecture instructions in the General Purpose group, including 4228floating-point square root. 4229 4230@item recip-precision 4231@itemx no-recip-precision 4232@cindex @code{target("recip-precision")} function attribute, PowerPC 4233Assume (do not assume) that the reciprocal estimate instructions 4234provide higher-precision estimates than is mandated by the PowerPC 4235ABI. 4236 4237@item string 4238@itemx no-string 4239@cindex @code{target("string")} function attribute, PowerPC 4240Generate code that uses (does not use) the load string instructions 4241and the store string word instructions to save multiple registers and 4242do small block moves. 4243 4244@item vsx 4245@itemx no-vsx 4246@cindex @code{target("vsx")} function attribute, PowerPC 4247Generate code that uses (does not use) vector/scalar (VSX) 4248instructions, and also enable the use of built-in functions that allow 4249more direct access to the VSX instruction set. In 32-bit code, you 4250cannot enable VSX or AltiVec instructions unless 4251@option{-mabi=altivec} is used on the command line. 4252 4253@item friz 4254@itemx no-friz 4255@cindex @code{target("friz")} function attribute, PowerPC 4256Generate (do not generate) the @code{friz} instruction when the 4257@option{-funsafe-math-optimizations} option is used to optimize 4258rounding a floating-point value to 64-bit integer and back to floating 4259point. The @code{friz} instruction does not return the same value if 4260the floating-point number is too large to fit in an integer. 4261 4262@item avoid-indexed-addresses 4263@itemx no-avoid-indexed-addresses 4264@cindex @code{target("avoid-indexed-addresses")} function attribute, PowerPC 4265Generate code that tries to avoid (not avoid) the use of indexed load 4266or store instructions. 4267 4268@item paired 4269@itemx no-paired 4270@cindex @code{target("paired")} function attribute, PowerPC 4271Generate code that uses (does not use) the generation of PAIRED simd 4272instructions. 4273 4274@item longcall 4275@itemx no-longcall 4276@cindex @code{target("longcall")} function attribute, PowerPC 4277Generate code that assumes (does not assume) that all calls are far 4278away so that a longer more expensive calling sequence is required. 4279 4280@item cpu=@var{CPU} 4281@cindex @code{target("cpu=@var{CPU}")} function attribute, PowerPC 4282Specify the architecture to generate code for when compiling the 4283function. If you select the @code{target("cpu=power7")} attribute when 4284generating 32-bit code, VSX and AltiVec instructions are not generated 4285unless you use the @option{-mabi=altivec} option on the command line. 4286 4287@item tune=@var{TUNE} 4288@cindex @code{target("tune=@var{TUNE}")} function attribute, PowerPC 4289Specify the architecture to tune for when compiling the function. If 4290you do not specify the @code{target("tune=@var{TUNE}")} attribute and 4291you do specify the @code{target("cpu=@var{CPU}")} attribute, 4292compilation tunes for the @var{CPU} architecture, and not the 4293default tuning specified on the command line. 4294@end table 4295 4296When compiling for Nios II, the following options are allowed: 4297 4298@table @samp 4299@item custom-@var{insn}=@var{N} 4300@itemx no-custom-@var{insn} 4301@cindex @code{target("custom-@var{insn}=@var{N}")} function attribute, Nios II 4302@cindex @code{target("no-custom-@var{insn}")} function attribute, Nios II 4303Each @samp{custom-@var{insn}=@var{N}} attribute locally enables use of a 4304custom instruction with encoding @var{N} when generating code that uses 4305@var{insn}. Similarly, @samp{no-custom-@var{insn}} locally inhibits use of 4306the custom instruction @var{insn}. 4307These target attributes correspond to the 4308@option{-mcustom-@var{insn}=@var{N}} and @option{-mno-custom-@var{insn}} 4309command-line options, and support the same set of @var{insn} keywords. 4310@xref{Nios II Options}, for more information. 4311 4312@item custom-fpu-cfg=@var{name} 4313@cindex @code{target("custom-fpu-cfg=@var{name}")} function attribute, Nios II 4314This attribute corresponds to the @option{-mcustom-fpu-cfg=@var{name}} 4315command-line option, to select a predefined set of custom instructions 4316named @var{name}. 4317@xref{Nios II Options}, for more information. 4318@end table 4319 4320On the x86 and PowerPC back ends, the inliner does not inline a 4321function that has different target options than the caller, unless the 4322callee has a subset of the target options of the caller. For example 4323a function declared with @code{target("sse3")} can inline a function 4324with @code{target("sse2")}, since @code{-msse3} implies @code{-msse2}. 4325 4326@item trap_exit 4327@cindex @code{trap_exit} function attribute, SH 4328Use this attribute on the SH for an @code{interrupt_handler} to return using 4329@code{trapa} instead of @code{rte}. This attribute expects an integer 4330argument specifying the trap number to be used. 4331 4332@item trapa_handler 4333@cindex @code{trapa_handler} function attribute, SH 4334On SH targets this function attribute is similar to @code{interrupt_handler} 4335but it does not save and restore all registers. 4336 4337@item unused 4338@cindex @code{unused} function attribute 4339This attribute, attached to a function, means that the function is meant 4340to be possibly unused. GCC does not produce a warning for this 4341function. 4342 4343@item used 4344@cindex @code{used} function attribute 4345This attribute, attached to a function, means that code must be emitted 4346for the function even if it appears that the function is not referenced. 4347This is useful, for example, when the function is referenced only in 4348inline assembly. 4349 4350When applied to a member function of a C++ class template, the 4351attribute also means that the function is instantiated if the 4352class itself is instantiated. 4353 4354@item vector 4355@cindex @code{vector} function attribute, RX 4356This RX attribute is similar to the @code{interrupt} attribute, including its 4357parameters, but does not make the function an interrupt-handler type 4358function (i.e. it retains the normal C function calling ABI). See the 4359@code{interrupt} attribute for a description of its arguments. 4360 4361@item version_id 4362@cindex @code{version_id} function attribute, IA-64 4363This IA-64 HP-UX attribute, attached to a global variable or function, renames a 4364symbol to contain a version string, thus allowing for function level 4365versioning. HP-UX system header files may use function level versioning 4366for some system calls. 4367 4368@smallexample 4369extern int foo () __attribute__((version_id ("20040821"))); 4370@end smallexample 4371 4372@noindent 4373Calls to @var{foo} are mapped to calls to @var{foo@{20040821@}}. 4374 4375@item visibility ("@var{visibility_type}") 4376@cindex @code{visibility} function attribute 4377This attribute affects the linkage of the declaration to which it is attached. 4378There are four supported @var{visibility_type} values: default, 4379hidden, protected or internal visibility. 4380 4381@smallexample 4382void __attribute__ ((visibility ("protected"))) 4383f () @{ /* @r{Do something.} */; @} 4384int i __attribute__ ((visibility ("hidden"))); 4385@end smallexample 4386 4387The possible values of @var{visibility_type} correspond to the 4388visibility settings in the ELF gABI. 4389 4390@table @dfn 4391@c keep this list of visibilities in alphabetical order. 4392 4393@item default 4394Default visibility is the normal case for the object file format. 4395This value is available for the visibility attribute to override other 4396options that may change the assumed visibility of entities. 4397 4398On ELF, default visibility means that the declaration is visible to other 4399modules and, in shared libraries, means that the declared entity may be 4400overridden. 4401 4402On Darwin, default visibility means that the declaration is visible to 4403other modules. 4404 4405Default visibility corresponds to ``external linkage'' in the language. 4406 4407@item hidden 4408Hidden visibility indicates that the entity declared has a new 4409form of linkage, which we call ``hidden linkage''. Two 4410declarations of an object with hidden linkage refer to the same object 4411if they are in the same shared object. 4412 4413@item internal 4414Internal visibility is like hidden visibility, but with additional 4415processor specific semantics. Unless otherwise specified by the 4416psABI, GCC defines internal visibility to mean that a function is 4417@emph{never} called from another module. Compare this with hidden 4418functions which, while they cannot be referenced directly by other 4419modules, can be referenced indirectly via function pointers. By 4420indicating that a function cannot be called from outside the module, 4421GCC may for instance omit the load of a PIC register since it is known 4422that the calling function loaded the correct value. 4423 4424@item protected 4425Protected visibility is like default visibility except that it 4426indicates that references within the defining module bind to the 4427definition in that module. That is, the declared entity cannot be 4428overridden by another module. 4429 4430@end table 4431 4432All visibilities are supported on many, but not all, ELF targets 4433(supported when the assembler supports the @samp{.visibility} 4434pseudo-op). Default visibility is supported everywhere. Hidden 4435visibility is supported on Darwin targets. 4436 4437The visibility attribute should be applied only to declarations that 4438would otherwise have external linkage. The attribute should be applied 4439consistently, so that the same entity should not be declared with 4440different settings of the attribute. 4441 4442In C++, the visibility attribute applies to types as well as functions 4443and objects, because in C++ types have linkage. A class must not have 4444greater visibility than its non-static data member types and bases, 4445and class members default to the visibility of their class. Also, a 4446declaration without explicit visibility is limited to the visibility 4447of its type. 4448 4449In C++, you can mark member functions and static member variables of a 4450class with the visibility attribute. This is useful if you know a 4451particular method or static member variable should only be used from 4452one shared object; then you can mark it hidden while the rest of the 4453class has default visibility. Care must be taken to avoid breaking 4454the One Definition Rule; for example, it is usually not useful to mark 4455an inline method as hidden without marking the whole class as hidden. 4456 4457A C++ namespace declaration can also have the visibility attribute. 4458 4459@smallexample 4460namespace nspace1 __attribute__ ((visibility ("protected"))) 4461@{ /* @r{Do something.} */; @} 4462@end smallexample 4463 4464This attribute applies only to the particular namespace body, not to 4465other definitions of the same namespace; it is equivalent to using 4466@samp{#pragma GCC visibility} before and after the namespace 4467definition (@pxref{Visibility Pragmas}). 4468 4469In C++, if a template argument has limited visibility, this 4470restriction is implicitly propagated to the template instantiation. 4471Otherwise, template instantiations and specializations default to the 4472visibility of their template. 4473 4474If both the template and enclosing class have explicit visibility, the 4475visibility from the template is used. 4476 4477@item vliw 4478@cindex @code{vliw} function attribute, MeP 4479On MeP, the @code{vliw} attribute tells the compiler to emit 4480instructions in VLIW mode instead of core mode. Note that this 4481attribute is not allowed unless a VLIW coprocessor has been configured 4482and enabled through command-line options. 4483 4484@item warn_unused_result 4485@cindex @code{warn_unused_result} function attribute 4486The @code{warn_unused_result} attribute causes a warning to be emitted 4487if a caller of the function with this attribute does not use its 4488return value. This is useful for functions where not checking 4489the result is either a security problem or always a bug, such as 4490@code{realloc}. 4491 4492@smallexample 4493int fn () __attribute__ ((warn_unused_result)); 4494int foo () 4495@{ 4496 if (fn () < 0) return -1; 4497 fn (); 4498 return 0; 4499@} 4500@end smallexample 4501 4502@noindent 4503results in warning on line 5. 4504 4505@item weak 4506@cindex @code{weak} function attribute 4507The @code{weak} attribute causes the declaration to be emitted as a weak 4508symbol rather than a global. This is primarily useful in defining 4509library functions that can be overridden in user code, though it can 4510also be used with non-function declarations. Weak symbols are supported 4511for ELF targets, and also for a.out targets when using the GNU assembler 4512and linker. 4513 4514@item weakref 4515@itemx weakref ("@var{target}") 4516@cindex @code{weakref} function attribute 4517The @code{weakref} attribute marks a declaration as a weak reference. 4518Without arguments, it should be accompanied by an @code{alias} attribute 4519naming the target symbol. Optionally, the @var{target} may be given as 4520an argument to @code{weakref} itself. In either case, @code{weakref} 4521implicitly marks the declaration as @code{weak}. Without a 4522@var{target}, given as an argument to @code{weakref} or to @code{alias}, 4523@code{weakref} is equivalent to @code{weak}. 4524 4525@smallexample 4526static int x() __attribute__ ((weakref ("y"))); 4527/* is equivalent to... */ 4528static int x() __attribute__ ((weak, weakref, alias ("y"))); 4529/* and to... */ 4530static int x() __attribute__ ((weakref)); 4531static int x() __attribute__ ((alias ("y"))); 4532@end smallexample 4533 4534A weak reference is an alias that does not by itself require a 4535definition to be given for the target symbol. If the target symbol is 4536only referenced through weak references, then it becomes a @code{weak} 4537undefined symbol. If it is directly referenced, however, then such 4538strong references prevail, and a definition is required for the 4539symbol, not necessarily in the same translation unit. 4540 4541The effect is equivalent to moving all references to the alias to a 4542separate translation unit, renaming the alias to the aliased symbol, 4543declaring it as weak, compiling the two separate translation units and 4544performing a reloadable link on them. 4545 4546At present, a declaration to which @code{weakref} is attached can 4547only be @code{static}. 4548 4549@end table 4550 4551You can specify multiple attributes in a declaration by separating them 4552by commas within the double parentheses or by immediately following an 4553attribute declaration with another attribute declaration. 4554 4555@cindex @code{#pragma}, reason for not using 4556@cindex pragma, reason for not using 4557Some people object to the @code{__attribute__} feature, suggesting that 4558ISO C's @code{#pragma} should be used instead. At the time 4559@code{__attribute__} was designed, there were two reasons for not doing 4560this. 4561 4562@enumerate 4563@item 4564It is impossible to generate @code{#pragma} commands from a macro. 4565 4566@item 4567There is no telling what the same @code{#pragma} might mean in another 4568compiler. 4569@end enumerate 4570 4571These two reasons applied to almost any application that might have been 4572proposed for @code{#pragma}. It was basically a mistake to use 4573@code{#pragma} for @emph{anything}. 4574 4575The ISO C99 standard includes @code{_Pragma}, which now allows pragmas 4576to be generated from macros. In addition, a @code{#pragma GCC} 4577namespace is now in use for GCC-specific pragmas. However, it has been 4578found convenient to use @code{__attribute__} to achieve a natural 4579attachment of attributes to their corresponding declarations, whereas 4580@code{#pragma GCC} is of use for constructs that do not naturally form 4581part of the grammar. @xref{Pragmas,,Pragmas Accepted by GCC}. 4582 4583@node Label Attributes 4584@section Label Attributes 4585@cindex Label Attributes 4586 4587GCC allows attributes to be set on C labels. @xref{Attribute Syntax}, for 4588details of the exact syntax for using attributes. Other attributes are 4589available for functions (@pxref{Function Attributes}), variables 4590(@pxref{Variable Attributes}) and for types (@pxref{Type Attributes}). 4591 4592This example uses the @code{cold} label attribute to indicate the 4593@code{ErrorHandling} branch is unlikely to be taken and that the 4594@code{ErrorHandling} label is unused: 4595 4596@smallexample 4597 4598 asm goto ("some asm" : : : : NoError); 4599 4600/* This branch (the fall-through from the asm) is less commonly used */ 4601ErrorHandling: 4602 __attribute__((cold, unused)); /* Semi-colon is required here */ 4603 printf("error\n"); 4604 return 0; 4605 4606NoError: 4607 printf("no error\n"); 4608 return 1; 4609@end smallexample 4610 4611@table @code 4612@item unused 4613@cindex @code{unused} label attribute 4614This feature is intended for program-generated code that may contain 4615unused labels, but which is compiled with @option{-Wall}. It is 4616not normally appropriate to use in it human-written code, though it 4617could be useful in cases where the code that jumps to the label is 4618contained within an @code{#ifdef} conditional. 4619 4620@item hot 4621@cindex @code{hot} label attribute 4622The @code{hot} attribute on a label is used to inform the compiler that 4623the path following the label is more likely than paths that are not so 4624annotated. This attribute is used in cases where @code{__builtin_expect} 4625cannot be used, for instance with computed goto or @code{asm goto}. 4626 4627@item cold 4628@cindex @code{cold} label attribute 4629The @code{cold} attribute on labels is used to inform the compiler that 4630the path following the label is unlikely to be executed. This attribute 4631is used in cases where @code{__builtin_expect} cannot be used, for instance 4632with computed goto or @code{asm goto}. 4633 4634@end table 4635 4636@node Attribute Syntax 4637@section Attribute Syntax 4638@cindex attribute syntax 4639 4640This section describes the syntax with which @code{__attribute__} may be 4641used, and the constructs to which attribute specifiers bind, for the C 4642language. Some details may vary for C++ and Objective-C@. Because of 4643infelicities in the grammar for attributes, some forms described here 4644may not be successfully parsed in all cases. 4645 4646There are some problems with the semantics of attributes in C++. For 4647example, there are no manglings for attributes, although they may affect 4648code generation, so problems may arise when attributed types are used in 4649conjunction with templates or overloading. Similarly, @code{typeid} 4650does not distinguish between types with different attributes. Support 4651for attributes in C++ may be restricted in future to attributes on 4652declarations only, but not on nested declarators. 4653 4654@xref{Function Attributes}, for details of the semantics of attributes 4655applying to functions. @xref{Variable Attributes}, for details of the 4656semantics of attributes applying to variables. @xref{Type Attributes}, 4657for details of the semantics of attributes applying to structure, union 4658and enumerated types. 4659@xref{Label Attributes}, for details of the semantics of attributes 4660applying to labels. 4661 4662An @dfn{attribute specifier} is of the form 4663@code{__attribute__ ((@var{attribute-list}))}. An @dfn{attribute list} 4664is a possibly empty comma-separated sequence of @dfn{attributes}, where 4665each attribute is one of the following: 4666 4667@itemize @bullet 4668@item 4669Empty. Empty attributes are ignored. 4670 4671@item 4672A word (which may be an identifier such as @code{unused}, or a reserved 4673word such as @code{const}). 4674 4675@item 4676A word, followed by, in parentheses, parameters for the attribute. 4677These parameters take one of the following forms: 4678 4679@itemize @bullet 4680@item 4681An identifier. For example, @code{mode} attributes use this form. 4682 4683@item 4684An identifier followed by a comma and a non-empty comma-separated list 4685of expressions. For example, @code{format} attributes use this form. 4686 4687@item 4688A possibly empty comma-separated list of expressions. For example, 4689@code{format_arg} attributes use this form with the list being a single 4690integer constant expression, and @code{alias} attributes use this form 4691with the list being a single string constant. 4692@end itemize 4693@end itemize 4694 4695An @dfn{attribute specifier list} is a sequence of one or more attribute 4696specifiers, not separated by any other tokens. 4697 4698@subsubheading Label Attributes 4699 4700In GNU C, an attribute specifier list may appear after the colon following a 4701label, other than a @code{case} or @code{default} label. GNU C++ only permits 4702attributes on labels if the attribute specifier is immediately 4703followed by a semicolon (i.e., the label applies to an empty 4704statement). If the semicolon is missing, C++ label attributes are 4705ambiguous, as it is permissible for a declaration, which could begin 4706with an attribute list, to be labelled in C++. Declarations cannot be 4707labelled in C90 or C99, so the ambiguity does not arise there. 4708 4709@subsubheading Type Attributes 4710 4711An attribute specifier list may appear as part of a @code{struct}, 4712@code{union} or @code{enum} specifier. It may go either immediately 4713after the @code{struct}, @code{union} or @code{enum} keyword, or after 4714the closing brace. The former syntax is preferred. 4715Where attribute specifiers follow the closing brace, they are considered 4716to relate to the structure, union or enumerated type defined, not to any 4717enclosing declaration the type specifier appears in, and the type 4718defined is not complete until after the attribute specifiers. 4719@c Otherwise, there would be the following problems: a shift/reduce 4720@c conflict between attributes binding the struct/union/enum and 4721@c binding to the list of specifiers/qualifiers; and "aligned" 4722@c attributes could use sizeof for the structure, but the size could be 4723@c changed later by "packed" attributes. 4724 4725 4726@subsubheading All other attributes 4727 4728Otherwise, an attribute specifier appears as part of a declaration, 4729counting declarations of unnamed parameters and type names, and relates 4730to that declaration (which may be nested in another declaration, for 4731example in the case of a parameter declaration), or to a particular declarator 4732within a declaration. Where an 4733attribute specifier is applied to a parameter declared as a function or 4734an array, it should apply to the function or array rather than the 4735pointer to which the parameter is implicitly converted, but this is not 4736yet correctly implemented. 4737 4738Any list of specifiers and qualifiers at the start of a declaration may 4739contain attribute specifiers, whether or not such a list may in that 4740context contain storage class specifiers. (Some attributes, however, 4741are essentially in the nature of storage class specifiers, and only make 4742sense where storage class specifiers may be used; for example, 4743@code{section}.) There is one necessary limitation to this syntax: the 4744first old-style parameter declaration in a function definition cannot 4745begin with an attribute specifier, because such an attribute applies to 4746the function instead by syntax described below (which, however, is not 4747yet implemented in this case). In some other cases, attribute 4748specifiers are permitted by this grammar but not yet supported by the 4749compiler. All attribute specifiers in this place relate to the 4750declaration as a whole. In the obsolescent usage where a type of 4751@code{int} is implied by the absence of type specifiers, such a list of 4752specifiers and qualifiers may be an attribute specifier list with no 4753other specifiers or qualifiers. 4754 4755At present, the first parameter in a function prototype must have some 4756type specifier that is not an attribute specifier; this resolves an 4757ambiguity in the interpretation of @code{void f(int 4758(__attribute__((foo)) x))}, but is subject to change. At present, if 4759the parentheses of a function declarator contain only attributes then 4760those attributes are ignored, rather than yielding an error or warning 4761or implying a single parameter of type int, but this is subject to 4762change. 4763 4764An attribute specifier list may appear immediately before a declarator 4765(other than the first) in a comma-separated list of declarators in a 4766declaration of more than one identifier using a single list of 4767specifiers and qualifiers. Such attribute specifiers apply 4768only to the identifier before whose declarator they appear. For 4769example, in 4770 4771@smallexample 4772__attribute__((noreturn)) void d0 (void), 4773 __attribute__((format(printf, 1, 2))) d1 (const char *, ...), 4774 d2 (void); 4775@end smallexample 4776 4777@noindent 4778the @code{noreturn} attribute applies to all the functions 4779declared; the @code{format} attribute only applies to @code{d1}. 4780 4781An attribute specifier list may appear immediately before the comma, 4782@code{=} or semicolon terminating the declaration of an identifier other 4783than a function definition. Such attribute specifiers apply 4784to the declared object or function. Where an 4785assembler name for an object or function is specified (@pxref{Asm 4786Labels}), the attribute must follow the @code{asm} 4787specification. 4788 4789An attribute specifier list may, in future, be permitted to appear after 4790the declarator in a function definition (before any old-style parameter 4791declarations or the function body). 4792 4793Attribute specifiers may be mixed with type qualifiers appearing inside 4794the @code{[]} of a parameter array declarator, in the C99 construct by 4795which such qualifiers are applied to the pointer to which the array is 4796implicitly converted. Such attribute specifiers apply to the pointer, 4797not to the array, but at present this is not implemented and they are 4798ignored. 4799 4800An attribute specifier list may appear at the start of a nested 4801declarator. At present, there are some limitations in this usage: the 4802attributes correctly apply to the declarator, but for most individual 4803attributes the semantics this implies are not implemented. 4804When attribute specifiers follow the @code{*} of a pointer 4805declarator, they may be mixed with any type qualifiers present. 4806The following describes the formal semantics of this syntax. It makes the 4807most sense if you are familiar with the formal specification of 4808declarators in the ISO C standard. 4809 4810Consider (as in C99 subclause 6.7.5 paragraph 4) a declaration @code{T 4811D1}, where @code{T} contains declaration specifiers that specify a type 4812@var{Type} (such as @code{int}) and @code{D1} is a declarator that 4813contains an identifier @var{ident}. The type specified for @var{ident} 4814for derived declarators whose type does not include an attribute 4815specifier is as in the ISO C standard. 4816 4817If @code{D1} has the form @code{( @var{attribute-specifier-list} D )}, 4818and the declaration @code{T D} specifies the type 4819``@var{derived-declarator-type-list} @var{Type}'' for @var{ident}, then 4820@code{T D1} specifies the type ``@var{derived-declarator-type-list} 4821@var{attribute-specifier-list} @var{Type}'' for @var{ident}. 4822 4823If @code{D1} has the form @code{* 4824@var{type-qualifier-and-attribute-specifier-list} D}, and the 4825declaration @code{T D} specifies the type 4826``@var{derived-declarator-type-list} @var{Type}'' for @var{ident}, then 4827@code{T D1} specifies the type ``@var{derived-declarator-type-list} 4828@var{type-qualifier-and-attribute-specifier-list} pointer to @var{Type}'' for 4829@var{ident}. 4830 4831For example, 4832 4833@smallexample 4834void (__attribute__((noreturn)) ****f) (void); 4835@end smallexample 4836 4837@noindent 4838specifies the type ``pointer to pointer to pointer to pointer to 4839non-returning function returning @code{void}''. As another example, 4840 4841@smallexample 4842char *__attribute__((aligned(8))) *f; 4843@end smallexample 4844 4845@noindent 4846specifies the type ``pointer to 8-byte-aligned pointer to @code{char}''. 4847Note again that this does not work with most attributes; for example, 4848the usage of @samp{aligned} and @samp{noreturn} attributes given above 4849is not yet supported. 4850 4851For compatibility with existing code written for compiler versions that 4852did not implement attributes on nested declarators, some laxity is 4853allowed in the placing of attributes. If an attribute that only applies 4854to types is applied to a declaration, it is treated as applying to 4855the type of that declaration. If an attribute that only applies to 4856declarations is applied to the type of a declaration, it is treated 4857as applying to that declaration; and, for compatibility with code 4858placing the attributes immediately before the identifier declared, such 4859an attribute applied to a function return type is treated as 4860applying to the function type, and such an attribute applied to an array 4861element type is treated as applying to the array type. If an 4862attribute that only applies to function types is applied to a 4863pointer-to-function type, it is treated as applying to the pointer 4864target type; if such an attribute is applied to a function return type 4865that is not a pointer-to-function type, it is treated as applying 4866to the function type. 4867 4868@node Function Prototypes 4869@section Prototypes and Old-Style Function Definitions 4870@cindex function prototype declarations 4871@cindex old-style function definitions 4872@cindex promotion of formal parameters 4873 4874GNU C extends ISO C to allow a function prototype to override a later 4875old-style non-prototype definition. Consider the following example: 4876 4877@smallexample 4878/* @r{Use prototypes unless the compiler is old-fashioned.} */ 4879#ifdef __STDC__ 4880#define P(x) x 4881#else 4882#define P(x) () 4883#endif 4884 4885/* @r{Prototype function declaration.} */ 4886int isroot P((uid_t)); 4887 4888/* @r{Old-style function definition.} */ 4889int 4890isroot (x) /* @r{??? lossage here ???} */ 4891 uid_t x; 4892@{ 4893 return x == 0; 4894@} 4895@end smallexample 4896 4897Suppose the type @code{uid_t} happens to be @code{short}. ISO C does 4898not allow this example, because subword arguments in old-style 4899non-prototype definitions are promoted. Therefore in this example the 4900function definition's argument is really an @code{int}, which does not 4901match the prototype argument type of @code{short}. 4902 4903This restriction of ISO C makes it hard to write code that is portable 4904to traditional C compilers, because the programmer does not know 4905whether the @code{uid_t} type is @code{short}, @code{int}, or 4906@code{long}. Therefore, in cases like these GNU C allows a prototype 4907to override a later old-style definition. More precisely, in GNU C, a 4908function prototype argument type overrides the argument type specified 4909by a later old-style definition if the former type is the same as the 4910latter type before promotion. Thus in GNU C the above example is 4911equivalent to the following: 4912 4913@smallexample 4914int isroot (uid_t); 4915 4916int 4917isroot (uid_t x) 4918@{ 4919 return x == 0; 4920@} 4921@end smallexample 4922 4923@noindent 4924GNU C++ does not support old-style function definitions, so this 4925extension is irrelevant. 4926 4927@node C++ Comments 4928@section C++ Style Comments 4929@cindex @code{//} 4930@cindex C++ comments 4931@cindex comments, C++ style 4932 4933In GNU C, you may use C++ style comments, which start with @samp{//} and 4934continue until the end of the line. Many other C implementations allow 4935such comments, and they are included in the 1999 C standard. However, 4936C++ style comments are not recognized if you specify an @option{-std} 4937option specifying a version of ISO C before C99, or @option{-ansi} 4938(equivalent to @option{-std=c90}). 4939 4940@node Dollar Signs 4941@section Dollar Signs in Identifier Names 4942@cindex $ 4943@cindex dollar signs in identifier names 4944@cindex identifier names, dollar signs in 4945 4946In GNU C, you may normally use dollar signs in identifier names. 4947This is because many traditional C implementations allow such identifiers. 4948However, dollar signs in identifiers are not supported on a few target 4949machines, typically because the target assembler does not allow them. 4950 4951@node Character Escapes 4952@section The Character @key{ESC} in Constants 4953 4954You can use the sequence @samp{\e} in a string or character constant to 4955stand for the ASCII character @key{ESC}. 4956 4957@node Variable Attributes 4958@section Specifying Attributes of Variables 4959@cindex attribute of variables 4960@cindex variable attributes 4961 4962The keyword @code{__attribute__} allows you to specify special 4963attributes of variables or structure fields. This keyword is followed 4964by an attribute specification inside double parentheses. Some 4965attributes are currently defined generically for variables. 4966Other attributes are defined for variables on particular target 4967systems. Other attributes are available for functions 4968(@pxref{Function Attributes}), labels (@pxref{Label Attributes}) and for 4969types (@pxref{Type Attributes}). 4970Other front ends might define more attributes 4971(@pxref{C++ Extensions,,Extensions to the C++ Language}). 4972 4973You may also specify attributes with @samp{__} preceding and following 4974each keyword. This allows you to use them in header files without 4975being concerned about a possible macro of the same name. For example, 4976you may use @code{__aligned__} instead of @code{aligned}. 4977 4978@xref{Attribute Syntax}, for details of the exact syntax for using 4979attributes. 4980 4981@table @code 4982@cindex @code{aligned} variable attribute 4983@item aligned (@var{alignment}) 4984This attribute specifies a minimum alignment for the variable or 4985structure field, measured in bytes. For example, the declaration: 4986 4987@smallexample 4988int x __attribute__ ((aligned (16))) = 0; 4989@end smallexample 4990 4991@noindent 4992causes the compiler to allocate the global variable @code{x} on a 499316-byte boundary. On a 68040, this could be used in conjunction with 4994an @code{asm} expression to access the @code{move16} instruction which 4995requires 16-byte aligned operands. 4996 4997You can also specify the alignment of structure fields. For example, to 4998create a double-word aligned @code{int} pair, you could write: 4999 5000@smallexample 5001struct foo @{ int x[2] __attribute__ ((aligned (8))); @}; 5002@end smallexample 5003 5004@noindent 5005This is an alternative to creating a union with a @code{double} member, 5006which forces the union to be double-word aligned. 5007 5008As in the preceding examples, you can explicitly specify the alignment 5009(in bytes) that you wish the compiler to use for a given variable or 5010structure field. Alternatively, you can leave out the alignment factor 5011and just ask the compiler to align a variable or field to the 5012default alignment for the target architecture you are compiling for. 5013The default alignment is sufficient for all scalar types, but may not be 5014enough for all vector types on a target that supports vector operations. 5015The default alignment is fixed for a particular target ABI. 5016 5017GCC also provides a target specific macro @code{__BIGGEST_ALIGNMENT__}, 5018which is the largest alignment ever used for any data type on the 5019target machine you are compiling for. For example, you could write: 5020 5021@smallexample 5022short array[3] __attribute__ ((aligned (__BIGGEST_ALIGNMENT__))); 5023@end smallexample 5024 5025The compiler automatically sets the alignment for the declared 5026variable or field to @code{__BIGGEST_ALIGNMENT__}. Doing this can 5027often make copy operations more efficient, because the compiler can 5028use whatever instructions copy the biggest chunks of memory when 5029performing copies to or from the variables or fields that you have 5030aligned this way. Note that the value of @code{__BIGGEST_ALIGNMENT__} 5031may change depending on command-line options. 5032 5033When used on a struct, or struct member, the @code{aligned} attribute can 5034only increase the alignment; in order to decrease it, the @code{packed} 5035attribute must be specified as well. When used as part of a typedef, the 5036@code{aligned} attribute can both increase and decrease alignment, and 5037specifying the @code{packed} attribute generates a warning. 5038 5039Note that the effectiveness of @code{aligned} attributes may be limited 5040by inherent limitations in your linker. On many systems, the linker is 5041only able to arrange for variables to be aligned up to a certain maximum 5042alignment. (For some linkers, the maximum supported alignment may 5043be very very small.) If your linker is only able to align variables 5044up to a maximum of 8-byte alignment, then specifying @code{aligned(16)} 5045in an @code{__attribute__} still only provides you with 8-byte 5046alignment. See your linker documentation for further information. 5047 5048The @code{aligned} attribute can also be used for functions 5049(@pxref{Function Attributes}.) 5050 5051@item cleanup (@var{cleanup_function}) 5052@cindex @code{cleanup} variable attribute 5053The @code{cleanup} attribute runs a function when the variable goes 5054out of scope. This attribute can only be applied to auto function 5055scope variables; it may not be applied to parameters or variables 5056with static storage duration. The function must take one parameter, 5057a pointer to a type compatible with the variable. The return value 5058of the function (if any) is ignored. 5059 5060If @option{-fexceptions} is enabled, then @var{cleanup_function} 5061is run during the stack unwinding that happens during the 5062processing of the exception. Note that the @code{cleanup} attribute 5063does not allow the exception to be caught, only to perform an action. 5064It is undefined what happens if @var{cleanup_function} does not 5065return normally. 5066 5067@item common 5068@itemx nocommon 5069@cindex @code{common} variable attribute 5070@cindex @code{nocommon} variable attribute 5071@opindex fcommon 5072@opindex fno-common 5073The @code{common} attribute requests GCC to place a variable in 5074``common'' storage. The @code{nocommon} attribute requests the 5075opposite---to allocate space for it directly. 5076 5077These attributes override the default chosen by the 5078@option{-fno-common} and @option{-fcommon} flags respectively. 5079 5080@item deprecated 5081@itemx deprecated (@var{msg}) 5082@cindex @code{deprecated} variable attribute 5083The @code{deprecated} attribute results in a warning if the variable 5084is used anywhere in the source file. This is useful when identifying 5085variables that are expected to be removed in a future version of a 5086program. The warning also includes the location of the declaration 5087of the deprecated variable, to enable users to easily find further 5088information about why the variable is deprecated, or what they should 5089do instead. Note that the warning only occurs for uses: 5090 5091@smallexample 5092extern int old_var __attribute__ ((deprecated)); 5093extern int old_var; 5094int new_fn () @{ return old_var; @} 5095@end smallexample 5096 5097@noindent 5098results in a warning on line 3 but not line 2. The optional @var{msg} 5099argument, which must be a string, is printed in the warning if 5100present. 5101 5102The @code{deprecated} attribute can also be used for functions and 5103types (@pxref{Function Attributes}, @pxref{Type Attributes}.) 5104 5105@item mode (@var{mode}) 5106@cindex @code{mode} variable attribute 5107This attribute specifies the data type for the declaration---whichever 5108type corresponds to the mode @var{mode}. This in effect lets you 5109request an integer or floating-point type according to its width. 5110 5111You may also specify a mode of @code{byte} or @code{__byte__} to 5112indicate the mode corresponding to a one-byte integer, @code{word} or 5113@code{__word__} for the mode of a one-word integer, and @code{pointer} 5114or @code{__pointer__} for the mode used to represent pointers. 5115 5116@item packed 5117@cindex @code{packed} variable attribute 5118The @code{packed} attribute specifies that a variable or structure field 5119should have the smallest possible alignment---one byte for a variable, 5120and one bit for a field, unless you specify a larger value with the 5121@code{aligned} attribute. 5122 5123Here is a structure in which the field @code{x} is packed, so that it 5124immediately follows @code{a}: 5125 5126@smallexample 5127struct foo 5128@{ 5129 char a; 5130 int x[2] __attribute__ ((packed)); 5131@}; 5132@end smallexample 5133 5134@emph{Note:} The 4.1, 4.2 and 4.3 series of GCC ignore the 5135@code{packed} attribute on bit-fields of type @code{char}. This has 5136been fixed in GCC 4.4 but the change can lead to differences in the 5137structure layout. See the documentation of 5138@option{-Wpacked-bitfield-compat} for more information. 5139 5140@item section ("@var{section-name}") 5141@cindex @code{section} variable attribute 5142Normally, the compiler places the objects it generates in sections like 5143@code{data} and @code{bss}. Sometimes, however, you need additional sections, 5144or you need certain particular variables to appear in special sections, 5145for example to map to special hardware. The @code{section} 5146attribute specifies that a variable (or function) lives in a particular 5147section. For example, this small program uses several specific section names: 5148 5149@smallexample 5150struct duart a __attribute__ ((section ("DUART_A"))) = @{ 0 @}; 5151struct duart b __attribute__ ((section ("DUART_B"))) = @{ 0 @}; 5152char stack[10000] __attribute__ ((section ("STACK"))) = @{ 0 @}; 5153int init_data __attribute__ ((section ("INITDATA"))); 5154 5155main() 5156@{ 5157 /* @r{Initialize stack pointer} */ 5158 init_sp (stack + sizeof (stack)); 5159 5160 /* @r{Initialize initialized data} */ 5161 memcpy (&init_data, &data, &edata - &data); 5162 5163 /* @r{Turn on the serial ports} */ 5164 init_duart (&a); 5165 init_duart (&b); 5166@} 5167@end smallexample 5168 5169@noindent 5170Use the @code{section} attribute with 5171@emph{global} variables and not @emph{local} variables, 5172as shown in the example. 5173 5174You may use the @code{section} attribute with initialized or 5175uninitialized global variables but the linker requires 5176each object be defined once, with the exception that uninitialized 5177variables tentatively go in the @code{common} (or @code{bss}) section 5178and can be multiply ``defined''. Using the @code{section} attribute 5179changes what section the variable goes into and may cause the 5180linker to issue an error if an uninitialized variable has multiple 5181definitions. You can force a variable to be initialized with the 5182@option{-fno-common} flag or the @code{nocommon} attribute. 5183 5184Some file formats do not support arbitrary sections so the @code{section} 5185attribute is not available on all platforms. 5186If you need to map the entire contents of a module to a particular 5187section, consider using the facilities of the linker instead. 5188 5189@item shared 5190@cindex @code{shared} variable attribute 5191On Microsoft Windows, in addition to putting variable definitions in a named 5192section, the section can also be shared among all running copies of an 5193executable or DLL@. For example, this small program defines shared data 5194by putting it in a named section @code{shared} and marking the section 5195shareable: 5196 5197@smallexample 5198int foo __attribute__((section ("shared"), shared)) = 0; 5199 5200int 5201main() 5202@{ 5203 /* @r{Read and write foo. All running 5204 copies see the same value.} */ 5205 return 0; 5206@} 5207@end smallexample 5208 5209@noindent 5210You may only use the @code{shared} attribute along with @code{section} 5211attribute with a fully-initialized global definition because of the way 5212linkers work. See @code{section} attribute for more information. 5213 5214The @code{shared} attribute is only available on Microsoft Windows@. 5215 5216@item tls_model ("@var{tls_model}") 5217@cindex @code{tls_model} variable attribute 5218The @code{tls_model} attribute sets thread-local storage model 5219(@pxref{Thread-Local}) of a particular @code{__thread} variable, 5220overriding @option{-ftls-model=} command-line switch on a per-variable 5221basis. 5222The @var{tls_model} argument should be one of @code{global-dynamic}, 5223@code{local-dynamic}, @code{initial-exec} or @code{local-exec}. 5224 5225Not all targets support this attribute. 5226 5227@item unused 5228@cindex @code{unused} variable attribute 5229This attribute, attached to a variable, means that the variable is meant 5230to be possibly unused. GCC does not produce a warning for this 5231variable. 5232 5233@item used 5234@cindex @code{used} variable attribute 5235This attribute, attached to a variable with static storage, means that 5236the variable must be emitted even if it appears that the variable is not 5237referenced. 5238 5239When applied to a static data member of a C++ class template, the 5240attribute also means that the member is instantiated if the 5241class itself is instantiated. 5242 5243@item vector_size (@var{bytes}) 5244@cindex @code{vector_size} variable attribute 5245This attribute specifies the vector size for the variable, measured in 5246bytes. For example, the declaration: 5247 5248@smallexample 5249int foo __attribute__ ((vector_size (16))); 5250@end smallexample 5251 5252@noindent 5253causes the compiler to set the mode for @code{foo}, to be 16 bytes, 5254divided into @code{int} sized units. Assuming a 32-bit int (a vector of 52554 units of 4 bytes), the corresponding mode of @code{foo} is V4SI@. 5256 5257This attribute is only applicable to integral and float scalars, 5258although arrays, pointers, and function return values are allowed in 5259conjunction with this construct. 5260 5261Aggregates with this attribute are invalid, even if they are of the same 5262size as a corresponding scalar. For example, the declaration: 5263 5264@smallexample 5265struct S @{ int a; @}; 5266struct S __attribute__ ((vector_size (16))) foo; 5267@end smallexample 5268 5269@noindent 5270is invalid even if the size of the structure is the same as the size of 5271the @code{int}. 5272 5273@item selectany 5274@cindex @code{selectany} variable attribute 5275The @code{selectany} attribute causes an initialized global variable to 5276have link-once semantics. When multiple definitions of the variable are 5277encountered by the linker, the first is selected and the remainder are 5278discarded. Following usage by the Microsoft compiler, the linker is told 5279@emph{not} to warn about size or content differences of the multiple 5280definitions. 5281 5282Although the primary usage of this attribute is for POD types, the 5283attribute can also be applied to global C++ objects that are initialized 5284by a constructor. In this case, the static initialization and destruction 5285code for the object is emitted in each translation defining the object, 5286but the calls to the constructor and destructor are protected by a 5287link-once guard variable. 5288 5289The @code{selectany} attribute is only available on Microsoft Windows 5290targets. You can use @code{__declspec (selectany)} as a synonym for 5291@code{__attribute__ ((selectany))} for compatibility with other 5292compilers. 5293 5294@item weak 5295@cindex @code{weak} variable attribute 5296The @code{weak} attribute is described in @ref{Function Attributes}. 5297 5298@item dllimport 5299@cindex @code{dllimport} variable attribute 5300The @code{dllimport} attribute is described in @ref{Function Attributes}. 5301 5302@item dllexport 5303@cindex @code{dllexport} variable attribute 5304The @code{dllexport} attribute is described in @ref{Function Attributes}. 5305 5306@end table 5307 5308@anchor{AVR Variable Attributes} 5309@subsection AVR Variable Attributes 5310 5311@table @code 5312@item progmem 5313@cindex @code{progmem} variable attribute, AVR 5314The @code{progmem} attribute is used on the AVR to place read-only 5315data in the non-volatile program memory (flash). The @code{progmem} 5316attribute accomplishes this by putting respective variables into a 5317section whose name starts with @code{.progmem}. 5318 5319This attribute works similar to the @code{section} attribute 5320but adds additional checking. Notice that just like the 5321@code{section} attribute, @code{progmem} affects the location 5322of the data but not how this data is accessed. 5323 5324In order to read data located with the @code{progmem} attribute 5325(inline) assembler must be used. 5326@smallexample 5327/* Use custom macros from @w{@uref{http://nongnu.org/avr-libc/user-manual/,AVR-LibC}} */ 5328#include <avr/pgmspace.h> 5329 5330/* Locate var in flash memory */ 5331const int var[2] PROGMEM = @{ 1, 2 @}; 5332 5333int read_var (int i) 5334@{ 5335 /* Access var[] by accessor macro from avr/pgmspace.h */ 5336 return (int) pgm_read_word (& var[i]); 5337@} 5338@end smallexample 5339 5340AVR is a Harvard architecture processor and data and read-only data 5341normally resides in the data memory (RAM). 5342 5343See also the @ref{AVR Named Address Spaces} section for 5344an alternate way to locate and access data in flash memory. 5345 5346@item io 5347@itemx io (@var{addr}) 5348@cindex @code{io} variable attribute, AVR 5349Variables with the @code{io} attribute are used to address 5350memory-mapped peripherals in the io address range. 5351If an address is specified, the variable 5352is assigned that address, and the value is interpreted as an 5353address in the data address space. 5354Example: 5355 5356@smallexample 5357volatile int porta __attribute__((io (0x22))); 5358@end smallexample 5359 5360The address specified in the address in the data address range. 5361 5362Otherwise, the variable it is not assigned an address, but the 5363compiler will still use in/out instructions where applicable, 5364assuming some other module assigns an address in the io address range. 5365Example: 5366 5367@smallexample 5368extern volatile int porta __attribute__((io)); 5369@end smallexample 5370 5371@item io_low 5372@itemx io_low (@var{addr}) 5373@cindex @code{io_low} variable attribute, AVR 5374This is like the @code{io} attribute, but additionally it informs the 5375compiler that the object lies in the lower half of the I/O area, 5376allowing the use of @code{cbi}, @code{sbi}, @code{sbic} and @code{sbis} 5377instructions. 5378 5379@item address 5380@itemx address (@var{addr}) 5381@cindex @code{address} variable attribute, AVR 5382Variables with the @code{address} attribute are used to address 5383memory-mapped peripherals that may lie outside the io address range. 5384 5385@smallexample 5386volatile int porta __attribute__((address (0x600))); 5387@end smallexample 5388 5389@end table 5390 5391@subsection Blackfin Variable Attributes 5392 5393Three attributes are currently defined for the Blackfin. 5394 5395@table @code 5396@item l1_data 5397@itemx l1_data_A 5398@itemx l1_data_B 5399@cindex @code{l1_data} variable attribute, Blackfin 5400@cindex @code{l1_data_A} variable attribute, Blackfin 5401@cindex @code{l1_data_B} variable attribute, Blackfin 5402Use these attributes on the Blackfin to place the variable into L1 Data SRAM. 5403Variables with @code{l1_data} attribute are put into the specific section 5404named @code{.l1.data}. Those with @code{l1_data_A} attribute are put into 5405the specific section named @code{.l1.data.A}. Those with @code{l1_data_B} 5406attribute are put into the specific section named @code{.l1.data.B}. 5407 5408@item l2 5409@cindex @code{l2} variable attribute, Blackfin 5410Use this attribute on the Blackfin to place the variable into L2 SRAM. 5411Variables with @code{l2} attribute are put into the specific section 5412named @code{.l2.data}. 5413@end table 5414 5415@subsection H8/300 Variable Attributes 5416 5417These variable attributes are available for H8/300 targets: 5418 5419@table @code 5420@item eightbit_data 5421@cindex @code{eightbit_data} variable attribute, H8/300 5422@cindex eight-bit data on the H8/300, H8/300H, and H8S 5423Use this attribute on the H8/300, H8/300H, and H8S to indicate that the specified 5424variable should be placed into the eight-bit data section. 5425The compiler generates more efficient code for certain operations 5426on data in the eight-bit data area. Note the eight-bit data area is limited to 5427256 bytes of data. 5428 5429You must use GAS and GLD from GNU binutils version 2.7 or later for 5430this attribute to work correctly. 5431 5432@item tiny_data 5433@cindex @code{tiny_data} variable attribute, H8/300 5434@cindex tiny data section on the H8/300H and H8S 5435Use this attribute on the H8/300H and H8S to indicate that the specified 5436variable should be placed into the tiny data section. 5437The compiler generates more efficient code for loads and stores 5438on data in the tiny data section. Note the tiny data area is limited to 5439slightly under 32KB of data. 5440 5441@end table 5442 5443@subsection IA-64 Variable Attributes 5444 5445The IA-64 back end supports the following variable attribute: 5446 5447@table @code 5448@item model (@var{model-name}) 5449@cindex @code{model} variable attribute, IA-64 5450 5451On IA-64, use this attribute to set the addressability of an object. 5452At present, the only supported identifier for @var{model-name} is 5453@code{small}, indicating addressability via ``small'' (22-bit) 5454addresses (so that their addresses can be loaded with the @code{addl} 5455instruction). Caveat: such addressing is by definition not position 5456independent and hence this attribute must not be used for objects 5457defined by shared libraries. 5458 5459@end table 5460 5461@subsection M32R/D Variable Attributes 5462 5463One attribute is currently defined for the M32R/D@. 5464 5465@table @code 5466@item model (@var{model-name}) 5467@cindex @code{model-name} variable attribute, M32R/D 5468@cindex variable addressability on the M32R/D 5469Use this attribute on the M32R/D to set the addressability of an object. 5470The identifier @var{model-name} is one of @code{small}, @code{medium}, 5471or @code{large}, representing each of the code models. 5472 5473Small model objects live in the lower 16MB of memory (so that their 5474addresses can be loaded with the @code{ld24} instruction). 5475 5476Medium and large model objects may live anywhere in the 32-bit address space 5477(the compiler generates @code{seth/add3} instructions to load their 5478addresses). 5479@end table 5480 5481@anchor{MeP Variable Attributes} 5482@subsection MeP Variable Attributes 5483 5484The MeP target has a number of addressing modes and busses. The 5485@code{near} space spans the standard memory space's first 16 megabytes 5486(24 bits). The @code{far} space spans the entire 32-bit memory space. 5487The @code{based} space is a 128-byte region in the memory space that 5488is addressed relative to the @code{$tp} register. The @code{tiny} 5489space is a 65536-byte region relative to the @code{$gp} register. In 5490addition to these memory regions, the MeP target has a separate 16-bit 5491control bus which is specified with @code{cb} attributes. 5492 5493@table @code 5494 5495@item based 5496@cindex @code{based} variable attribute, MeP 5497Any variable with the @code{based} attribute is assigned to the 5498@code{.based} section, and is accessed with relative to the 5499@code{$tp} register. 5500 5501@item tiny 5502@cindex @code{tiny} variable attribute, MeP 5503Likewise, the @code{tiny} attribute assigned variables to the 5504@code{.tiny} section, relative to the @code{$gp} register. 5505 5506@item near 5507@cindex @code{near} variable attribute, MeP 5508Variables with the @code{near} attribute are assumed to have addresses 5509that fit in a 24-bit addressing mode. This is the default for large 5510variables (@code{-mtiny=4} is the default) but this attribute can 5511override @code{-mtiny=} for small variables, or override @code{-ml}. 5512 5513@item far 5514@cindex @code{far} variable attribute, MeP 5515Variables with the @code{far} attribute are addressed using a full 551632-bit address. Since this covers the entire memory space, this 5517allows modules to make no assumptions about where variables might be 5518stored. 5519 5520@item io 5521@cindex @code{io} variable attribute, MeP 5522@itemx io (@var{addr}) 5523Variables with the @code{io} attribute are used to address 5524memory-mapped peripherals. If an address is specified, the variable 5525is assigned that address, else it is not assigned an address (it is 5526assumed some other module assigns an address). Example: 5527 5528@smallexample 5529int timer_count __attribute__((io(0x123))); 5530@end smallexample 5531 5532@item cb 5533@itemx cb (@var{addr}) 5534@cindex @code{cb} variable attribute, MeP 5535Variables with the @code{cb} attribute are used to access the control 5536bus, using special instructions. @code{addr} indicates the control bus 5537address. Example: 5538 5539@smallexample 5540int cpu_clock __attribute__((cb(0x123))); 5541@end smallexample 5542 5543@end table 5544 5545@subsection PowerPC Variable Attributes 5546 5547Three attributes currently are defined for PowerPC configurations: 5548@code{altivec}, @code{ms_struct} and @code{gcc_struct}. 5549 5550@cindex @code{ms_struct} variable attribute, PowerPC 5551@cindex @code{gcc_struct} variable attribute, PowerPC 5552For full documentation of the struct attributes please see the 5553documentation in @ref{x86 Variable Attributes}. 5554 5555@cindex @code{altivec} variable attribute, PowerPC 5556For documentation of @code{altivec} attribute please see the 5557documentation in @ref{PowerPC Type Attributes}. 5558 5559@subsection SPU Variable Attributes 5560 5561@cindex @code{spu_vector} variable attribute, SPU 5562The SPU supports the @code{spu_vector} attribute for variables. For 5563documentation of this attribute please see the documentation in 5564@ref{SPU Type Attributes}. 5565 5566@anchor{x86 Variable Attributes} 5567@subsection x86 Variable Attributes 5568 5569Two attributes are currently defined for x86 configurations: 5570@code{ms_struct} and @code{gcc_struct}. 5571 5572@table @code 5573@item ms_struct 5574@itemx gcc_struct 5575@cindex @code{ms_struct} variable attribute, x86 5576@cindex @code{gcc_struct} variable attribute, x86 5577 5578If @code{packed} is used on a structure, or if bit-fields are used, 5579it may be that the Microsoft ABI lays out the structure differently 5580than the way GCC normally does. Particularly when moving packed 5581data between functions compiled with GCC and the native Microsoft compiler 5582(either via function call or as data in a file), it may be necessary to access 5583either format. 5584 5585Currently @option{-m[no-]ms-bitfields} is provided for the Microsoft Windows x86 5586compilers to match the native Microsoft compiler. 5587 5588The Microsoft structure layout algorithm is fairly simple with the exception 5589of the bit-field packing. 5590The padding and alignment of members of structures and whether a bit-field 5591can straddle a storage-unit boundary are determine by these rules: 5592 5593@enumerate 5594@item Structure members are stored sequentially in the order in which they are 5595declared: the first member has the lowest memory address and the last member 5596the highest. 5597 5598@item Every data object has an alignment requirement. The alignment requirement 5599for all data except structures, unions, and arrays is either the size of the 5600object or the current packing size (specified with either the 5601@code{aligned} attribute or the @code{pack} pragma), 5602whichever is less. For structures, unions, and arrays, 5603the alignment requirement is the largest alignment requirement of its members. 5604Every object is allocated an offset so that: 5605 5606@smallexample 5607offset % alignment_requirement == 0 5608@end smallexample 5609 5610@item Adjacent bit-fields are packed into the same 1-, 2-, or 4-byte allocation 5611unit if the integral types are the same size and if the next bit-field fits 5612into the current allocation unit without crossing the boundary imposed by the 5613common alignment requirements of the bit-fields. 5614@end enumerate 5615 5616MSVC interprets zero-length bit-fields in the following ways: 5617 5618@enumerate 5619@item If a zero-length bit-field is inserted between two bit-fields that 5620are normally coalesced, the bit-fields are not coalesced. 5621 5622For example: 5623 5624@smallexample 5625struct 5626 @{ 5627 unsigned long bf_1 : 12; 5628 unsigned long : 0; 5629 unsigned long bf_2 : 12; 5630 @} t1; 5631@end smallexample 5632 5633@noindent 5634The size of @code{t1} is 8 bytes with the zero-length bit-field. If the 5635zero-length bit-field were removed, @code{t1}'s size would be 4 bytes. 5636 5637@item If a zero-length bit-field is inserted after a bit-field, @code{foo}, and the 5638alignment of the zero-length bit-field is greater than the member that follows it, 5639@code{bar}, @code{bar} is aligned as the type of the zero-length bit-field. 5640 5641For example: 5642 5643@smallexample 5644struct 5645 @{ 5646 char foo : 4; 5647 short : 0; 5648 char bar; 5649 @} t2; 5650 5651struct 5652 @{ 5653 char foo : 4; 5654 short : 0; 5655 double bar; 5656 @} t3; 5657@end smallexample 5658 5659@noindent 5660For @code{t2}, @code{bar} is placed at offset 2, rather than offset 1. 5661Accordingly, the size of @code{t2} is 4. For @code{t3}, the zero-length 5662bit-field does not affect the alignment of @code{bar} or, as a result, the size 5663of the structure. 5664 5665Taking this into account, it is important to note the following: 5666 5667@enumerate 5668@item If a zero-length bit-field follows a normal bit-field, the type of the 5669zero-length bit-field may affect the alignment of the structure as whole. For 5670example, @code{t2} has a size of 4 bytes, since the zero-length bit-field follows a 5671normal bit-field, and is of type short. 5672 5673@item Even if a zero-length bit-field is not followed by a normal bit-field, it may 5674still affect the alignment of the structure: 5675 5676@smallexample 5677struct 5678 @{ 5679 char foo : 6; 5680 long : 0; 5681 @} t4; 5682@end smallexample 5683 5684@noindent 5685Here, @code{t4} takes up 4 bytes. 5686@end enumerate 5687 5688@item Zero-length bit-fields following non-bit-field members are ignored: 5689 5690@smallexample 5691struct 5692 @{ 5693 char foo; 5694 long : 0; 5695 char bar; 5696 @} t5; 5697@end smallexample 5698 5699@noindent 5700Here, @code{t5} takes up 2 bytes. 5701@end enumerate 5702@end table 5703 5704@subsection Xstormy16 Variable Attributes 5705 5706One attribute is currently defined for xstormy16 configurations: 5707@code{below100}. 5708 5709@table @code 5710@item below100 5711@cindex @code{below100} variable attribute, Xstormy16 5712 5713If a variable has the @code{below100} attribute (@code{BELOW100} is 5714allowed also), GCC places the variable in the first 0x100 bytes of 5715memory and use special opcodes to access it. Such variables are 5716placed in either the @code{.bss_below100} section or the 5717@code{.data_below100} section. 5718 5719@end table 5720 5721@node Type Attributes 5722@section Specifying Attributes of Types 5723@cindex attribute of types 5724@cindex type attributes 5725 5726The keyword @code{__attribute__} allows you to specify special 5727attributes of @code{struct} and @code{union} types when you define 5728such types. This keyword is followed by an attribute specification 5729inside double parentheses. Eight attributes are currently defined for 5730types: @code{aligned}, @code{packed}, @code{transparent_union}, 5731@code{unused}, @code{deprecated}, @code{visibility}, @code{may_alias} 5732and @code{bnd_variable_size}. Other attributes are defined for 5733functions (@pxref{Function Attributes}), labels (@pxref{Label 5734Attributes}) and for variables (@pxref{Variable Attributes}). 5735 5736You may also specify any one of these attributes with @samp{__} 5737preceding and following its keyword. This allows you to use these 5738attributes in header files without being concerned about a possible 5739macro of the same name. For example, you may use @code{__aligned__} 5740instead of @code{aligned}. 5741 5742You may specify type attributes in an enum, struct or union type 5743declaration or definition, or for other types in a @code{typedef} 5744declaration. 5745 5746For an enum, struct or union type, you may specify attributes either 5747between the enum, struct or union tag and the name of the type, or 5748just past the closing curly brace of the @emph{definition}. The 5749former syntax is preferred. 5750 5751@xref{Attribute Syntax}, for details of the exact syntax for using 5752attributes. 5753 5754@table @code 5755@cindex @code{aligned} type attribute 5756@item aligned (@var{alignment}) 5757This attribute specifies a minimum alignment (in bytes) for variables 5758of the specified type. For example, the declarations: 5759 5760@smallexample 5761struct S @{ short f[3]; @} __attribute__ ((aligned (8))); 5762typedef int more_aligned_int __attribute__ ((aligned (8))); 5763@end smallexample 5764 5765@noindent 5766force the compiler to ensure (as far as it can) that each variable whose 5767type is @code{struct S} or @code{more_aligned_int} is allocated and 5768aligned @emph{at least} on a 8-byte boundary. On a SPARC, having all 5769variables of type @code{struct S} aligned to 8-byte boundaries allows 5770the compiler to use the @code{ldd} and @code{std} (doubleword load and 5771store) instructions when copying one variable of type @code{struct S} to 5772another, thus improving run-time efficiency. 5773 5774Note that the alignment of any given @code{struct} or @code{union} type 5775is required by the ISO C standard to be at least a perfect multiple of 5776the lowest common multiple of the alignments of all of the members of 5777the @code{struct} or @code{union} in question. This means that you @emph{can} 5778effectively adjust the alignment of a @code{struct} or @code{union} 5779type by attaching an @code{aligned} attribute to any one of the members 5780of such a type, but the notation illustrated in the example above is a 5781more obvious, intuitive, and readable way to request the compiler to 5782adjust the alignment of an entire @code{struct} or @code{union} type. 5783 5784As in the preceding example, you can explicitly specify the alignment 5785(in bytes) that you wish the compiler to use for a given @code{struct} 5786or @code{union} type. Alternatively, you can leave out the alignment factor 5787and just ask the compiler to align a type to the maximum 5788useful alignment for the target machine you are compiling for. For 5789example, you could write: 5790 5791@smallexample 5792struct S @{ short f[3]; @} __attribute__ ((aligned)); 5793@end smallexample 5794 5795Whenever you leave out the alignment factor in an @code{aligned} 5796attribute specification, the compiler automatically sets the alignment 5797for the type to the largest alignment that is ever used for any data 5798type on the target machine you are compiling for. Doing this can often 5799make copy operations more efficient, because the compiler can use 5800whatever instructions copy the biggest chunks of memory when performing 5801copies to or from the variables that have types that you have aligned 5802this way. 5803 5804In the example above, if the size of each @code{short} is 2 bytes, then 5805the size of the entire @code{struct S} type is 6 bytes. The smallest 5806power of two that is greater than or equal to that is 8, so the 5807compiler sets the alignment for the entire @code{struct S} type to 8 5808bytes. 5809 5810Note that although you can ask the compiler to select a time-efficient 5811alignment for a given type and then declare only individual stand-alone 5812objects of that type, the compiler's ability to select a time-efficient 5813alignment is primarily useful only when you plan to create arrays of 5814variables having the relevant (efficiently aligned) type. If you 5815declare or use arrays of variables of an efficiently-aligned type, then 5816it is likely that your program also does pointer arithmetic (or 5817subscripting, which amounts to the same thing) on pointers to the 5818relevant type, and the code that the compiler generates for these 5819pointer arithmetic operations is often more efficient for 5820efficiently-aligned types than for other types. 5821 5822The @code{aligned} attribute can only increase the alignment; but you 5823can decrease it by specifying @code{packed} as well. See below. 5824 5825Note that the effectiveness of @code{aligned} attributes may be limited 5826by inherent limitations in your linker. On many systems, the linker is 5827only able to arrange for variables to be aligned up to a certain maximum 5828alignment. (For some linkers, the maximum supported alignment may 5829be very very small.) If your linker is only able to align variables 5830up to a maximum of 8-byte alignment, then specifying @code{aligned(16)} 5831in an @code{__attribute__} still only provides you with 8-byte 5832alignment. See your linker documentation for further information. 5833 5834@item packed 5835@cindex @code{packed} type attribute 5836This attribute, attached to @code{struct} or @code{union} type 5837definition, specifies that each member (other than zero-width bit-fields) 5838of the structure or union is placed to minimize the memory required. When 5839attached to an @code{enum} definition, it indicates that the smallest 5840integral type should be used. 5841 5842@opindex fshort-enums 5843Specifying this attribute for @code{struct} and @code{union} types is 5844equivalent to specifying the @code{packed} attribute on each of the 5845structure or union members. Specifying the @option{-fshort-enums} 5846flag on the line is equivalent to specifying the @code{packed} 5847attribute on all @code{enum} definitions. 5848 5849In the following example @code{struct my_packed_struct}'s members are 5850packed closely together, but the internal layout of its @code{s} member 5851is not packed---to do that, @code{struct my_unpacked_struct} needs to 5852be packed too. 5853 5854@smallexample 5855struct my_unpacked_struct 5856 @{ 5857 char c; 5858 int i; 5859 @}; 5860 5861struct __attribute__ ((__packed__)) my_packed_struct 5862 @{ 5863 char c; 5864 int i; 5865 struct my_unpacked_struct s; 5866 @}; 5867@end smallexample 5868 5869You may only specify this attribute on the definition of an @code{enum}, 5870@code{struct} or @code{union}, not on a @code{typedef} that does not 5871also define the enumerated type, structure or union. 5872 5873@item transparent_union 5874@cindex @code{transparent_union} type attribute 5875 5876This attribute, attached to a @code{union} type definition, indicates 5877that any function parameter having that union type causes calls to that 5878function to be treated in a special way. 5879 5880First, the argument corresponding to a transparent union type can be of 5881any type in the union; no cast is required. Also, if the union contains 5882a pointer type, the corresponding argument can be a null pointer 5883constant or a void pointer expression; and if the union contains a void 5884pointer type, the corresponding argument can be any pointer expression. 5885If the union member type is a pointer, qualifiers like @code{const} on 5886the referenced type must be respected, just as with normal pointer 5887conversions. 5888 5889Second, the argument is passed to the function using the calling 5890conventions of the first member of the transparent union, not the calling 5891conventions of the union itself. All members of the union must have the 5892same machine representation; this is necessary for this argument passing 5893to work properly. 5894 5895Transparent unions are designed for library functions that have multiple 5896interfaces for compatibility reasons. For example, suppose the 5897@code{wait} function must accept either a value of type @code{int *} to 5898comply with POSIX, or a value of type @code{union wait *} to comply with 5899the 4.1BSD interface. If @code{wait}'s parameter were @code{void *}, 5900@code{wait} would accept both kinds of arguments, but it would also 5901accept any other pointer type and this would make argument type checking 5902less useful. Instead, @code{<sys/wait.h>} might define the interface 5903as follows: 5904 5905@smallexample 5906typedef union __attribute__ ((__transparent_union__)) 5907 @{ 5908 int *__ip; 5909 union wait *__up; 5910 @} wait_status_ptr_t; 5911 5912pid_t wait (wait_status_ptr_t); 5913@end smallexample 5914 5915@noindent 5916This interface allows either @code{int *} or @code{union wait *} 5917arguments to be passed, using the @code{int *} calling convention. 5918The program can call @code{wait} with arguments of either type: 5919 5920@smallexample 5921int w1 () @{ int w; return wait (&w); @} 5922int w2 () @{ union wait w; return wait (&w); @} 5923@end smallexample 5924 5925@noindent 5926With this interface, @code{wait}'s implementation might look like this: 5927 5928@smallexample 5929pid_t wait (wait_status_ptr_t p) 5930@{ 5931 return waitpid (-1, p.__ip, 0); 5932@} 5933@end smallexample 5934 5935@item unused 5936@cindex @code{unused} type attribute 5937When attached to a type (including a @code{union} or a @code{struct}), 5938this attribute means that variables of that type are meant to appear 5939possibly unused. GCC does not produce a warning for any variables of 5940that type, even if the variable appears to do nothing. This is often 5941the case with lock or thread classes, which are usually defined and then 5942not referenced, but contain constructors and destructors that have 5943nontrivial bookkeeping functions. 5944 5945@item deprecated 5946@itemx deprecated (@var{msg}) 5947@cindex @code{deprecated} type attribute 5948The @code{deprecated} attribute results in a warning if the type 5949is used anywhere in the source file. This is useful when identifying 5950types that are expected to be removed in a future version of a program. 5951If possible, the warning also includes the location of the declaration 5952of the deprecated type, to enable users to easily find further 5953information about why the type is deprecated, or what they should do 5954instead. Note that the warnings only occur for uses and then only 5955if the type is being applied to an identifier that itself is not being 5956declared as deprecated. 5957 5958@smallexample 5959typedef int T1 __attribute__ ((deprecated)); 5960T1 x; 5961typedef T1 T2; 5962T2 y; 5963typedef T1 T3 __attribute__ ((deprecated)); 5964T3 z __attribute__ ((deprecated)); 5965@end smallexample 5966 5967@noindent 5968results in a warning on line 2 and 3 but not lines 4, 5, or 6. No 5969warning is issued for line 4 because T2 is not explicitly 5970deprecated. Line 5 has no warning because T3 is explicitly 5971deprecated. Similarly for line 6. The optional @var{msg} 5972argument, which must be a string, is printed in the warning if 5973present. 5974 5975The @code{deprecated} attribute can also be used for functions and 5976variables (@pxref{Function Attributes}, @pxref{Variable Attributes}.) 5977 5978@item may_alias 5979@cindex @code{may_alias} type attribute 5980Accesses through pointers to types with this attribute are not subject 5981to type-based alias analysis, but are instead assumed to be able to alias 5982any other type of objects. 5983In the context of section 6.5 paragraph 7 of the C99 standard, 5984an lvalue expression 5985dereferencing such a pointer is treated like having a character type. 5986See @option{-fstrict-aliasing} for more information on aliasing issues. 5987This extension exists to support some vector APIs, in which pointers to 5988one vector type are permitted to alias pointers to a different vector type. 5989 5990Note that an object of a type with this attribute does not have any 5991special semantics. 5992 5993Example of use: 5994 5995@smallexample 5996typedef short __attribute__((__may_alias__)) short_a; 5997 5998int 5999main (void) 6000@{ 6001 int a = 0x12345678; 6002 short_a *b = (short_a *) &a; 6003 6004 b[1] = 0; 6005 6006 if (a == 0x12345678) 6007 abort(); 6008 6009 exit(0); 6010@} 6011@end smallexample 6012 6013@noindent 6014If you replaced @code{short_a} with @code{short} in the variable 6015declaration, the above program would abort when compiled with 6016@option{-fstrict-aliasing}, which is on by default at @option{-O2} or 6017above. 6018 6019@item visibility 6020@cindex @code{visibility} type attribute 6021In C++, attribute visibility (@pxref{Function Attributes}) can also be 6022applied to class, struct, union and enum types. Unlike other type 6023attributes, the attribute must appear between the initial keyword and 6024the name of the type; it cannot appear after the body of the type. 6025 6026Note that the type visibility is applied to vague linkage entities 6027associated with the class (vtable, typeinfo node, etc.). In 6028particular, if a class is thrown as an exception in one shared object 6029and caught in another, the class must have default visibility. 6030Otherwise the two shared objects are unable to use the same 6031typeinfo node and exception handling will break. 6032 6033@item designated_init 6034@cindex @code{designated_init} type attribute 6035This attribute may only be applied to structure types. It indicates 6036that any initialization of an object of this type must use designated 6037initializers rather than positional initializers. The intent of this 6038attribute is to allow the programmer to indicate that a structure's 6039layout may change, and that therefore relying on positional 6040initialization will result in future breakage. 6041 6042GCC emits warnings based on this attribute by default; use 6043@option{-Wno-designated-init} to suppress them. 6044 6045@item bnd_variable_size 6046@cindex @code{bnd_variable_size} type attribute 6047@cindex Pointer Bounds Checker attributes 6048When applied to a structure field, this attribute tells Pointer 6049Bounds Checker that the size of this field should not be computed 6050using static type information. It may be used to mark variably-sized 6051static array fields placed at the end of a structure. 6052 6053@smallexample 6054struct S 6055@{ 6056 int size; 6057 char data[1]; 6058@} 6059S *p = (S *)malloc (sizeof(S) + 100); 6060p->data[10] = 0; //Bounds violation 6061@end smallexample 6062 6063@noindent 6064By using an attribute for the field we may avoid unwanted bound 6065violation checks: 6066 6067@smallexample 6068struct S 6069@{ 6070 int size; 6071 char data[1] __attribute__((bnd_variable_size)); 6072@} 6073S *p = (S *)malloc (sizeof(S) + 100); 6074p->data[10] = 0; //OK 6075@end smallexample 6076 6077@end table 6078 6079To specify multiple attributes, separate them by commas within the 6080double parentheses: for example, @samp{__attribute__ ((aligned (16), 6081packed))}. 6082 6083@subsection ARM Type Attributes 6084 6085@cindex @code{notshared} type attribute, ARM 6086On those ARM targets that support @code{dllimport} (such as Symbian 6087OS), you can use the @code{notshared} attribute to indicate that the 6088virtual table and other similar data for a class should not be 6089exported from a DLL@. For example: 6090 6091@smallexample 6092class __declspec(notshared) C @{ 6093public: 6094 __declspec(dllimport) C(); 6095 virtual void f(); 6096@} 6097 6098__declspec(dllexport) 6099C::C() @{@} 6100@end smallexample 6101 6102@noindent 6103In this code, @code{C::C} is exported from the current DLL, but the 6104virtual table for @code{C} is not exported. (You can use 6105@code{__attribute__} instead of @code{__declspec} if you prefer, but 6106most Symbian OS code uses @code{__declspec}.) 6107 6108@anchor{MeP Type Attributes} 6109@subsection MeP Type Attributes 6110 6111@cindex @code{based} type attribute, MeP 6112@cindex @code{tiny} type attribute, MeP 6113@cindex @code{near} type attribute, MeP 6114@cindex @code{far} type attribute, MeP 6115Many of the MeP variable attributes may be applied to types as well. 6116Specifically, the @code{based}, @code{tiny}, @code{near}, and 6117@code{far} attributes may be applied to either. The @code{io} and 6118@code{cb} attributes may not be applied to types. 6119 6120@anchor{PowerPC Type Attributes} 6121@subsection PowerPC Type Attributes 6122 6123Three attributes currently are defined for PowerPC configurations: 6124@code{altivec}, @code{ms_struct} and @code{gcc_struct}. 6125 6126@cindex @code{ms_struct} type attribute, PowerPC 6127@cindex @code{gcc_struct} type attribute, PowerPC 6128For full documentation of the @code{ms_struct} and @code{gcc_struct} 6129attributes please see the documentation in @ref{x86 Type Attributes}. 6130 6131@cindex @code{altivec} type attribute, PowerPC 6132The @code{altivec} attribute allows one to declare AltiVec vector data 6133types supported by the AltiVec Programming Interface Manual. The 6134attribute requires an argument to specify one of three vector types: 6135@code{vector__}, @code{pixel__} (always followed by unsigned short), 6136and @code{bool__} (always followed by unsigned). 6137 6138@smallexample 6139__attribute__((altivec(vector__))) 6140__attribute__((altivec(pixel__))) unsigned short 6141__attribute__((altivec(bool__))) unsigned 6142@end smallexample 6143 6144These attributes mainly are intended to support the @code{__vector}, 6145@code{__pixel}, and @code{__bool} AltiVec keywords. 6146 6147@anchor{SPU Type Attributes} 6148@subsection SPU Type Attributes 6149 6150@cindex @code{spu_vector} type attribute, SPU 6151The SPU supports the @code{spu_vector} attribute for types. This attribute 6152allows one to declare vector data types supported by the Sony/Toshiba/IBM SPU 6153Language Extensions Specification. It is intended to support the 6154@code{__vector} keyword. 6155 6156@anchor{x86 Type Attributes} 6157@subsection x86 Type Attributes 6158 6159Two attributes are currently defined for x86 configurations: 6160@code{ms_struct} and @code{gcc_struct}. 6161 6162@table @code 6163 6164@item ms_struct 6165@itemx gcc_struct 6166@cindex @code{ms_struct} type attribute, x86 6167@cindex @code{gcc_struct} type attribute, x86 6168 6169If @code{packed} is used on a structure, or if bit-fields are used 6170it may be that the Microsoft ABI packs them differently 6171than GCC normally packs them. Particularly when moving packed 6172data between functions compiled with GCC and the native Microsoft compiler 6173(either via function call or as data in a file), it may be necessary to access 6174either format. 6175 6176Currently @option{-m[no-]ms-bitfields} is provided for the Microsoft Windows x86 6177compilers to match the native Microsoft compiler. 6178@end table 6179 6180@node Alignment 6181@section Inquiring on Alignment of Types or Variables 6182@cindex alignment 6183@cindex type alignment 6184@cindex variable alignment 6185 6186The keyword @code{__alignof__} allows you to inquire about how an object 6187is aligned, or the minimum alignment usually required by a type. Its 6188syntax is just like @code{sizeof}. 6189 6190For example, if the target machine requires a @code{double} value to be 6191aligned on an 8-byte boundary, then @code{__alignof__ (double)} is 8. 6192This is true on many RISC machines. On more traditional machine 6193designs, @code{__alignof__ (double)} is 4 or even 2. 6194 6195Some machines never actually require alignment; they allow reference to any 6196data type even at an odd address. For these machines, @code{__alignof__} 6197reports the smallest alignment that GCC gives the data type, usually as 6198mandated by the target ABI. 6199 6200If the operand of @code{__alignof__} is an lvalue rather than a type, 6201its value is the required alignment for its type, taking into account 6202any minimum alignment specified with GCC's @code{__attribute__} 6203extension (@pxref{Variable Attributes}). For example, after this 6204declaration: 6205 6206@smallexample 6207struct foo @{ int x; char y; @} foo1; 6208@end smallexample 6209 6210@noindent 6211the value of @code{__alignof__ (foo1.y)} is 1, even though its actual 6212alignment is probably 2 or 4, the same as @code{__alignof__ (int)}. 6213 6214It is an error to ask for the alignment of an incomplete type. 6215 6216 6217@node Inline 6218@section An Inline Function is As Fast As a Macro 6219@cindex inline functions 6220@cindex integrating function code 6221@cindex open coding 6222@cindex macros, inline alternative 6223 6224By declaring a function inline, you can direct GCC to make 6225calls to that function faster. One way GCC can achieve this is to 6226integrate that function's code into the code for its callers. This 6227makes execution faster by eliminating the function-call overhead; in 6228addition, if any of the actual argument values are constant, their 6229known values may permit simplifications at compile time so that not 6230all of the inline function's code needs to be included. The effect on 6231code size is less predictable; object code may be larger or smaller 6232with function inlining, depending on the particular case. You can 6233also direct GCC to try to integrate all ``simple enough'' functions 6234into their callers with the option @option{-finline-functions}. 6235 6236GCC implements three different semantics of declaring a function 6237inline. One is available with @option{-std=gnu89} or 6238@option{-fgnu89-inline} or when @code{gnu_inline} attribute is present 6239on all inline declarations, another when 6240@option{-std=c99}, @option{-std=c11}, 6241@option{-std=gnu99} or @option{-std=gnu11} 6242(without @option{-fgnu89-inline}), and the third 6243is used when compiling C++. 6244 6245To declare a function inline, use the @code{inline} keyword in its 6246declaration, like this: 6247 6248@smallexample 6249static inline int 6250inc (int *a) 6251@{ 6252 return (*a)++; 6253@} 6254@end smallexample 6255 6256If you are writing a header file to be included in ISO C90 programs, write 6257@code{__inline__} instead of @code{inline}. @xref{Alternate Keywords}. 6258 6259The three types of inlining behave similarly in two important cases: 6260when the @code{inline} keyword is used on a @code{static} function, 6261like the example above, and when a function is first declared without 6262using the @code{inline} keyword and then is defined with 6263@code{inline}, like this: 6264 6265@smallexample 6266extern int inc (int *a); 6267inline int 6268inc (int *a) 6269@{ 6270 return (*a)++; 6271@} 6272@end smallexample 6273 6274In both of these common cases, the program behaves the same as if you 6275had not used the @code{inline} keyword, except for its speed. 6276 6277@cindex inline functions, omission of 6278@opindex fkeep-inline-functions 6279When a function is both inline and @code{static}, if all calls to the 6280function are integrated into the caller, and the function's address is 6281never used, then the function's own assembler code is never referenced. 6282In this case, GCC does not actually output assembler code for the 6283function, unless you specify the option @option{-fkeep-inline-functions}. 6284Some calls cannot be integrated for various reasons (in particular, 6285calls that precede the function's definition cannot be integrated, and 6286neither can recursive calls within the definition). If there is a 6287nonintegrated call, then the function is compiled to assembler code as 6288usual. The function must also be compiled as usual if the program 6289refers to its address, because that can't be inlined. 6290 6291@opindex Winline 6292Note that certain usages in a function definition can make it unsuitable 6293for inline substitution. Among these usages are: variadic functions, use of 6294@code{alloca}, use of variable-length data types (@pxref{Variable Length}), 6295use of computed goto (@pxref{Labels as Values}), use of nonlocal goto, 6296and nested functions (@pxref{Nested Functions}). Using @option{-Winline} 6297warns when a function marked @code{inline} could not be substituted, 6298and gives the reason for the failure. 6299 6300@cindex automatic @code{inline} for C++ member fns 6301@cindex @code{inline} automatic for C++ member fns 6302@cindex member fns, automatically @code{inline} 6303@cindex C++ member fns, automatically @code{inline} 6304@opindex fno-default-inline 6305As required by ISO C++, GCC considers member functions defined within 6306the body of a class to be marked inline even if they are 6307not explicitly declared with the @code{inline} keyword. You can 6308override this with @option{-fno-default-inline}; @pxref{C++ Dialect 6309Options,,Options Controlling C++ Dialect}. 6310 6311GCC does not inline any functions when not optimizing unless you specify 6312the @samp{always_inline} attribute for the function, like this: 6313 6314@smallexample 6315/* @r{Prototype.} */ 6316inline void foo (const char) __attribute__((always_inline)); 6317@end smallexample 6318 6319The remainder of this section is specific to GNU C90 inlining. 6320 6321@cindex non-static inline function 6322When an inline function is not @code{static}, then the compiler must assume 6323that there may be calls from other source files; since a global symbol can 6324be defined only once in any program, the function must not be defined in 6325the other source files, so the calls therein cannot be integrated. 6326Therefore, a non-@code{static} inline function is always compiled on its 6327own in the usual fashion. 6328 6329If you specify both @code{inline} and @code{extern} in the function 6330definition, then the definition is used only for inlining. In no case 6331is the function compiled on its own, not even if you refer to its 6332address explicitly. Such an address becomes an external reference, as 6333if you had only declared the function, and had not defined it. 6334 6335This combination of @code{inline} and @code{extern} has almost the 6336effect of a macro. The way to use it is to put a function definition in 6337a header file with these keywords, and put another copy of the 6338definition (lacking @code{inline} and @code{extern}) in a library file. 6339The definition in the header file causes most calls to the function 6340to be inlined. If any uses of the function remain, they refer to 6341the single copy in the library. 6342 6343@node Volatiles 6344@section When is a Volatile Object Accessed? 6345@cindex accessing volatiles 6346@cindex volatile read 6347@cindex volatile write 6348@cindex volatile access 6349 6350C has the concept of volatile objects. These are normally accessed by 6351pointers and used for accessing hardware or inter-thread 6352communication. The standard encourages compilers to refrain from 6353optimizations concerning accesses to volatile objects, but leaves it 6354implementation defined as to what constitutes a volatile access. The 6355minimum requirement is that at a sequence point all previous accesses 6356to volatile objects have stabilized and no subsequent accesses have 6357occurred. Thus an implementation is free to reorder and combine 6358volatile accesses that occur between sequence points, but cannot do 6359so for accesses across a sequence point. The use of volatile does 6360not allow you to violate the restriction on updating objects multiple 6361times between two sequence points. 6362 6363Accesses to non-volatile objects are not ordered with respect to 6364volatile accesses. You cannot use a volatile object as a memory 6365barrier to order a sequence of writes to non-volatile memory. For 6366instance: 6367 6368@smallexample 6369int *ptr = @var{something}; 6370volatile int vobj; 6371*ptr = @var{something}; 6372vobj = 1; 6373@end smallexample 6374 6375@noindent 6376Unless @var{*ptr} and @var{vobj} can be aliased, it is not guaranteed 6377that the write to @var{*ptr} occurs by the time the update 6378of @var{vobj} happens. If you need this guarantee, you must use 6379a stronger memory barrier such as: 6380 6381@smallexample 6382int *ptr = @var{something}; 6383volatile int vobj; 6384*ptr = @var{something}; 6385asm volatile ("" : : : "memory"); 6386vobj = 1; 6387@end smallexample 6388 6389A scalar volatile object is read when it is accessed in a void context: 6390 6391@smallexample 6392volatile int *src = @var{somevalue}; 6393*src; 6394@end smallexample 6395 6396Such expressions are rvalues, and GCC implements this as a 6397read of the volatile object being pointed to. 6398 6399Assignments are also expressions and have an rvalue. However when 6400assigning to a scalar volatile, the volatile object is not reread, 6401regardless of whether the assignment expression's rvalue is used or 6402not. If the assignment's rvalue is used, the value is that assigned 6403to the volatile object. For instance, there is no read of @var{vobj} 6404in all the following cases: 6405 6406@smallexample 6407int obj; 6408volatile int vobj; 6409vobj = @var{something}; 6410obj = vobj = @var{something}; 6411obj ? vobj = @var{onething} : vobj = @var{anotherthing}; 6412obj = (@var{something}, vobj = @var{anotherthing}); 6413@end smallexample 6414 6415If you need to read the volatile object after an assignment has 6416occurred, you must use a separate expression with an intervening 6417sequence point. 6418 6419As bit-fields are not individually addressable, volatile bit-fields may 6420be implicitly read when written to, or when adjacent bit-fields are 6421accessed. Bit-field operations may be optimized such that adjacent 6422bit-fields are only partially accessed, if they straddle a storage unit 6423boundary. For these reasons it is unwise to use volatile bit-fields to 6424access hardware. 6425 6426@node Using Assembly Language with C 6427@section How to Use Inline Assembly Language in C Code 6428@cindex @code{asm} keyword 6429@cindex assembly language in C 6430@cindex inline assembly language 6431@cindex mixing assembly language and C 6432 6433The @code{asm} keyword allows you to embed assembler instructions 6434within C code. GCC provides two forms of inline @code{asm} 6435statements. A @dfn{basic @code{asm}} statement is one with no 6436operands (@pxref{Basic Asm}), while an @dfn{extended @code{asm}} 6437statement (@pxref{Extended Asm}) includes one or more operands. 6438The extended form is preferred for mixing C and assembly language 6439within a function, but to include assembly language at 6440top level you must use basic @code{asm}. 6441 6442You can also use the @code{asm} keyword to override the assembler name 6443for a C symbol, or to place a C variable in a specific register. 6444 6445@menu 6446* Basic Asm:: Inline assembler without operands. 6447* Extended Asm:: Inline assembler with operands. 6448* Constraints:: Constraints for @code{asm} operands 6449* Asm Labels:: Specifying the assembler name to use for a C symbol. 6450* Explicit Reg Vars:: Defining variables residing in specified registers. 6451* Size of an asm:: How GCC calculates the size of an @code{asm} block. 6452@end menu 6453 6454@node Basic Asm 6455@subsection Basic Asm --- Assembler Instructions Without Operands 6456@cindex basic @code{asm} 6457@cindex assembly language in C, basic 6458 6459A basic @code{asm} statement has the following syntax: 6460 6461@example 6462asm @r{[} volatile @r{]} ( @var{AssemblerInstructions} ) 6463@end example 6464 6465The @code{asm} keyword is a GNU extension. 6466When writing code that can be compiled with @option{-ansi} and the 6467various @option{-std} options, use @code{__asm__} instead of 6468@code{asm} (@pxref{Alternate Keywords}). 6469 6470@subsubheading Qualifiers 6471@table @code 6472@item volatile 6473The optional @code{volatile} qualifier has no effect. 6474All basic @code{asm} blocks are implicitly volatile. 6475@end table 6476 6477@subsubheading Parameters 6478@table @var 6479 6480@item AssemblerInstructions 6481This is a literal string that specifies the assembler code. The string can 6482contain any instructions recognized by the assembler, including directives. 6483GCC does not parse the assembler instructions themselves and 6484does not know what they mean or even whether they are valid assembler input. 6485 6486You may place multiple assembler instructions together in a single @code{asm} 6487string, separated by the characters normally used in assembly code for the 6488system. A combination that works in most places is a newline to break the 6489line, plus a tab character (written as @samp{\n\t}). 6490Some assemblers allow semicolons as a line separator. However, 6491note that some assembler dialects use semicolons to start a comment. 6492@end table 6493 6494@subsubheading Remarks 6495Using extended @code{asm} typically produces smaller, safer, and more 6496efficient code, and in most cases it is a better solution than basic 6497@code{asm}. However, there are two situations where only basic @code{asm} 6498can be used: 6499 6500@itemize @bullet 6501@item 6502Extended @code{asm} statements have to be inside a C 6503function, so to write inline assembly language at file scope (``top-level''), 6504outside of C functions, you must use basic @code{asm}. 6505You can use this technique to emit assembler directives, 6506define assembly language macros that can be invoked elsewhere in the file, 6507or write entire functions in assembly language. 6508 6509@item 6510Functions declared 6511with the @code{naked} attribute also require basic @code{asm} 6512(@pxref{Function Attributes}). 6513@end itemize 6514 6515Safely accessing C data and calling functions from basic @code{asm} is more 6516complex than it may appear. To access C data, it is better to use extended 6517@code{asm}. 6518 6519Do not expect a sequence of @code{asm} statements to remain perfectly 6520consecutive after compilation. If certain instructions need to remain 6521consecutive in the output, put them in a single multi-instruction @code{asm} 6522statement. Note that GCC's optimizers can move @code{asm} statements 6523relative to other code, including across jumps. 6524 6525@code{asm} statements may not perform jumps into other @code{asm} statements. 6526GCC does not know about these jumps, and therefore cannot take 6527account of them when deciding how to optimize. Jumps from @code{asm} to C 6528labels are only supported in extended @code{asm}. 6529 6530Under certain circumstances, GCC may duplicate (or remove duplicates of) your 6531assembly code when optimizing. This can lead to unexpected duplicate 6532symbol errors during compilation if your assembly code defines symbols or 6533labels. 6534 6535Since GCC does not parse the @var{AssemblerInstructions}, it has no 6536visibility of any symbols it references. This may result in GCC discarding 6537those symbols as unreferenced. 6538 6539The compiler copies the assembler instructions in a basic @code{asm} 6540verbatim to the assembly language output file, without 6541processing dialects or any of the @samp{%} operators that are available with 6542extended @code{asm}. This results in minor differences between basic 6543@code{asm} strings and extended @code{asm} templates. For example, to refer to 6544registers you might use @samp{%eax} in basic @code{asm} and 6545@samp{%%eax} in extended @code{asm}. 6546 6547On targets such as x86 that support multiple assembler dialects, 6548all basic @code{asm} blocks use the assembler dialect specified by the 6549@option{-masm} command-line option (@pxref{x86 Options}). 6550Basic @code{asm} provides no 6551mechanism to provide different assembler strings for different dialects. 6552 6553Here is an example of basic @code{asm} for i386: 6554 6555@example 6556/* Note that this code will not compile with -masm=intel */ 6557#define DebugBreak() asm("int $3") 6558@end example 6559 6560@node Extended Asm 6561@subsection Extended Asm - Assembler Instructions with C Expression Operands 6562@cindex extended @code{asm} 6563@cindex assembly language in C, extended 6564 6565With extended @code{asm} you can read and write C variables from 6566assembler and perform jumps from assembler code to C labels. 6567Extended @code{asm} syntax uses colons (@samp{:}) to delimit 6568the operand parameters after the assembler template: 6569 6570@example 6571asm @r{[}volatile@r{]} ( @var{AssemblerTemplate} 6572 : @var{OutputOperands} 6573 @r{[} : @var{InputOperands} 6574 @r{[} : @var{Clobbers} @r{]} @r{]}) 6575 6576asm @r{[}volatile@r{]} goto ( @var{AssemblerTemplate} 6577 : 6578 : @var{InputOperands} 6579 : @var{Clobbers} 6580 : @var{GotoLabels}) 6581@end example 6582 6583The @code{asm} keyword is a GNU extension. 6584When writing code that can be compiled with @option{-ansi} and the 6585various @option{-std} options, use @code{__asm__} instead of 6586@code{asm} (@pxref{Alternate Keywords}). 6587 6588@subsubheading Qualifiers 6589@table @code 6590 6591@item volatile 6592The typical use of extended @code{asm} statements is to manipulate input 6593values to produce output values. However, your @code{asm} statements may 6594also produce side effects. If so, you may need to use the @code{volatile} 6595qualifier to disable certain optimizations. @xref{Volatile}. 6596 6597@item goto 6598This qualifier informs the compiler that the @code{asm} statement may 6599perform a jump to one of the labels listed in the @var{GotoLabels}. 6600@xref{GotoLabels}. 6601@end table 6602 6603@subsubheading Parameters 6604@table @var 6605@item AssemblerTemplate 6606This is a literal string that is the template for the assembler code. It is a 6607combination of fixed text and tokens that refer to the input, output, 6608and goto parameters. @xref{AssemblerTemplate}. 6609 6610@item OutputOperands 6611A comma-separated list of the C variables modified by the instructions in the 6612@var{AssemblerTemplate}. An empty list is permitted. @xref{OutputOperands}. 6613 6614@item InputOperands 6615A comma-separated list of C expressions read by the instructions in the 6616@var{AssemblerTemplate}. An empty list is permitted. @xref{InputOperands}. 6617 6618@item Clobbers 6619A comma-separated list of registers or other values changed by the 6620@var{AssemblerTemplate}, beyond those listed as outputs. 6621An empty list is permitted. @xref{Clobbers}. 6622 6623@item GotoLabels 6624When you are using the @code{goto} form of @code{asm}, this section contains 6625the list of all C labels to which the code in the 6626@var{AssemblerTemplate} may jump. 6627@xref{GotoLabels}. 6628 6629@code{asm} statements may not perform jumps into other @code{asm} statements, 6630only to the listed @var{GotoLabels}. 6631GCC's optimizers do not know about other jumps; therefore they cannot take 6632account of them when deciding how to optimize. 6633@end table 6634 6635The total number of input + output + goto operands is limited to 30. 6636 6637@subsubheading Remarks 6638The @code{asm} statement allows you to include assembly instructions directly 6639within C code. This may help you to maximize performance in time-sensitive 6640code or to access assembly instructions that are not readily available to C 6641programs. 6642 6643Note that extended @code{asm} statements must be inside a function. Only 6644basic @code{asm} may be outside functions (@pxref{Basic Asm}). 6645Functions declared with the @code{naked} attribute also require basic 6646@code{asm} (@pxref{Function Attributes}). 6647 6648While the uses of @code{asm} are many and varied, it may help to think of an 6649@code{asm} statement as a series of low-level instructions that convert input 6650parameters to output parameters. So a simple (if not particularly useful) 6651example for i386 using @code{asm} might look like this: 6652 6653@example 6654int src = 1; 6655int dst; 6656 6657asm ("mov %1, %0\n\t" 6658 "add $1, %0" 6659 : "=r" (dst) 6660 : "r" (src)); 6661 6662printf("%d\n", dst); 6663@end example 6664 6665This code copies @code{src} to @code{dst} and add 1 to @code{dst}. 6666 6667@anchor{Volatile} 6668@subsubsection Volatile 6669@cindex volatile @code{asm} 6670@cindex @code{asm} volatile 6671 6672GCC's optimizers sometimes discard @code{asm} statements if they determine 6673there is no need for the output variables. Also, the optimizers may move 6674code out of loops if they believe that the code will always return the same 6675result (i.e. none of its input values change between calls). Using the 6676@code{volatile} qualifier disables these optimizations. @code{asm} statements 6677that have no output operands, including @code{asm goto} statements, 6678are implicitly volatile. 6679 6680This i386 code demonstrates a case that does not use (or require) the 6681@code{volatile} qualifier. If it is performing assertion checking, this code 6682uses @code{asm} to perform the validation. Otherwise, @code{dwRes} is 6683unreferenced by any code. As a result, the optimizers can discard the 6684@code{asm} statement, which in turn removes the need for the entire 6685@code{DoCheck} routine. By omitting the @code{volatile} qualifier when it 6686isn't needed you allow the optimizers to produce the most efficient code 6687possible. 6688 6689@example 6690void DoCheck(uint32_t dwSomeValue) 6691@{ 6692 uint32_t dwRes; 6693 6694 // Assumes dwSomeValue is not zero. 6695 asm ("bsfl %1,%0" 6696 : "=r" (dwRes) 6697 : "r" (dwSomeValue) 6698 : "cc"); 6699 6700 assert(dwRes > 3); 6701@} 6702@end example 6703 6704The next example shows a case where the optimizers can recognize that the input 6705(@code{dwSomeValue}) never changes during the execution of the function and can 6706therefore move the @code{asm} outside the loop to produce more efficient code. 6707Again, using @code{volatile} disables this type of optimization. 6708 6709@example 6710void do_print(uint32_t dwSomeValue) 6711@{ 6712 uint32_t dwRes; 6713 6714 for (uint32_t x=0; x < 5; x++) 6715 @{ 6716 // Assumes dwSomeValue is not zero. 6717 asm ("bsfl %1,%0" 6718 : "=r" (dwRes) 6719 : "r" (dwSomeValue) 6720 : "cc"); 6721 6722 printf("%u: %u %u\n", x, dwSomeValue, dwRes); 6723 @} 6724@} 6725@end example 6726 6727The following example demonstrates a case where you need to use the 6728@code{volatile} qualifier. 6729It uses the x86 @code{rdtsc} instruction, which reads 6730the computer's time-stamp counter. Without the @code{volatile} qualifier, 6731the optimizers might assume that the @code{asm} block will always return the 6732same value and therefore optimize away the second call. 6733 6734@example 6735uint64_t msr; 6736 6737asm volatile ( "rdtsc\n\t" // Returns the time in EDX:EAX. 6738 "shl $32, %%rdx\n\t" // Shift the upper bits left. 6739 "or %%rdx, %0" // 'Or' in the lower bits. 6740 : "=a" (msr) 6741 : 6742 : "rdx"); 6743 6744printf("msr: %llx\n", msr); 6745 6746// Do other work... 6747 6748// Reprint the timestamp 6749asm volatile ( "rdtsc\n\t" // Returns the time in EDX:EAX. 6750 "shl $32, %%rdx\n\t" // Shift the upper bits left. 6751 "or %%rdx, %0" // 'Or' in the lower bits. 6752 : "=a" (msr) 6753 : 6754 : "rdx"); 6755 6756printf("msr: %llx\n", msr); 6757@end example 6758 6759GCC's optimizers do not treat this code like the non-volatile code in the 6760earlier examples. They do not move it out of loops or omit it on the 6761assumption that the result from a previous call is still valid. 6762 6763Note that the compiler can move even volatile @code{asm} instructions relative 6764to other code, including across jump instructions. For example, on many 6765targets there is a system register that controls the rounding mode of 6766floating-point operations. Setting it with a volatile @code{asm}, as in the 6767following PowerPC example, does not work reliably. 6768 6769@example 6770asm volatile("mtfsf 255, %0" : : "f" (fpenv)); 6771sum = x + y; 6772@end example 6773 6774The compiler may move the addition back before the volatile @code{asm}. To 6775make it work as expected, add an artificial dependency to the @code{asm} by 6776referencing a variable in the subsequent code, for example: 6777 6778@example 6779asm volatile ("mtfsf 255,%1" : "=X" (sum) : "f" (fpenv)); 6780sum = x + y; 6781@end example 6782 6783Under certain circumstances, GCC may duplicate (or remove duplicates of) your 6784assembly code when optimizing. This can lead to unexpected duplicate symbol 6785errors during compilation if your asm code defines symbols or labels. 6786Using @samp{%=} 6787(@pxref{AssemblerTemplate}) may help resolve this problem. 6788 6789@anchor{AssemblerTemplate} 6790@subsubsection Assembler Template 6791@cindex @code{asm} assembler template 6792 6793An assembler template is a literal string containing assembler instructions. 6794The compiler replaces tokens in the template that refer 6795to inputs, outputs, and goto labels, 6796and then outputs the resulting string to the assembler. The 6797string can contain any instructions recognized by the assembler, including 6798directives. GCC does not parse the assembler instructions 6799themselves and does not know what they mean or even whether they are valid 6800assembler input. However, it does count the statements 6801(@pxref{Size of an asm}). 6802 6803You may place multiple assembler instructions together in a single @code{asm} 6804string, separated by the characters normally used in assembly code for the 6805system. A combination that works in most places is a newline to break the 6806line, plus a tab character to move to the instruction field (written as 6807@samp{\n\t}). 6808Some assemblers allow semicolons as a line separator. However, note 6809that some assembler dialects use semicolons to start a comment. 6810 6811Do not expect a sequence of @code{asm} statements to remain perfectly 6812consecutive after compilation, even when you are using the @code{volatile} 6813qualifier. If certain instructions need to remain consecutive in the output, 6814put them in a single multi-instruction asm statement. 6815 6816Accessing data from C programs without using input/output operands (such as 6817by using global symbols directly from the assembler template) may not work as 6818expected. Similarly, calling functions directly from an assembler template 6819requires a detailed understanding of the target assembler and ABI. 6820 6821Since GCC does not parse the assembler template, 6822it has no visibility of any 6823symbols it references. This may result in GCC discarding those symbols as 6824unreferenced unless they are also listed as input, output, or goto operands. 6825 6826@subsubheading Special format strings 6827 6828In addition to the tokens described by the input, output, and goto operands, 6829these tokens have special meanings in the assembler template: 6830 6831@table @samp 6832@item %% 6833Outputs a single @samp{%} into the assembler code. 6834 6835@item %= 6836Outputs a number that is unique to each instance of the @code{asm} 6837statement in the entire compilation. This option is useful when creating local 6838labels and referring to them multiple times in a single template that 6839generates multiple assembler instructions. 6840 6841@item %@{ 6842@itemx %| 6843@itemx %@} 6844Outputs @samp{@{}, @samp{|}, and @samp{@}} characters (respectively) 6845into the assembler code. When unescaped, these characters have special 6846meaning to indicate multiple assembler dialects, as described below. 6847@end table 6848 6849@subsubheading Multiple assembler dialects in @code{asm} templates 6850 6851On targets such as x86, GCC supports multiple assembler dialects. 6852The @option{-masm} option controls which dialect GCC uses as its 6853default for inline assembler. The target-specific documentation for the 6854@option{-masm} option contains the list of supported dialects, as well as the 6855default dialect if the option is not specified. This information may be 6856important to understand, since assembler code that works correctly when 6857compiled using one dialect will likely fail if compiled using another. 6858@xref{x86 Options}. 6859 6860If your code needs to support multiple assembler dialects (for example, if 6861you are writing public headers that need to support a variety of compilation 6862options), use constructs of this form: 6863 6864@example 6865@{ dialect0 | dialect1 | dialect2... @} 6866@end example 6867 6868This construct outputs @code{dialect0} 6869when using dialect #0 to compile the code, 6870@code{dialect1} for dialect #1, etc. If there are fewer alternatives within the 6871braces than the number of dialects the compiler supports, the construct 6872outputs nothing. 6873 6874For example, if an x86 compiler supports two dialects 6875(@samp{att}, @samp{intel}), an 6876assembler template such as this: 6877 6878@example 6879"bt@{l %[Offset],%[Base] | %[Base],%[Offset]@}; jc %l2" 6880@end example 6881 6882@noindent 6883is equivalent to one of 6884 6885@example 6886"btl %[Offset],%[Base] ; jc %l2" @r{/* att dialect */} 6887"bt %[Base],%[Offset]; jc %l2" @r{/* intel dialect */} 6888@end example 6889 6890Using that same compiler, this code: 6891 6892@example 6893"xchg@{l@}\t@{%%@}ebx, %1" 6894@end example 6895 6896@noindent 6897corresponds to either 6898 6899@example 6900"xchgl\t%%ebx, %1" @r{/* att dialect */} 6901"xchg\tebx, %1" @r{/* intel dialect */} 6902@end example 6903 6904There is no support for nesting dialect alternatives. 6905 6906@anchor{OutputOperands} 6907@subsubsection Output Operands 6908@cindex @code{asm} output operands 6909 6910An @code{asm} statement has zero or more output operands indicating the names 6911of C variables modified by the assembler code. 6912 6913In this i386 example, @code{old} (referred to in the template string as 6914@code{%0}) and @code{*Base} (as @code{%1}) are outputs and @code{Offset} 6915(@code{%2}) is an input: 6916 6917@example 6918bool old; 6919 6920__asm__ ("btsl %2,%1\n\t" // Turn on zero-based bit #Offset in Base. 6921 "sbb %0,%0" // Use the CF to calculate old. 6922 : "=r" (old), "+rm" (*Base) 6923 : "Ir" (Offset) 6924 : "cc"); 6925 6926return old; 6927@end example 6928 6929Operands are separated by commas. Each operand has this format: 6930 6931@example 6932@r{[} [@var{asmSymbolicName}] @r{]} @var{constraint} (@var{cvariablename}) 6933@end example 6934 6935@table @var 6936@item asmSymbolicName 6937Specifies a symbolic name for the operand. 6938Reference the name in the assembler template 6939by enclosing it in square brackets 6940(i.e. @samp{%[Value]}). The scope of the name is the @code{asm} statement 6941that contains the definition. Any valid C variable name is acceptable, 6942including names already defined in the surrounding code. No two operands 6943within the same @code{asm} statement can use the same symbolic name. 6944 6945When not using an @var{asmSymbolicName}, use the (zero-based) position 6946of the operand 6947in the list of operands in the assembler template. For example if there are 6948three output operands, use @samp{%0} in the template to refer to the first, 6949@samp{%1} for the second, and @samp{%2} for the third. 6950 6951@item constraint 6952A string constant specifying constraints on the placement of the operand; 6953@xref{Constraints}, for details. 6954 6955Output constraints must begin with either @samp{=} (a variable overwriting an 6956existing value) or @samp{+} (when reading and writing). When using 6957@samp{=}, do not assume the location contains the existing value 6958on entry to the @code{asm}, except 6959when the operand is tied to an input; @pxref{InputOperands,,Input Operands}. 6960 6961After the prefix, there must be one or more additional constraints 6962(@pxref{Constraints}) that describe where the value resides. Common 6963constraints include @samp{r} for register and @samp{m} for memory. 6964When you list more than one possible location (for example, @code{"=rm"}), 6965the compiler chooses the most efficient one based on the current context. 6966If you list as many alternates as the @code{asm} statement allows, you permit 6967the optimizers to produce the best possible code. 6968If you must use a specific register, but your Machine Constraints do not 6969provide sufficient control to select the specific register you want, 6970local register variables may provide a solution (@pxref{Local Reg Vars}). 6971 6972@item cvariablename 6973Specifies a C lvalue expression to hold the output, typically a variable name. 6974The enclosing parentheses are a required part of the syntax. 6975 6976@end table 6977 6978When the compiler selects the registers to use to 6979represent the output operands, it does not use any of the clobbered registers 6980(@pxref{Clobbers}). 6981 6982Output operand expressions must be lvalues. The compiler cannot check whether 6983the operands have data types that are reasonable for the instruction being 6984executed. For output expressions that are not directly addressable (for 6985example a bit-field), the constraint must allow a register. In that case, GCC 6986uses the register as the output of the @code{asm}, and then stores that 6987register into the output. 6988 6989Operands using the @samp{+} constraint modifier count as two operands 6990(that is, both as input and output) towards the total maximum of 30 operands 6991per @code{asm} statement. 6992 6993Use the @samp{&} constraint modifier (@pxref{Modifiers}) on all output 6994operands that must not overlap an input. Otherwise, 6995GCC may allocate the output operand in the same register as an unrelated 6996input operand, on the assumption that the assembler code consumes its 6997inputs before producing outputs. This assumption may be false if the assembler 6998code actually consists of more than one instruction. 6999 7000The same problem can occur if one output parameter (@var{a}) allows a register 7001constraint and another output parameter (@var{b}) allows a memory constraint. 7002The code generated by GCC to access the memory address in @var{b} can contain 7003registers which @emph{might} be shared by @var{a}, and GCC considers those 7004registers to be inputs to the asm. As above, GCC assumes that such input 7005registers are consumed before any outputs are written. This assumption may 7006result in incorrect behavior if the asm writes to @var{a} before using 7007@var{b}. Combining the @samp{&} modifier with the register constraint on @var{a} 7008ensures that modifying @var{a} does not affect the address referenced by 7009@var{b}. Otherwise, the location of @var{b} 7010is undefined if @var{a} is modified before using @var{b}. 7011 7012@code{asm} supports operand modifiers on operands (for example @samp{%k2} 7013instead of simply @samp{%2}). Typically these qualifiers are hardware 7014dependent. The list of supported modifiers for x86 is found at 7015@ref{x86Operandmodifiers,x86 Operand modifiers}. 7016 7017If the C code that follows the @code{asm} makes no use of any of the output 7018operands, use @code{volatile} for the @code{asm} statement to prevent the 7019optimizers from discarding the @code{asm} statement as unneeded 7020(see @ref{Volatile}). 7021 7022This code makes no use of the optional @var{asmSymbolicName}. Therefore it 7023references the first output operand as @code{%0} (were there a second, it 7024would be @code{%1}, etc). The number of the first input operand is one greater 7025than that of the last output operand. In this i386 example, that makes 7026@code{Mask} referenced as @code{%1}: 7027 7028@example 7029uint32_t Mask = 1234; 7030uint32_t Index; 7031 7032 asm ("bsfl %1, %0" 7033 : "=r" (Index) 7034 : "r" (Mask) 7035 : "cc"); 7036@end example 7037 7038That code overwrites the variable @code{Index} (@samp{=}), 7039placing the value in a register (@samp{r}). 7040Using the generic @samp{r} constraint instead of a constraint for a specific 7041register allows the compiler to pick the register to use, which can result 7042in more efficient code. This may not be possible if an assembler instruction 7043requires a specific register. 7044 7045The following i386 example uses the @var{asmSymbolicName} syntax. 7046It produces the 7047same result as the code above, but some may consider it more readable or more 7048maintainable since reordering index numbers is not necessary when adding or 7049removing operands. The names @code{aIndex} and @code{aMask} 7050are only used in this example to emphasize which 7051names get used where. 7052It is acceptable to reuse the names @code{Index} and @code{Mask}. 7053 7054@example 7055uint32_t Mask = 1234; 7056uint32_t Index; 7057 7058 asm ("bsfl %[aMask], %[aIndex]" 7059 : [aIndex] "=r" (Index) 7060 : [aMask] "r" (Mask) 7061 : "cc"); 7062@end example 7063 7064Here are some more examples of output operands. 7065 7066@example 7067uint32_t c = 1; 7068uint32_t d; 7069uint32_t *e = &c; 7070 7071asm ("mov %[e], %[d]" 7072 : [d] "=rm" (d) 7073 : [e] "rm" (*e)); 7074@end example 7075 7076Here, @code{d} may either be in a register or in memory. Since the compiler 7077might already have the current value of the @code{uint32_t} location 7078pointed to by @code{e} 7079in a register, you can enable it to choose the best location 7080for @code{d} by specifying both constraints. 7081 7082@anchor{InputOperands} 7083@subsubsection Input Operands 7084@cindex @code{asm} input operands 7085@cindex @code{asm} expressions 7086 7087Input operands make values from C variables and expressions available to the 7088assembly code. 7089 7090Operands are separated by commas. Each operand has this format: 7091 7092@example 7093@r{[} [@var{asmSymbolicName}] @r{]} @var{constraint} (@var{cexpression}) 7094@end example 7095 7096@table @var 7097@item asmSymbolicName 7098Specifies a symbolic name for the operand. 7099Reference the name in the assembler template 7100by enclosing it in square brackets 7101(i.e. @samp{%[Value]}). The scope of the name is the @code{asm} statement 7102that contains the definition. Any valid C variable name is acceptable, 7103including names already defined in the surrounding code. No two operands 7104within the same @code{asm} statement can use the same symbolic name. 7105 7106When not using an @var{asmSymbolicName}, use the (zero-based) position 7107of the operand 7108in the list of operands in the assembler template. For example if there are 7109two output operands and three inputs, 7110use @samp{%2} in the template to refer to the first input operand, 7111@samp{%3} for the second, and @samp{%4} for the third. 7112 7113@item constraint 7114A string constant specifying constraints on the placement of the operand; 7115@xref{Constraints}, for details. 7116 7117Input constraint strings may not begin with either @samp{=} or @samp{+}. 7118When you list more than one possible location (for example, @samp{"irm"}), 7119the compiler chooses the most efficient one based on the current context. 7120If you must use a specific register, but your Machine Constraints do not 7121provide sufficient control to select the specific register you want, 7122local register variables may provide a solution (@pxref{Local Reg Vars}). 7123 7124Input constraints can also be digits (for example, @code{"0"}). This indicates 7125that the specified input must be in the same place as the output constraint 7126at the (zero-based) index in the output constraint list. 7127When using @var{asmSymbolicName} syntax for the output operands, 7128you may use these names (enclosed in brackets @samp{[]}) instead of digits. 7129 7130@item cexpression 7131This is the C variable or expression being passed to the @code{asm} statement 7132as input. The enclosing parentheses are a required part of the syntax. 7133 7134@end table 7135 7136When the compiler selects the registers to use to represent the input 7137operands, it does not use any of the clobbered registers (@pxref{Clobbers}). 7138 7139If there are no output operands but there are input operands, place two 7140consecutive colons where the output operands would go: 7141 7142@example 7143__asm__ ("some instructions" 7144 : /* No outputs. */ 7145 : "r" (Offset / 8)); 7146@end example 7147 7148@strong{Warning:} Do @emph{not} modify the contents of input-only operands 7149(except for inputs tied to outputs). The compiler assumes that on exit from 7150the @code{asm} statement these operands contain the same values as they 7151had before executing the statement. 7152It is @emph{not} possible to use clobbers 7153to inform the compiler that the values in these inputs are changing. One 7154common work-around is to tie the changing input variable to an output variable 7155that never gets used. Note, however, that if the code that follows the 7156@code{asm} statement makes no use of any of the output operands, the GCC 7157optimizers may discard the @code{asm} statement as unneeded 7158(see @ref{Volatile}). 7159 7160@code{asm} supports operand modifiers on operands (for example @samp{%k2} 7161instead of simply @samp{%2}). Typically these qualifiers are hardware 7162dependent. The list of supported modifiers for x86 is found at 7163@ref{x86Operandmodifiers,x86 Operand modifiers}. 7164 7165In this example using the fictitious @code{combine} instruction, the 7166constraint @code{"0"} for input operand 1 says that it must occupy the same 7167location as output operand 0. Only input operands may use numbers in 7168constraints, and they must each refer to an output operand. Only a number (or 7169the symbolic assembler name) in the constraint can guarantee that one operand 7170is in the same place as another. The mere fact that @code{foo} is the value of 7171both operands is not enough to guarantee that they are in the same place in 7172the generated assembler code. 7173 7174@example 7175asm ("combine %2, %0" 7176 : "=r" (foo) 7177 : "0" (foo), "g" (bar)); 7178@end example 7179 7180Here is an example using symbolic names. 7181 7182@example 7183asm ("cmoveq %1, %2, %[result]" 7184 : [result] "=r"(result) 7185 : "r" (test), "r" (new), "[result]" (old)); 7186@end example 7187 7188@anchor{Clobbers} 7189@subsubsection Clobbers 7190@cindex @code{asm} clobbers 7191 7192While the compiler is aware of changes to entries listed in the output 7193operands, the inline @code{asm} code may modify more than just the outputs. For 7194example, calculations may require additional registers, or the processor may 7195overwrite a register as a side effect of a particular assembler instruction. 7196In order to inform the compiler of these changes, list them in the clobber 7197list. Clobber list items are either register names or the special clobbers 7198(listed below). Each clobber list item is a string constant 7199enclosed in double quotes and separated by commas. 7200 7201Clobber descriptions may not in any way overlap with an input or output 7202operand. For example, you may not have an operand describing a register class 7203with one member when listing that register in the clobber list. Variables 7204declared to live in specific registers (@pxref{Explicit Reg Vars}) and used 7205as @code{asm} input or output operands must have no part mentioned in the 7206clobber description. In particular, there is no way to specify that input 7207operands get modified without also specifying them as output operands. 7208 7209When the compiler selects which registers to use to represent input and output 7210operands, it does not use any of the clobbered registers. As a result, 7211clobbered registers are available for any use in the assembler code. 7212 7213Here is a realistic example for the VAX showing the use of clobbered 7214registers: 7215 7216@example 7217asm volatile ("movc3 %0, %1, %2" 7218 : /* No outputs. */ 7219 : "g" (from), "g" (to), "g" (count) 7220 : "r0", "r1", "r2", "r3", "r4", "r5"); 7221@end example 7222 7223Also, there are two special clobber arguments: 7224 7225@table @code 7226@item "cc" 7227The @code{"cc"} clobber indicates that the assembler code modifies the flags 7228register. On some machines, GCC represents the condition codes as a specific 7229hardware register; @code{"cc"} serves to name this register. 7230On other machines, condition code handling is different, 7231and specifying @code{"cc"} has no effect. But 7232it is valid no matter what the target. 7233 7234@item "memory" 7235The @code{"memory"} clobber tells the compiler that the assembly code 7236performs memory 7237reads or writes to items other than those listed in the input and output 7238operands (for example, accessing the memory pointed to by one of the input 7239parameters). To ensure memory contains correct values, GCC may need to flush 7240specific register values to memory before executing the @code{asm}. Further, 7241the compiler does not assume that any values read from memory before an 7242@code{asm} remain unchanged after that @code{asm}; it reloads them as 7243needed. 7244Using the @code{"memory"} clobber effectively forms a read/write 7245memory barrier for the compiler. 7246 7247Note that this clobber does not prevent the @emph{processor} from doing 7248speculative reads past the @code{asm} statement. To prevent that, you need 7249processor-specific fence instructions. 7250 7251Flushing registers to memory has performance implications and may be an issue 7252for time-sensitive code. You can use a trick to avoid this if the size of 7253the memory being accessed is known at compile time. For example, if accessing 7254ten bytes of a string, use a memory input like: 7255 7256@code{@{"m"( (@{ struct @{ char x[10]; @} *p = (void *)ptr ; *p; @}) )@}}. 7257 7258@end table 7259 7260@anchor{GotoLabels} 7261@subsubsection Goto Labels 7262@cindex @code{asm} goto labels 7263 7264@code{asm goto} allows assembly code to jump to one or more C labels. The 7265@var{GotoLabels} section in an @code{asm goto} statement contains 7266a comma-separated 7267list of all C labels to which the assembler code may jump. GCC assumes that 7268@code{asm} execution falls through to the next statement (if this is not the 7269case, consider using the @code{__builtin_unreachable} intrinsic after the 7270@code{asm} statement). Optimization of @code{asm goto} may be improved by 7271using the @code{hot} and @code{cold} label attributes (@pxref{Label 7272Attributes}). 7273 7274An @code{asm goto} statement cannot have outputs. 7275This is due to an internal restriction of 7276the compiler: control transfer instructions cannot have outputs. 7277If the assembler code does modify anything, use the @code{"memory"} clobber 7278to force the 7279optimizers to flush all register values to memory and reload them if 7280necessary after the @code{asm} statement. 7281 7282Also note that an @code{asm goto} statement is always implicitly 7283considered volatile. 7284 7285To reference a label in the assembler template, 7286prefix it with @samp{%l} (lowercase @samp{L}) followed 7287by its (zero-based) position in @var{GotoLabels} plus the number of input 7288operands. For example, if the @code{asm} has three inputs and references two 7289labels, refer to the first label as @samp{%l3} and the second as @samp{%l4}). 7290 7291Alternately, you can reference labels using the actual C label name enclosed 7292in brackets. For example, to reference a label named @code{carry}, you can 7293use @samp{%l[carry]}. The label must still be listed in the @var{GotoLabels} 7294section when using this approach. 7295 7296Here is an example of @code{asm goto} for i386: 7297 7298@example 7299asm goto ( 7300 "btl %1, %0\n\t" 7301 "jc %l2" 7302 : /* No outputs. */ 7303 : "r" (p1), "r" (p2) 7304 : "cc" 7305 : carry); 7306 7307return 0; 7308 7309carry: 7310return 1; 7311@end example 7312 7313The following example shows an @code{asm goto} that uses a memory clobber. 7314 7315@example 7316int frob(int x) 7317@{ 7318 int y; 7319 asm goto ("frob %%r5, %1; jc %l[error]; mov (%2), %%r5" 7320 : /* No outputs. */ 7321 : "r"(x), "r"(&y) 7322 : "r5", "memory" 7323 : error); 7324 return y; 7325error: 7326 return -1; 7327@} 7328@end example 7329 7330@anchor{x86Operandmodifiers} 7331@subsubsection x86 Operand Modifiers 7332 7333References to input, output, and goto operands in the assembler template 7334of extended @code{asm} statements can use 7335modifiers to affect the way the operands are formatted in 7336the code output to the assembler. For example, the 7337following code uses the @samp{h} and @samp{b} modifiers for x86: 7338 7339@example 7340uint16_t num; 7341asm volatile ("xchg %h0, %b0" : "+a" (num) ); 7342@end example 7343 7344@noindent 7345These modifiers generate this assembler code: 7346 7347@example 7348xchg %ah, %al 7349@end example 7350 7351The rest of this discussion uses the following code for illustrative purposes. 7352 7353@example 7354int main() 7355@{ 7356 int iInt = 1; 7357 7358top: 7359 7360 asm volatile goto ("some assembler instructions here" 7361 : /* No outputs. */ 7362 : "q" (iInt), "X" (sizeof(unsigned char) + 1) 7363 : /* No clobbers. */ 7364 : top); 7365@} 7366@end example 7367 7368With no modifiers, this is what the output from the operands would be for the 7369@samp{att} and @samp{intel} dialects of assembler: 7370 7371@multitable {Operand} {masm=att} {OFFSET FLAT:.L2} 7372@headitem Operand @tab masm=att @tab masm=intel 7373@item @code{%0} 7374@tab @code{%eax} 7375@tab @code{eax} 7376@item @code{%1} 7377@tab @code{$2} 7378@tab @code{2} 7379@item @code{%2} 7380@tab @code{$.L2} 7381@tab @code{OFFSET FLAT:.L2} 7382@end multitable 7383 7384The table below shows the list of supported modifiers and their effects. 7385 7386@multitable {Modifier} {Print the opcode suffix for the size of th} {Operand} {masm=att} {masm=intel} 7387@headitem Modifier @tab Description @tab Operand @tab @option{masm=att} @tab @option{masm=intel} 7388@item @code{z} 7389@tab Print the opcode suffix for the size of the current integer operand (one of @code{b}/@code{w}/@code{l}/@code{q}). 7390@tab @code{%z0} 7391@tab @code{l} 7392@tab 7393@item @code{b} 7394@tab Print the QImode name of the register. 7395@tab @code{%b0} 7396@tab @code{%al} 7397@tab @code{al} 7398@item @code{h} 7399@tab Print the QImode name for a ``high'' register. 7400@tab @code{%h0} 7401@tab @code{%ah} 7402@tab @code{ah} 7403@item @code{w} 7404@tab Print the HImode name of the register. 7405@tab @code{%w0} 7406@tab @code{%ax} 7407@tab @code{ax} 7408@item @code{k} 7409@tab Print the SImode name of the register. 7410@tab @code{%k0} 7411@tab @code{%eax} 7412@tab @code{eax} 7413@item @code{q} 7414@tab Print the DImode name of the register. 7415@tab @code{%q0} 7416@tab @code{%rax} 7417@tab @code{rax} 7418@item @code{l} 7419@tab Print the label name with no punctuation. 7420@tab @code{%l2} 7421@tab @code{.L2} 7422@tab @code{.L2} 7423@item @code{c} 7424@tab Require a constant operand and print the constant expression with no punctuation. 7425@tab @code{%c1} 7426@tab @code{2} 7427@tab @code{2} 7428@end multitable 7429 7430@anchor{x86floatingpointasmoperands} 7431@subsubsection x86 Floating-Point @code{asm} Operands 7432 7433On x86 targets, there are several rules on the usage of stack-like registers 7434in the operands of an @code{asm}. These rules apply only to the operands 7435that are stack-like registers: 7436 7437@enumerate 7438@item 7439Given a set of input registers that die in an @code{asm}, it is 7440necessary to know which are implicitly popped by the @code{asm}, and 7441which must be explicitly popped by GCC@. 7442 7443An input register that is implicitly popped by the @code{asm} must be 7444explicitly clobbered, unless it is constrained to match an 7445output operand. 7446 7447@item 7448For any input register that is implicitly popped by an @code{asm}, it is 7449necessary to know how to adjust the stack to compensate for the pop. 7450If any non-popped input is closer to the top of the reg-stack than 7451the implicitly popped register, it would not be possible to know what the 7452stack looked like---it's not clear how the rest of the stack ``slides 7453up''. 7454 7455All implicitly popped input registers must be closer to the top of 7456the reg-stack than any input that is not implicitly popped. 7457 7458It is possible that if an input dies in an @code{asm}, the compiler might 7459use the input register for an output reload. Consider this example: 7460 7461@smallexample 7462asm ("foo" : "=t" (a) : "f" (b)); 7463@end smallexample 7464 7465@noindent 7466This code says that input @code{b} is not popped by the @code{asm}, and that 7467the @code{asm} pushes a result onto the reg-stack, i.e., the stack is one 7468deeper after the @code{asm} than it was before. But, it is possible that 7469reload may think that it can use the same register for both the input and 7470the output. 7471 7472To prevent this from happening, 7473if any input operand uses the @samp{f} constraint, all output register 7474constraints must use the @samp{&} early-clobber modifier. 7475 7476The example above is correctly written as: 7477 7478@smallexample 7479asm ("foo" : "=&t" (a) : "f" (b)); 7480@end smallexample 7481 7482@item 7483Some operands need to be in particular places on the stack. All 7484output operands fall in this category---GCC has no other way to 7485know which registers the outputs appear in unless you indicate 7486this in the constraints. 7487 7488Output operands must specifically indicate which register an output 7489appears in after an @code{asm}. @samp{=f} is not allowed: the operand 7490constraints must select a class with a single register. 7491 7492@item 7493Output operands may not be ``inserted'' between existing stack registers. 7494Since no 387 opcode uses a read/write operand, all output operands 7495are dead before the @code{asm}, and are pushed by the @code{asm}. 7496It makes no sense to push anywhere but the top of the reg-stack. 7497 7498Output operands must start at the top of the reg-stack: output 7499operands may not ``skip'' a register. 7500 7501@item 7502Some @code{asm} statements may need extra stack space for internal 7503calculations. This can be guaranteed by clobbering stack registers 7504unrelated to the inputs and outputs. 7505 7506@end enumerate 7507 7508This @code{asm} 7509takes one input, which is internally popped, and produces two outputs. 7510 7511@smallexample 7512asm ("fsincos" : "=t" (cos), "=u" (sin) : "0" (inp)); 7513@end smallexample 7514 7515@noindent 7516This @code{asm} takes two inputs, which are popped by the @code{fyl2xp1} opcode, 7517and replaces them with one output. The @code{st(1)} clobber is necessary 7518for the compiler to know that @code{fyl2xp1} pops both inputs. 7519 7520@smallexample 7521asm ("fyl2xp1" : "=t" (result) : "0" (x), "u" (y) : "st(1)"); 7522@end smallexample 7523 7524@lowersections 7525@include md.texi 7526@raisesections 7527 7528@node Asm Labels 7529@subsection Controlling Names Used in Assembler Code 7530@cindex assembler names for identifiers 7531@cindex names used in assembler code 7532@cindex identifiers, names in assembler code 7533 7534You can specify the name to be used in the assembler code for a C 7535function or variable by writing the @code{asm} (or @code{__asm__}) 7536keyword after the declarator as follows: 7537 7538@smallexample 7539int foo asm ("myfoo") = 2; 7540@end smallexample 7541 7542@noindent 7543This specifies that the name to be used for the variable @code{foo} in 7544the assembler code should be @samp{myfoo} rather than the usual 7545@samp{_foo}. 7546 7547On systems where an underscore is normally prepended to the name of a C 7548function or variable, this feature allows you to define names for the 7549linker that do not start with an underscore. 7550 7551It does not make sense to use this feature with a non-static local 7552variable since such variables do not have assembler names. If you are 7553trying to put the variable in a particular register, see @ref{Explicit 7554Reg Vars}. GCC presently accepts such code with a warning, but will 7555probably be changed to issue an error, rather than a warning, in the 7556future. 7557 7558You cannot use @code{asm} in this way in a function @emph{definition}; but 7559you can get the same effect by writing a declaration for the function 7560before its definition and putting @code{asm} there, like this: 7561 7562@smallexample 7563extern func () asm ("FUNC"); 7564 7565func (x, y) 7566 int x, y; 7567/* @r{@dots{}} */ 7568@end smallexample 7569 7570It is up to you to make sure that the assembler names you choose do not 7571conflict with any other assembler symbols. Also, you must not use a 7572register name; that would produce completely invalid assembler code. GCC 7573does not as yet have the ability to store static variables in registers. 7574Perhaps that will be added. 7575 7576@node Explicit Reg Vars 7577@subsection Variables in Specified Registers 7578@cindex explicit register variables 7579@cindex variables in specified registers 7580@cindex specified registers 7581@cindex registers, global allocation 7582 7583GNU C allows you to put a few global variables into specified hardware 7584registers. You can also specify the register in which an ordinary 7585register variable should be allocated. 7586 7587@itemize @bullet 7588@item 7589Global register variables reserve registers throughout the program. 7590This may be useful in programs such as programming language 7591interpreters that have a couple of global variables that are accessed 7592very often. 7593 7594@item 7595Local register variables in specific registers do not reserve the 7596registers, except at the point where they are used as input or output 7597operands in an @code{asm} statement and the @code{asm} statement itself is 7598not deleted. The compiler's data flow analysis is capable of determining 7599where the specified registers contain live values, and where they are 7600available for other uses. Stores into local register variables may be deleted 7601when they appear to be dead according to dataflow analysis. References 7602to local register variables may be deleted or moved or simplified. 7603 7604These local variables are sometimes convenient for use with the extended 7605@code{asm} feature (@pxref{Extended Asm}), if you want to write one 7606output of the assembler instruction directly into a particular register. 7607(This works provided the register you specify fits the constraints 7608specified for that operand in the @code{asm}.) 7609@end itemize 7610 7611@menu 7612* Global Reg Vars:: 7613* Local Reg Vars:: 7614@end menu 7615 7616@node Global Reg Vars 7617@subsubsection Defining Global Register Variables 7618@cindex global register variables 7619@cindex registers, global variables in 7620 7621You can define a global register variable in GNU C like this: 7622 7623@smallexample 7624register int *foo asm ("a5"); 7625@end smallexample 7626 7627@noindent 7628Here @code{a5} is the name of the register that should be used. Choose a 7629register that is normally saved and restored by function calls on your 7630machine, so that library routines will not clobber it. 7631 7632Naturally the register name is CPU-dependent, so you need to 7633conditionalize your program according to CPU type. The register 7634@code{a5} is a good choice on a 68000 for a variable of pointer 7635type. On machines with register windows, be sure to choose a ``global'' 7636register that is not affected magically by the function call mechanism. 7637 7638In addition, different operating systems on the same CPU may differ in how they 7639name the registers; then you need additional conditionals. For 7640example, some 68000 operating systems call this register @code{%a5}. 7641 7642Eventually there may be a way of asking the compiler to choose a register 7643automatically, but first we need to figure out how it should choose and 7644how to enable you to guide the choice. No solution is evident. 7645 7646Defining a global register variable in a certain register reserves that 7647register entirely for this use, at least within the current compilation. 7648The register is not allocated for any other purpose in the functions 7649in the current compilation, and is not saved and restored by 7650these functions. Stores into this register are never deleted even if they 7651appear to be dead, but references may be deleted or moved or 7652simplified. 7653 7654It is not safe to access the global register variables from signal 7655handlers, or from more than one thread of control, because the system 7656library routines may temporarily use the register for other things (unless 7657you recompile them specially for the task at hand). 7658 7659@cindex @code{qsort}, and global register variables 7660It is not safe for one function that uses a global register variable to 7661call another such function @code{foo} by way of a third function 7662@code{lose} that is compiled without knowledge of this variable (i.e.@: in a 7663different source file in which the variable isn't declared). This is 7664because @code{lose} might save the register and put some other value there. 7665For example, you can't expect a global register variable to be available in 7666the comparison-function that you pass to @code{qsort}, since @code{qsort} 7667might have put something else in that register. (If you are prepared to 7668recompile @code{qsort} with the same global register variable, you can 7669solve this problem.) 7670 7671If you want to recompile @code{qsort} or other source files that do not 7672actually use your global register variable, so that they do not use that 7673register for any other purpose, then it suffices to specify the compiler 7674option @option{-ffixed-@var{reg}}. You need not actually add a global 7675register declaration to their source code. 7676 7677A function that can alter the value of a global register variable cannot 7678safely be called from a function compiled without this variable, because it 7679could clobber the value the caller expects to find there on return. 7680Therefore, the function that is the entry point into the part of the 7681program that uses the global register variable must explicitly save and 7682restore the value that belongs to its caller. 7683 7684@cindex register variable after @code{longjmp} 7685@cindex global register after @code{longjmp} 7686@cindex value after @code{longjmp} 7687@findex longjmp 7688@findex setjmp 7689On most machines, @code{longjmp} restores to each global register 7690variable the value it had at the time of the @code{setjmp}. On some 7691machines, however, @code{longjmp} does not change the value of global 7692register variables. To be portable, the function that called @code{setjmp} 7693should make other arrangements to save the values of the global register 7694variables, and to restore them in a @code{longjmp}. This way, the same 7695thing happens regardless of what @code{longjmp} does. 7696 7697All global register variable declarations must precede all function 7698definitions. If such a declaration could appear after function 7699definitions, the declaration would be too late to prevent the register from 7700being used for other purposes in the preceding functions. 7701 7702Global register variables may not have initial values, because an 7703executable file has no means to supply initial contents for a register. 7704 7705On the SPARC, there are reports that g3 @dots{} g7 are suitable 7706registers, but certain library functions, such as @code{getwd}, as well 7707as the subroutines for division and remainder, modify g3 and g4. g1 and 7708g2 are local temporaries. 7709 7710On the 68000, a2 @dots{} a5 should be suitable, as should d2 @dots{} d7. 7711Of course, it does not do to use more than a few of those. 7712 7713@node Local Reg Vars 7714@subsubsection Specifying Registers for Local Variables 7715@cindex local variables, specifying registers 7716@cindex specifying registers for local variables 7717@cindex registers for local variables 7718 7719You can define a local register variable with a specified register 7720like this: 7721 7722@smallexample 7723register int *foo asm ("a5"); 7724@end smallexample 7725 7726@noindent 7727Here @code{a5} is the name of the register that should be used. Note 7728that this is the same syntax used for defining global register 7729variables, but for a local variable it appears within a function. 7730 7731Naturally the register name is CPU-dependent, but this is not a 7732problem, since specific registers are most often useful with explicit 7733assembler instructions (@pxref{Extended Asm}). Both of these things 7734generally require that you conditionalize your program according to 7735CPU type. 7736 7737In addition, operating systems on one type of CPU may differ in how they 7738name the registers; then you need additional conditionals. For 7739example, some 68000 operating systems call this register @code{%a5}. 7740 7741Defining such a register variable does not reserve the register; it 7742remains available for other uses in places where flow control determines 7743the variable's value is not live. 7744 7745This option does not guarantee that GCC generates code that has 7746this variable in the register you specify at all times. You may not 7747code an explicit reference to this register in the assembler 7748instruction template part of an @code{asm} statement and assume it 7749always refers to this variable. 7750However, using the variable as an input or output operand to the @code{asm} 7751guarantees that the specified register is used for that operand. 7752@xref{Extended Asm}, for more information. 7753 7754Stores into local register variables may be deleted when they appear to be dead 7755according to dataflow analysis. References to local register variables may 7756be deleted or moved or simplified. 7757 7758As with global register variables, it is recommended that you choose a 7759register that is normally saved and restored by function calls on 7760your machine, so that library routines will not clobber it. 7761 7762Sometimes when writing inline @code{asm} code, you need to make an operand be a 7763specific register, but there's no matching constraint letter for that 7764register. To force the operand into that register, create a local variable 7765and specify the register in the variable's declaration. Then use the local 7766variable for the asm operand and specify any constraint letter that matches 7767the register: 7768 7769@smallexample 7770register int *p1 asm ("r0") = @dots{}; 7771register int *p2 asm ("r1") = @dots{}; 7772register int *result asm ("r0"); 7773asm ("sysint" : "=r" (result) : "0" (p1), "r" (p2)); 7774@end smallexample 7775 7776@emph{Warning:} In the above example, be aware that a register (for example r0) can be 7777call-clobbered by subsequent code, including function calls and library calls 7778for arithmetic operators on other variables (for example the initialization 7779of p2). In this case, use temporary variables for expressions between the 7780register assignments: 7781 7782@smallexample 7783int t1 = @dots{}; 7784register int *p1 asm ("r0") = @dots{}; 7785register int *p2 asm ("r1") = t1; 7786register int *result asm ("r0"); 7787asm ("sysint" : "=r" (result) : "0" (p1), "r" (p2)); 7788@end smallexample 7789 7790@node Size of an asm 7791@subsection Size of an @code{asm} 7792 7793Some targets require that GCC track the size of each instruction used 7794in order to generate correct code. Because the final length of the 7795code produced by an @code{asm} statement is only known by the 7796assembler, GCC must make an estimate as to how big it will be. It 7797does this by counting the number of instructions in the pattern of the 7798@code{asm} and multiplying that by the length of the longest 7799instruction supported by that processor. (When working out the number 7800of instructions, it assumes that any occurrence of a newline or of 7801whatever statement separator character is supported by the assembler -- 7802typically @samp{;} --- indicates the end of an instruction.) 7803 7804Normally, GCC's estimate is adequate to ensure that correct 7805code is generated, but it is possible to confuse the compiler if you use 7806pseudo instructions or assembler macros that expand into multiple real 7807instructions, or if you use assembler directives that expand to more 7808space in the object file than is needed for a single instruction. 7809If this happens then the assembler may produce a diagnostic saying that 7810a label is unreachable. 7811 7812@node Alternate Keywords 7813@section Alternate Keywords 7814@cindex alternate keywords 7815@cindex keywords, alternate 7816 7817@option{-ansi} and the various @option{-std} options disable certain 7818keywords. This causes trouble when you want to use GNU C extensions, or 7819a general-purpose header file that should be usable by all programs, 7820including ISO C programs. The keywords @code{asm}, @code{typeof} and 7821@code{inline} are not available in programs compiled with 7822@option{-ansi} or @option{-std} (although @code{inline} can be used in a 7823program compiled with @option{-std=c99} or @option{-std=c11}). The 7824ISO C99 keyword 7825@code{restrict} is only available when @option{-std=gnu99} (which will 7826eventually be the default) or @option{-std=c99} (or the equivalent 7827@option{-std=iso9899:1999}), or an option for a later standard 7828version, is used. 7829 7830The way to solve these problems is to put @samp{__} at the beginning and 7831end of each problematical keyword. For example, use @code{__asm__} 7832instead of @code{asm}, and @code{__inline__} instead of @code{inline}. 7833 7834Other C compilers won't accept these alternative keywords; if you want to 7835compile with another compiler, you can define the alternate keywords as 7836macros to replace them with the customary keywords. It looks like this: 7837 7838@smallexample 7839#ifndef __GNUC__ 7840#define __asm__ asm 7841#endif 7842@end smallexample 7843 7844@findex __extension__ 7845@opindex pedantic 7846@option{-pedantic} and other options cause warnings for many GNU C extensions. 7847You can 7848prevent such warnings within one expression by writing 7849@code{__extension__} before the expression. @code{__extension__} has no 7850effect aside from this. 7851 7852@node Incomplete Enums 7853@section Incomplete @code{enum} Types 7854 7855You can define an @code{enum} tag without specifying its possible values. 7856This results in an incomplete type, much like what you get if you write 7857@code{struct foo} without describing the elements. A later declaration 7858that does specify the possible values completes the type. 7859 7860You can't allocate variables or storage using the type while it is 7861incomplete. However, you can work with pointers to that type. 7862 7863This extension may not be very useful, but it makes the handling of 7864@code{enum} more consistent with the way @code{struct} and @code{union} 7865are handled. 7866 7867This extension is not supported by GNU C++. 7868 7869@node Function Names 7870@section Function Names as Strings 7871@cindex @code{__func__} identifier 7872@cindex @code{__FUNCTION__} identifier 7873@cindex @code{__PRETTY_FUNCTION__} identifier 7874 7875GCC provides three magic variables that hold the name of the current 7876function, as a string. The first of these is @code{__func__}, which 7877is part of the C99 standard: 7878 7879The identifier @code{__func__} is implicitly declared by the translator 7880as if, immediately following the opening brace of each function 7881definition, the declaration 7882 7883@smallexample 7884static const char __func__[] = "function-name"; 7885@end smallexample 7886 7887@noindent 7888appeared, where function-name is the name of the lexically-enclosing 7889function. This name is the unadorned name of the function. 7890 7891@code{__FUNCTION__} is another name for @code{__func__}, provided for 7892backward compatibility with old versions of GCC. 7893 7894In C, @code{__PRETTY_FUNCTION__} is yet another name for 7895@code{__func__}. However, in C++, @code{__PRETTY_FUNCTION__} contains 7896the type signature of the function as well as its bare name. For 7897example, this program: 7898 7899@smallexample 7900extern "C" @{ 7901extern int printf (char *, ...); 7902@} 7903 7904class a @{ 7905 public: 7906 void sub (int i) 7907 @{ 7908 printf ("__FUNCTION__ = %s\n", __FUNCTION__); 7909 printf ("__PRETTY_FUNCTION__ = %s\n", __PRETTY_FUNCTION__); 7910 @} 7911@}; 7912 7913int 7914main (void) 7915@{ 7916 a ax; 7917 ax.sub (0); 7918 return 0; 7919@} 7920@end smallexample 7921 7922@noindent 7923gives this output: 7924 7925@smallexample 7926__FUNCTION__ = sub 7927__PRETTY_FUNCTION__ = void a::sub(int) 7928@end smallexample 7929 7930These identifiers are variables, not preprocessor macros, and may not 7931be used to initialize @code{char} arrays or be concatenated with other string 7932literals. 7933 7934@node Return Address 7935@section Getting the Return or Frame Address of a Function 7936 7937These functions may be used to get information about the callers of a 7938function. 7939 7940@deftypefn {Built-in Function} {void *} __builtin_return_address (unsigned int @var{level}) 7941This function returns the return address of the current function, or of 7942one of its callers. The @var{level} argument is number of frames to 7943scan up the call stack. A value of @code{0} yields the return address 7944of the current function, a value of @code{1} yields the return address 7945of the caller of the current function, and so forth. When inlining 7946the expected behavior is that the function returns the address of 7947the function that is returned to. To work around this behavior use 7948the @code{noinline} function attribute. 7949 7950The @var{level} argument must be a constant integer. 7951 7952On some machines it may be impossible to determine the return address of 7953any function other than the current one; in such cases, or when the top 7954of the stack has been reached, this function returns @code{0} or a 7955random value. In addition, @code{__builtin_frame_address} may be used 7956to determine if the top of the stack has been reached. 7957 7958Additional post-processing of the returned value may be needed, see 7959@code{__builtin_extract_return_addr}. 7960 7961This function should only be used with a nonzero argument for debugging 7962purposes. 7963@end deftypefn 7964 7965@deftypefn {Built-in Function} {void *} __builtin_extract_return_addr (void *@var{addr}) 7966The address as returned by @code{__builtin_return_address} may have to be fed 7967through this function to get the actual encoded address. For example, on the 796831-bit S/390 platform the highest bit has to be masked out, or on SPARC 7969platforms an offset has to be added for the true next instruction to be 7970executed. 7971 7972If no fixup is needed, this function simply passes through @var{addr}. 7973@end deftypefn 7974 7975@deftypefn {Built-in Function} {void *} __builtin_frob_return_address (void *@var{addr}) 7976This function does the reverse of @code{__builtin_extract_return_addr}. 7977@end deftypefn 7978 7979@deftypefn {Built-in Function} {void *} __builtin_frame_address (unsigned int @var{level}) 7980This function is similar to @code{__builtin_return_address}, but it 7981returns the address of the function frame rather than the return address 7982of the function. Calling @code{__builtin_frame_address} with a value of 7983@code{0} yields the frame address of the current function, a value of 7984@code{1} yields the frame address of the caller of the current function, 7985and so forth. 7986 7987The frame is the area on the stack that holds local variables and saved 7988registers. The frame address is normally the address of the first word 7989pushed on to the stack by the function. However, the exact definition 7990depends upon the processor and the calling convention. If the processor 7991has a dedicated frame pointer register, and the function has a frame, 7992then @code{__builtin_frame_address} returns the value of the frame 7993pointer register. 7994 7995On some machines it may be impossible to determine the frame address of 7996any function other than the current one; in such cases, or when the top 7997of the stack has been reached, this function returns @code{0} if 7998the first frame pointer is properly initialized by the startup code. 7999 8000This function should only be used with a nonzero argument for debugging 8001purposes. 8002@end deftypefn 8003 8004@node Vector Extensions 8005@section Using Vector Instructions through Built-in Functions 8006 8007On some targets, the instruction set contains SIMD vector instructions which 8008operate on multiple values contained in one large register at the same time. 8009For example, on the x86 the MMX, 3DNow!@: and SSE extensions can be used 8010this way. 8011 8012The first step in using these extensions is to provide the necessary data 8013types. This should be done using an appropriate @code{typedef}: 8014 8015@smallexample 8016typedef int v4si __attribute__ ((vector_size (16))); 8017@end smallexample 8018 8019@noindent 8020The @code{int} type specifies the base type, while the attribute specifies 8021the vector size for the variable, measured in bytes. For example, the 8022declaration above causes the compiler to set the mode for the @code{v4si} 8023type to be 16 bytes wide and divided into @code{int} sized units. For 8024a 32-bit @code{int} this means a vector of 4 units of 4 bytes, and the 8025corresponding mode of @code{foo} is @acronym{V4SI}. 8026 8027The @code{vector_size} attribute is only applicable to integral and 8028float scalars, although arrays, pointers, and function return values 8029are allowed in conjunction with this construct. Only sizes that are 8030a power of two are currently allowed. 8031 8032All the basic integer types can be used as base types, both as signed 8033and as unsigned: @code{char}, @code{short}, @code{int}, @code{long}, 8034@code{long long}. In addition, @code{float} and @code{double} can be 8035used to build floating-point vector types. 8036 8037Specifying a combination that is not valid for the current architecture 8038causes GCC to synthesize the instructions using a narrower mode. 8039For example, if you specify a variable of type @code{V4SI} and your 8040architecture does not allow for this specific SIMD type, GCC 8041produces code that uses 4 @code{SIs}. 8042 8043The types defined in this manner can be used with a subset of normal C 8044operations. Currently, GCC allows using the following operators 8045on these types: @code{+, -, *, /, unary minus, ^, |, &, ~, %}@. 8046 8047The operations behave like C++ @code{valarrays}. Addition is defined as 8048the addition of the corresponding elements of the operands. For 8049example, in the code below, each of the 4 elements in @var{a} is 8050added to the corresponding 4 elements in @var{b} and the resulting 8051vector is stored in @var{c}. 8052 8053@smallexample 8054typedef int v4si __attribute__ ((vector_size (16))); 8055 8056v4si a, b, c; 8057 8058c = a + b; 8059@end smallexample 8060 8061Subtraction, multiplication, division, and the logical operations 8062operate in a similar manner. Likewise, the result of using the unary 8063minus or complement operators on a vector type is a vector whose 8064elements are the negative or complemented values of the corresponding 8065elements in the operand. 8066 8067It is possible to use shifting operators @code{<<}, @code{>>} on 8068integer-type vectors. The operation is defined as following: @code{@{a0, 8069a1, @dots{}, an@} >> @{b0, b1, @dots{}, bn@} == @{a0 >> b0, a1 >> b1, 8070@dots{}, an >> bn@}}@. Vector operands must have the same number of 8071elements. 8072 8073For convenience, it is allowed to use a binary vector operation 8074where one operand is a scalar. In that case the compiler transforms 8075the scalar operand into a vector where each element is the scalar from 8076the operation. The transformation happens only if the scalar could be 8077safely converted to the vector-element type. 8078Consider the following code. 8079 8080@smallexample 8081typedef int v4si __attribute__ ((vector_size (16))); 8082 8083v4si a, b, c; 8084long l; 8085 8086a = b + 1; /* a = b + @{1,1,1,1@}; */ 8087a = 2 * b; /* a = @{2,2,2,2@} * b; */ 8088 8089a = l + a; /* Error, cannot convert long to int. */ 8090@end smallexample 8091 8092Vectors can be subscripted as if the vector were an array with 8093the same number of elements and base type. Out of bound accesses 8094invoke undefined behavior at run time. Warnings for out of bound 8095accesses for vector subscription can be enabled with 8096@option{-Warray-bounds}. 8097 8098Vector comparison is supported with standard comparison 8099operators: @code{==, !=, <, <=, >, >=}. Comparison operands can be 8100vector expressions of integer-type or real-type. Comparison between 8101integer-type vectors and real-type vectors are not supported. The 8102result of the comparison is a vector of the same width and number of 8103elements as the comparison operands with a signed integral element 8104type. 8105 8106Vectors are compared element-wise producing 0 when comparison is false 8107and -1 (constant of the appropriate type where all bits are set) 8108otherwise. Consider the following example. 8109 8110@smallexample 8111typedef int v4si __attribute__ ((vector_size (16))); 8112 8113v4si a = @{1,2,3,4@}; 8114v4si b = @{3,2,1,4@}; 8115v4si c; 8116 8117c = a > b; /* The result would be @{0, 0,-1, 0@} */ 8118c = a == b; /* The result would be @{0,-1, 0,-1@} */ 8119@end smallexample 8120 8121In C++, the ternary operator @code{?:} is available. @code{a?b:c}, where 8122@code{b} and @code{c} are vectors of the same type and @code{a} is an 8123integer vector with the same number of elements of the same size as @code{b} 8124and @code{c}, computes all three arguments and creates a vector 8125@code{@{a[0]?b[0]:c[0], a[1]?b[1]:c[1], @dots{}@}}. Note that unlike in 8126OpenCL, @code{a} is thus interpreted as @code{a != 0} and not @code{a < 0}. 8127As in the case of binary operations, this syntax is also accepted when 8128one of @code{b} or @code{c} is a scalar that is then transformed into a 8129vector. If both @code{b} and @code{c} are scalars and the type of 8130@code{true?b:c} has the same size as the element type of @code{a}, then 8131@code{b} and @code{c} are converted to a vector type whose elements have 8132this type and with the same number of elements as @code{a}. 8133 8134In C++, the logic operators @code{!, &&, ||} are available for vectors. 8135@code{!v} is equivalent to @code{v == 0}, @code{a && b} is equivalent to 8136@code{a!=0 & b!=0} and @code{a || b} is equivalent to @code{a!=0 | b!=0}. 8137For mixed operations between a scalar @code{s} and a vector @code{v}, 8138@code{s && v} is equivalent to @code{s?v!=0:0} (the evaluation is 8139short-circuit) and @code{v && s} is equivalent to @code{v!=0 & (s?-1:0)}. 8140 8141Vector shuffling is available using functions 8142@code{__builtin_shuffle (vec, mask)} and 8143@code{__builtin_shuffle (vec0, vec1, mask)}. 8144Both functions construct a permutation of elements from one or two 8145vectors and return a vector of the same type as the input vector(s). 8146The @var{mask} is an integral vector with the same width (@var{W}) 8147and element count (@var{N}) as the output vector. 8148 8149The elements of the input vectors are numbered in memory ordering of 8150@var{vec0} beginning at 0 and @var{vec1} beginning at @var{N}. The 8151elements of @var{mask} are considered modulo @var{N} in the single-operand 8152case and modulo @math{2*@var{N}} in the two-operand case. 8153 8154Consider the following example, 8155 8156@smallexample 8157typedef int v4si __attribute__ ((vector_size (16))); 8158 8159v4si a = @{1,2,3,4@}; 8160v4si b = @{5,6,7,8@}; 8161v4si mask1 = @{0,1,1,3@}; 8162v4si mask2 = @{0,4,2,5@}; 8163v4si res; 8164 8165res = __builtin_shuffle (a, mask1); /* res is @{1,2,2,4@} */ 8166res = __builtin_shuffle (a, b, mask2); /* res is @{1,5,3,6@} */ 8167@end smallexample 8168 8169Note that @code{__builtin_shuffle} is intentionally semantically 8170compatible with the OpenCL @code{shuffle} and @code{shuffle2} functions. 8171 8172You can declare variables and use them in function calls and returns, as 8173well as in assignments and some casts. You can specify a vector type as 8174a return type for a function. Vector types can also be used as function 8175arguments. It is possible to cast from one vector type to another, 8176provided they are of the same size (in fact, you can also cast vectors 8177to and from other datatypes of the same size). 8178 8179You cannot operate between vectors of different lengths or different 8180signedness without a cast. 8181 8182@node Offsetof 8183@section Support for @code{offsetof} 8184@findex __builtin_offsetof 8185 8186GCC implements for both C and C++ a syntactic extension to implement 8187the @code{offsetof} macro. 8188 8189@smallexample 8190primary: 8191 "__builtin_offsetof" "(" @code{typename} "," offsetof_member_designator ")" 8192 8193offsetof_member_designator: 8194 @code{identifier} 8195 | offsetof_member_designator "." @code{identifier} 8196 | offsetof_member_designator "[" @code{expr} "]" 8197@end smallexample 8198 8199This extension is sufficient such that 8200 8201@smallexample 8202#define offsetof(@var{type}, @var{member}) __builtin_offsetof (@var{type}, @var{member}) 8203@end smallexample 8204 8205@noindent 8206is a suitable definition of the @code{offsetof} macro. In C++, @var{type} 8207may be dependent. In either case, @var{member} may consist of a single 8208identifier, or a sequence of member accesses and array references. 8209 8210@node __sync Builtins 8211@section Legacy @code{__sync} Built-in Functions for Atomic Memory Access 8212 8213The following built-in functions 8214are intended to be compatible with those described 8215in the @cite{Intel Itanium Processor-specific Application Binary Interface}, 8216section 7.4. As such, they depart from the normal GCC practice of using 8217the @samp{__builtin_} prefix, and further that they are overloaded such that 8218they work on multiple types. 8219 8220The definition given in the Intel documentation allows only for the use of 8221the types @code{int}, @code{long}, @code{long long} as well as their unsigned 8222counterparts. GCC allows any integral scalar or pointer type that is 82231, 2, 4 or 8 bytes in length. 8224 8225Not all operations are supported by all target processors. If a particular 8226operation cannot be implemented on the target processor, a warning is 8227generated and a call to an external function is generated. The external 8228function carries the same name as the built-in version, 8229with an additional suffix 8230@samp{_@var{n}} where @var{n} is the size of the data type. 8231 8232@c ??? Should we have a mechanism to suppress this warning? This is almost 8233@c useful for implementing the operation under the control of an external 8234@c mutex. 8235 8236In most cases, these built-in functions are considered a @dfn{full barrier}. 8237That is, 8238no memory operand is moved across the operation, either forward or 8239backward. Further, instructions are issued as necessary to prevent the 8240processor from speculating loads across the operation and from queuing stores 8241after the operation. 8242 8243All of the routines are described in the Intel documentation to take 8244``an optional list of variables protected by the memory barrier''. It's 8245not clear what is meant by that; it could mean that @emph{only} the 8246following variables are protected, or it could mean that these variables 8247should in addition be protected. At present GCC ignores this list and 8248protects all variables that are globally accessible. If in the future 8249we make some use of this list, an empty list will continue to mean all 8250globally accessible variables. 8251 8252@table @code 8253@item @var{type} __sync_fetch_and_add (@var{type} *ptr, @var{type} value, ...) 8254@itemx @var{type} __sync_fetch_and_sub (@var{type} *ptr, @var{type} value, ...) 8255@itemx @var{type} __sync_fetch_and_or (@var{type} *ptr, @var{type} value, ...) 8256@itemx @var{type} __sync_fetch_and_and (@var{type} *ptr, @var{type} value, ...) 8257@itemx @var{type} __sync_fetch_and_xor (@var{type} *ptr, @var{type} value, ...) 8258@itemx @var{type} __sync_fetch_and_nand (@var{type} *ptr, @var{type} value, ...) 8259@findex __sync_fetch_and_add 8260@findex __sync_fetch_and_sub 8261@findex __sync_fetch_and_or 8262@findex __sync_fetch_and_and 8263@findex __sync_fetch_and_xor 8264@findex __sync_fetch_and_nand 8265These built-in functions perform the operation suggested by the name, and 8266returns the value that had previously been in memory. That is, 8267 8268@smallexample 8269@{ tmp = *ptr; *ptr @var{op}= value; return tmp; @} 8270@{ tmp = *ptr; *ptr = ~(tmp & value); return tmp; @} // nand 8271@end smallexample 8272 8273@emph{Note:} GCC 4.4 and later implement @code{__sync_fetch_and_nand} 8274as @code{*ptr = ~(tmp & value)} instead of @code{*ptr = ~tmp & value}. 8275 8276@item @var{type} __sync_add_and_fetch (@var{type} *ptr, @var{type} value, ...) 8277@itemx @var{type} __sync_sub_and_fetch (@var{type} *ptr, @var{type} value, ...) 8278@itemx @var{type} __sync_or_and_fetch (@var{type} *ptr, @var{type} value, ...) 8279@itemx @var{type} __sync_and_and_fetch (@var{type} *ptr, @var{type} value, ...) 8280@itemx @var{type} __sync_xor_and_fetch (@var{type} *ptr, @var{type} value, ...) 8281@itemx @var{type} __sync_nand_and_fetch (@var{type} *ptr, @var{type} value, ...) 8282@findex __sync_add_and_fetch 8283@findex __sync_sub_and_fetch 8284@findex __sync_or_and_fetch 8285@findex __sync_and_and_fetch 8286@findex __sync_xor_and_fetch 8287@findex __sync_nand_and_fetch 8288These built-in functions perform the operation suggested by the name, and 8289return the new value. That is, 8290 8291@smallexample 8292@{ *ptr @var{op}= value; return *ptr; @} 8293@{ *ptr = ~(*ptr & value); return *ptr; @} // nand 8294@end smallexample 8295 8296@emph{Note:} GCC 4.4 and later implement @code{__sync_nand_and_fetch} 8297as @code{*ptr = ~(*ptr & value)} instead of 8298@code{*ptr = ~*ptr & value}. 8299 8300@item bool __sync_bool_compare_and_swap (@var{type} *ptr, @var{type} oldval, @var{type} newval, ...) 8301@itemx @var{type} __sync_val_compare_and_swap (@var{type} *ptr, @var{type} oldval, @var{type} newval, ...) 8302@findex __sync_bool_compare_and_swap 8303@findex __sync_val_compare_and_swap 8304These built-in functions perform an atomic compare and swap. 8305That is, if the current 8306value of @code{*@var{ptr}} is @var{oldval}, then write @var{newval} into 8307@code{*@var{ptr}}. 8308 8309The ``bool'' version returns true if the comparison is successful and 8310@var{newval} is written. The ``val'' version returns the contents 8311of @code{*@var{ptr}} before the operation. 8312 8313@item __sync_synchronize (...) 8314@findex __sync_synchronize 8315This built-in function issues a full memory barrier. 8316 8317@item @var{type} __sync_lock_test_and_set (@var{type} *ptr, @var{type} value, ...) 8318@findex __sync_lock_test_and_set 8319This built-in function, as described by Intel, is not a traditional test-and-set 8320operation, but rather an atomic exchange operation. It writes @var{value} 8321into @code{*@var{ptr}}, and returns the previous contents of 8322@code{*@var{ptr}}. 8323 8324Many targets have only minimal support for such locks, and do not support 8325a full exchange operation. In this case, a target may support reduced 8326functionality here by which the @emph{only} valid value to store is the 8327immediate constant 1. The exact value actually stored in @code{*@var{ptr}} 8328is implementation defined. 8329 8330This built-in function is not a full barrier, 8331but rather an @dfn{acquire barrier}. 8332This means that references after the operation cannot move to (or be 8333speculated to) before the operation, but previous memory stores may not 8334be globally visible yet, and previous memory loads may not yet be 8335satisfied. 8336 8337@item void __sync_lock_release (@var{type} *ptr, ...) 8338@findex __sync_lock_release 8339This built-in function releases the lock acquired by 8340@code{__sync_lock_test_and_set}. 8341Normally this means writing the constant 0 to @code{*@var{ptr}}. 8342 8343This built-in function is not a full barrier, 8344but rather a @dfn{release barrier}. 8345This means that all previous memory stores are globally visible, and all 8346previous memory loads have been satisfied, but following memory reads 8347are not prevented from being speculated to before the barrier. 8348@end table 8349 8350@node __atomic Builtins 8351@section Built-in Functions for Memory Model Aware Atomic Operations 8352 8353The following built-in functions approximately match the requirements for 8354C++11 memory model. Many are similar to the @samp{__sync} prefixed built-in 8355functions, but all also have a memory model parameter. These are all 8356identified by being prefixed with @samp{__atomic}, and most are overloaded 8357such that they work with multiple types. 8358 8359GCC allows any integral scalar or pointer type that is 1, 2, 4, or 8 8360bytes in length. 16-byte integral types are also allowed if 8361@samp{__int128} (@pxref{__int128}) is supported by the architecture. 8362 8363Target architectures are encouraged to provide their own patterns for 8364each of these built-in functions. If no target is provided, the original 8365non-memory model set of @samp{__sync} atomic built-in functions are 8366utilized, along with any required synchronization fences surrounding it in 8367order to achieve the proper behavior. Execution in this case is subject 8368to the same restrictions as those built-in functions. 8369 8370If there is no pattern or mechanism to provide a lock free instruction 8371sequence, a call is made to an external routine with the same parameters 8372to be resolved at run time. 8373 8374The four non-arithmetic functions (load, store, exchange, and 8375compare_exchange) all have a generic version as well. This generic 8376version works on any data type. If the data type size maps to one 8377of the integral sizes that may have lock free support, the generic 8378version utilizes the lock free built-in function. Otherwise an 8379external call is left to be resolved at run time. This external call is 8380the same format with the addition of a @samp{size_t} parameter inserted 8381as the first parameter indicating the size of the object being pointed to. 8382All objects must be the same size. 8383 8384There are 6 different memory models that can be specified. These map 8385to the same names in the C++11 standard. Refer there or to the 8386@uref{http://gcc.gnu.org/wiki/Atomic/GCCMM/AtomicSync,GCC wiki on 8387atomic synchronization} for more detailed definitions. These memory 8388models integrate both barriers to code motion as well as synchronization 8389requirements with other threads. These are listed in approximately 8390ascending order of strength. It is also possible to use target specific 8391flags for memory model flags, like Hardware Lock Elision. 8392 8393@table @code 8394@item __ATOMIC_RELAXED 8395No barriers or synchronization. 8396@item __ATOMIC_CONSUME 8397Data dependency only for both barrier and synchronization with another 8398thread. 8399@item __ATOMIC_ACQUIRE 8400Barrier to hoisting of code and synchronizes with release (or stronger) 8401semantic stores from another thread. 8402@item __ATOMIC_RELEASE 8403Barrier to sinking of code and synchronizes with acquire (or stronger) 8404semantic loads from another thread. 8405@item __ATOMIC_ACQ_REL 8406Full barrier in both directions and synchronizes with acquire loads and 8407release stores in another thread. 8408@item __ATOMIC_SEQ_CST 8409Full barrier in both directions and synchronizes with acquire loads and 8410release stores in all threads. 8411@end table 8412 8413When implementing patterns for these built-in functions, the memory model 8414parameter can be ignored as long as the pattern implements the most 8415restrictive @code{__ATOMIC_SEQ_CST} model. Any of the other memory models 8416execute correctly with this memory model but they may not execute as 8417efficiently as they could with a more appropriate implementation of the 8418relaxed requirements. 8419 8420Note that the C++11 standard allows for the memory model parameter to be 8421determined at run time rather than at compile time. These built-in 8422functions map any run-time value to @code{__ATOMIC_SEQ_CST} rather 8423than invoke a runtime library call or inline a switch statement. This is 8424standard compliant, safe, and the simplest approach for now. 8425 8426The memory model parameter is a signed int, but only the lower 16 bits are 8427reserved for the memory model. The remainder of the signed int is reserved 8428for target use and should be 0. Use of the predefined atomic values 8429ensures proper usage. 8430 8431@deftypefn {Built-in Function} @var{type} __atomic_load_n (@var{type} *ptr, int memmodel) 8432This built-in function implements an atomic load operation. It returns the 8433contents of @code{*@var{ptr}}. 8434 8435The valid memory model variants are 8436@code{__ATOMIC_RELAXED}, @code{__ATOMIC_SEQ_CST}, @code{__ATOMIC_ACQUIRE}, 8437and @code{__ATOMIC_CONSUME}. 8438 8439@end deftypefn 8440 8441@deftypefn {Built-in Function} void __atomic_load (@var{type} *ptr, @var{type} *ret, int memmodel) 8442This is the generic version of an atomic load. It returns the 8443contents of @code{*@var{ptr}} in @code{*@var{ret}}. 8444 8445@end deftypefn 8446 8447@deftypefn {Built-in Function} void __atomic_store_n (@var{type} *ptr, @var{type} val, int memmodel) 8448This built-in function implements an atomic store operation. It writes 8449@code{@var{val}} into @code{*@var{ptr}}. 8450 8451The valid memory model variants are 8452@code{__ATOMIC_RELAXED}, @code{__ATOMIC_SEQ_CST}, and @code{__ATOMIC_RELEASE}. 8453 8454@end deftypefn 8455 8456@deftypefn {Built-in Function} void __atomic_store (@var{type} *ptr, @var{type} *val, int memmodel) 8457This is the generic version of an atomic store. It stores the value 8458of @code{*@var{val}} into @code{*@var{ptr}}. 8459 8460@end deftypefn 8461 8462@deftypefn {Built-in Function} @var{type} __atomic_exchange_n (@var{type} *ptr, @var{type} val, int memmodel) 8463This built-in function implements an atomic exchange operation. It writes 8464@var{val} into @code{*@var{ptr}}, and returns the previous contents of 8465@code{*@var{ptr}}. 8466 8467The valid memory model variants are 8468@code{__ATOMIC_RELAXED}, @code{__ATOMIC_SEQ_CST}, @code{__ATOMIC_ACQUIRE}, 8469@code{__ATOMIC_RELEASE}, and @code{__ATOMIC_ACQ_REL}. 8470 8471@end deftypefn 8472 8473@deftypefn {Built-in Function} void __atomic_exchange (@var{type} *ptr, @var{type} *val, @var{type} *ret, int memmodel) 8474This is the generic version of an atomic exchange. It stores the 8475contents of @code{*@var{val}} into @code{*@var{ptr}}. The original value 8476of @code{*@var{ptr}} is copied into @code{*@var{ret}}. 8477 8478@end deftypefn 8479 8480@deftypefn {Built-in Function} bool __atomic_compare_exchange_n (@var{type} *ptr, @var{type} *expected, @var{type} desired, bool weak, int success_memmodel, int failure_memmodel) 8481This built-in function implements an atomic compare and exchange operation. 8482This compares the contents of @code{*@var{ptr}} with the contents of 8483@code{*@var{expected}} and if equal, writes @var{desired} into 8484@code{*@var{ptr}}. If they are not equal, the current contents of 8485@code{*@var{ptr}} is written into @code{*@var{expected}}. @var{weak} is true 8486for weak compare_exchange, and false for the strong variation. Many targets 8487only offer the strong variation and ignore the parameter. When in doubt, use 8488the strong variation. 8489 8490True is returned if @var{desired} is written into 8491@code{*@var{ptr}} and the execution is considered to conform to the 8492memory model specified by @var{success_memmodel}. There are no 8493restrictions on what memory model can be used here. 8494 8495False is returned otherwise, and the execution is considered to conform 8496to @var{failure_memmodel}. This memory model cannot be 8497@code{__ATOMIC_RELEASE} nor @code{__ATOMIC_ACQ_REL}. It also cannot be a 8498stronger model than that specified by @var{success_memmodel}. 8499 8500@end deftypefn 8501 8502@deftypefn {Built-in Function} bool __atomic_compare_exchange (@var{type} *ptr, @var{type} *expected, @var{type} *desired, bool weak, int success_memmodel, int failure_memmodel) 8503This built-in function implements the generic version of 8504@code{__atomic_compare_exchange}. The function is virtually identical to 8505@code{__atomic_compare_exchange_n}, except the desired value is also a 8506pointer. 8507 8508@end deftypefn 8509 8510@deftypefn {Built-in Function} @var{type} __atomic_add_fetch (@var{type} *ptr, @var{type} val, int memmodel) 8511@deftypefnx {Built-in Function} @var{type} __atomic_sub_fetch (@var{type} *ptr, @var{type} val, int memmodel) 8512@deftypefnx {Built-in Function} @var{type} __atomic_and_fetch (@var{type} *ptr, @var{type} val, int memmodel) 8513@deftypefnx {Built-in Function} @var{type} __atomic_xor_fetch (@var{type} *ptr, @var{type} val, int memmodel) 8514@deftypefnx {Built-in Function} @var{type} __atomic_or_fetch (@var{type} *ptr, @var{type} val, int memmodel) 8515@deftypefnx {Built-in Function} @var{type} __atomic_nand_fetch (@var{type} *ptr, @var{type} val, int memmodel) 8516These built-in functions perform the operation suggested by the name, and 8517return the result of the operation. That is, 8518 8519@smallexample 8520@{ *ptr @var{op}= val; return *ptr; @} 8521@end smallexample 8522 8523All memory models are valid. 8524 8525@end deftypefn 8526 8527@deftypefn {Built-in Function} @var{type} __atomic_fetch_add (@var{type} *ptr, @var{type} val, int memmodel) 8528@deftypefnx {Built-in Function} @var{type} __atomic_fetch_sub (@var{type} *ptr, @var{type} val, int memmodel) 8529@deftypefnx {Built-in Function} @var{type} __atomic_fetch_and (@var{type} *ptr, @var{type} val, int memmodel) 8530@deftypefnx {Built-in Function} @var{type} __atomic_fetch_xor (@var{type} *ptr, @var{type} val, int memmodel) 8531@deftypefnx {Built-in Function} @var{type} __atomic_fetch_or (@var{type} *ptr, @var{type} val, int memmodel) 8532@deftypefnx {Built-in Function} @var{type} __atomic_fetch_nand (@var{type} *ptr, @var{type} val, int memmodel) 8533These built-in functions perform the operation suggested by the name, and 8534return the value that had previously been in @code{*@var{ptr}}. That is, 8535 8536@smallexample 8537@{ tmp = *ptr; *ptr @var{op}= val; return tmp; @} 8538@end smallexample 8539 8540All memory models are valid. 8541 8542@end deftypefn 8543 8544@deftypefn {Built-in Function} bool __atomic_test_and_set (void *ptr, int memmodel) 8545 8546This built-in function performs an atomic test-and-set operation on 8547the byte at @code{*@var{ptr}}. The byte is set to some implementation 8548defined nonzero ``set'' value and the return value is @code{true} if and only 8549if the previous contents were ``set''. 8550It should be only used for operands of type @code{bool} or @code{char}. For 8551other types only part of the value may be set. 8552 8553All memory models are valid. 8554 8555@end deftypefn 8556 8557@deftypefn {Built-in Function} void __atomic_clear (bool *ptr, int memmodel) 8558 8559This built-in function performs an atomic clear operation on 8560@code{*@var{ptr}}. After the operation, @code{*@var{ptr}} contains 0. 8561It should be only used for operands of type @code{bool} or @code{char} and 8562in conjunction with @code{__atomic_test_and_set}. 8563For other types it may only clear partially. If the type is not @code{bool} 8564prefer using @code{__atomic_store}. 8565 8566The valid memory model variants are 8567@code{__ATOMIC_RELAXED}, @code{__ATOMIC_SEQ_CST}, and 8568@code{__ATOMIC_RELEASE}. 8569 8570@end deftypefn 8571 8572@deftypefn {Built-in Function} void __atomic_thread_fence (int memmodel) 8573 8574This built-in function acts as a synchronization fence between threads 8575based on the specified memory model. 8576 8577All memory orders are valid. 8578 8579@end deftypefn 8580 8581@deftypefn {Built-in Function} void __atomic_signal_fence (int memmodel) 8582 8583This built-in function acts as a synchronization fence between a thread 8584and signal handlers based in the same thread. 8585 8586All memory orders are valid. 8587 8588@end deftypefn 8589 8590@deftypefn {Built-in Function} bool __atomic_always_lock_free (size_t size, void *ptr) 8591 8592This built-in function returns true if objects of @var{size} bytes always 8593generate lock free atomic instructions for the target architecture. 8594@var{size} must resolve to a compile-time constant and the result also 8595resolves to a compile-time constant. 8596 8597@var{ptr} is an optional pointer to the object that may be used to determine 8598alignment. A value of 0 indicates typical alignment should be used. The 8599compiler may also ignore this parameter. 8600 8601@smallexample 8602if (_atomic_always_lock_free (sizeof (long long), 0)) 8603@end smallexample 8604 8605@end deftypefn 8606 8607@deftypefn {Built-in Function} bool __atomic_is_lock_free (size_t size, void *ptr) 8608 8609This built-in function returns true if objects of @var{size} bytes always 8610generate lock free atomic instructions for the target architecture. If 8611it is not known to be lock free a call is made to a runtime routine named 8612@code{__atomic_is_lock_free}. 8613 8614@var{ptr} is an optional pointer to the object that may be used to determine 8615alignment. A value of 0 indicates typical alignment should be used. The 8616compiler may also ignore this parameter. 8617@end deftypefn 8618 8619@node Integer Overflow Builtins 8620@section Built-in Functions to Perform Arithmetic with Overflow Checking 8621 8622The following built-in functions allow performing simple arithmetic operations 8623together with checking whether the operations overflowed. 8624 8625@deftypefn {Built-in Function} bool __builtin_add_overflow (@var{type1} a, @var{type2} b, @var{type3} *res) 8626@deftypefnx {Built-in Function} bool __builtin_sadd_overflow (int a, int b, int *res) 8627@deftypefnx {Built-in Function} bool __builtin_saddl_overflow (long int a, long int b, long int *res) 8628@deftypefnx {Built-in Function} bool __builtin_saddll_overflow (long long int a, long long int b, long int *res) 8629@deftypefnx {Built-in Function} bool __builtin_uadd_overflow (unsigned int a, unsigned int b, unsigned int *res) 8630@deftypefnx {Built-in Function} bool __builtin_uaddl_overflow (unsigned long int a, unsigned long int b, unsigned long int *res) 8631@deftypefnx {Built-in Function} bool __builtin_uaddll_overflow (unsigned long long int a, unsigned long long int b, unsigned long int *res) 8632 8633These built-in functions promote the first two operands into infinite precision signed 8634type and perform addition on those promoted operands. The result is then 8635cast to the type the third pointer argument points to and stored there. 8636If the stored result is equal to the infinite precision result, the built-in 8637functions return false, otherwise they return true. As the addition is 8638performed in infinite signed precision, these built-in functions have fully defined 8639behavior for all argument values. 8640 8641The first built-in function allows arbitrary integral types for operands and 8642the result type must be pointer to some integer type, the rest of the built-in 8643functions have explicit integer types. 8644 8645The compiler will attempt to use hardware instructions to implement 8646these built-in functions where possible, like conditional jump on overflow 8647after addition, conditional jump on carry etc. 8648 8649@end deftypefn 8650 8651@deftypefn {Built-in Function} bool __builtin_sub_overflow (@var{type1} a, @var{type2} b, @var{type3} *res) 8652@deftypefnx {Built-in Function} bool __builtin_ssub_overflow (int a, int b, int *res) 8653@deftypefnx {Built-in Function} bool __builtin_ssubl_overflow (long int a, long int b, long int *res) 8654@deftypefnx {Built-in Function} bool __builtin_ssubll_overflow (long long int a, long long int b, long int *res) 8655@deftypefnx {Built-in Function} bool __builtin_usub_overflow (unsigned int a, unsigned int b, unsigned int *res) 8656@deftypefnx {Built-in Function} bool __builtin_usubl_overflow (unsigned long int a, unsigned long int b, unsigned long int *res) 8657@deftypefnx {Built-in Function} bool __builtin_usubll_overflow (unsigned long long int a, unsigned long long int b, unsigned long int *res) 8658 8659These built-in functions are similar to the add overflow checking built-in 8660functions above, except they perform subtraction, subtract the second argument 8661from the first one, instead of addition. 8662 8663@end deftypefn 8664 8665@deftypefn {Built-in Function} bool __builtin_mul_overflow (@var{type1} a, @var{type2} b, @var{type3} *res) 8666@deftypefnx {Built-in Function} bool __builtin_smul_overflow (int a, int b, int *res) 8667@deftypefnx {Built-in Function} bool __builtin_smull_overflow (long int a, long int b, long int *res) 8668@deftypefnx {Built-in Function} bool __builtin_smulll_overflow (long long int a, long long int b, long int *res) 8669@deftypefnx {Built-in Function} bool __builtin_umul_overflow (unsigned int a, unsigned int b, unsigned int *res) 8670@deftypefnx {Built-in Function} bool __builtin_umull_overflow (unsigned long int a, unsigned long int b, unsigned long int *res) 8671@deftypefnx {Built-in Function} bool __builtin_umulll_overflow (unsigned long long int a, unsigned long long int b, unsigned long int *res) 8672 8673These built-in functions are similar to the add overflow checking built-in 8674functions above, except they perform multiplication, instead of addition. 8675 8676@end deftypefn 8677 8678@node x86 specific memory model extensions for transactional memory 8679@section x86-Specific Memory Model Extensions for Transactional Memory 8680 8681The x86 architecture supports additional memory ordering flags 8682to mark lock critical sections for hardware lock elision. 8683These must be specified in addition to an existing memory model to 8684atomic intrinsics. 8685 8686@table @code 8687@item __ATOMIC_HLE_ACQUIRE 8688Start lock elision on a lock variable. 8689Memory model must be @code{__ATOMIC_ACQUIRE} or stronger. 8690@item __ATOMIC_HLE_RELEASE 8691End lock elision on a lock variable. 8692Memory model must be @code{__ATOMIC_RELEASE} or stronger. 8693@end table 8694 8695When a lock acquire fails it is required for good performance to abort 8696the transaction quickly. This can be done with a @code{_mm_pause} 8697 8698@smallexample 8699#include <immintrin.h> // For _mm_pause 8700 8701int lockvar; 8702 8703/* Acquire lock with lock elision */ 8704while (__atomic_exchange_n(&lockvar, 1, __ATOMIC_ACQUIRE|__ATOMIC_HLE_ACQUIRE)) 8705 _mm_pause(); /* Abort failed transaction */ 8706... 8707/* Free lock with lock elision */ 8708__atomic_store_n(&lockvar, 0, __ATOMIC_RELEASE|__ATOMIC_HLE_RELEASE); 8709@end smallexample 8710 8711@node Object Size Checking 8712@section Object Size Checking Built-in Functions 8713@findex __builtin_object_size 8714@findex __builtin___memcpy_chk 8715@findex __builtin___mempcpy_chk 8716@findex __builtin___memmove_chk 8717@findex __builtin___memset_chk 8718@findex __builtin___strcpy_chk 8719@findex __builtin___stpcpy_chk 8720@findex __builtin___strncpy_chk 8721@findex __builtin___strcat_chk 8722@findex __builtin___strncat_chk 8723@findex __builtin___sprintf_chk 8724@findex __builtin___snprintf_chk 8725@findex __builtin___vsprintf_chk 8726@findex __builtin___vsnprintf_chk 8727@findex __builtin___printf_chk 8728@findex __builtin___vprintf_chk 8729@findex __builtin___fprintf_chk 8730@findex __builtin___vfprintf_chk 8731 8732GCC implements a limited buffer overflow protection mechanism 8733that can prevent some buffer overflow attacks. 8734 8735@deftypefn {Built-in Function} {size_t} __builtin_object_size (void * @var{ptr}, int @var{type}) 8736is a built-in construct that returns a constant number of bytes from 8737@var{ptr} to the end of the object @var{ptr} pointer points to 8738(if known at compile time). @code{__builtin_object_size} never evaluates 8739its arguments for side-effects. If there are any side-effects in them, it 8740returns @code{(size_t) -1} for @var{type} 0 or 1 and @code{(size_t) 0} 8741for @var{type} 2 or 3. If there are multiple objects @var{ptr} can 8742point to and all of them are known at compile time, the returned number 8743is the maximum of remaining byte counts in those objects if @var{type} & 2 is 87440 and minimum if nonzero. If it is not possible to determine which objects 8745@var{ptr} points to at compile time, @code{__builtin_object_size} should 8746return @code{(size_t) -1} for @var{type} 0 or 1 and @code{(size_t) 0} 8747for @var{type} 2 or 3. 8748 8749@var{type} is an integer constant from 0 to 3. If the least significant 8750bit is clear, objects are whole variables, if it is set, a closest 8751surrounding subobject is considered the object a pointer points to. 8752The second bit determines if maximum or minimum of remaining bytes 8753is computed. 8754 8755@smallexample 8756struct V @{ char buf1[10]; int b; char buf2[10]; @} var; 8757char *p = &var.buf1[1], *q = &var.b; 8758 8759/* Here the object p points to is var. */ 8760assert (__builtin_object_size (p, 0) == sizeof (var) - 1); 8761/* The subobject p points to is var.buf1. */ 8762assert (__builtin_object_size (p, 1) == sizeof (var.buf1) - 1); 8763/* The object q points to is var. */ 8764assert (__builtin_object_size (q, 0) 8765 == (char *) (&var + 1) - (char *) &var.b); 8766/* The subobject q points to is var.b. */ 8767assert (__builtin_object_size (q, 1) == sizeof (var.b)); 8768@end smallexample 8769@end deftypefn 8770 8771There are built-in functions added for many common string operation 8772functions, e.g., for @code{memcpy} @code{__builtin___memcpy_chk} 8773built-in is provided. This built-in has an additional last argument, 8774which is the number of bytes remaining in object the @var{dest} 8775argument points to or @code{(size_t) -1} if the size is not known. 8776 8777The built-in functions are optimized into the normal string functions 8778like @code{memcpy} if the last argument is @code{(size_t) -1} or if 8779it is known at compile time that the destination object will not 8780be overflown. If the compiler can determine at compile time the 8781object will be always overflown, it issues a warning. 8782 8783The intended use can be e.g.@: 8784 8785@smallexample 8786#undef memcpy 8787#define bos0(dest) __builtin_object_size (dest, 0) 8788#define memcpy(dest, src, n) \ 8789 __builtin___memcpy_chk (dest, src, n, bos0 (dest)) 8790 8791char *volatile p; 8792char buf[10]; 8793/* It is unknown what object p points to, so this is optimized 8794 into plain memcpy - no checking is possible. */ 8795memcpy (p, "abcde", n); 8796/* Destination is known and length too. It is known at compile 8797 time there will be no overflow. */ 8798memcpy (&buf[5], "abcde", 5); 8799/* Destination is known, but the length is not known at compile time. 8800 This will result in __memcpy_chk call that can check for overflow 8801 at run time. */ 8802memcpy (&buf[5], "abcde", n); 8803/* Destination is known and it is known at compile time there will 8804 be overflow. There will be a warning and __memcpy_chk call that 8805 will abort the program at run time. */ 8806memcpy (&buf[6], "abcde", 5); 8807@end smallexample 8808 8809Such built-in functions are provided for @code{memcpy}, @code{mempcpy}, 8810@code{memmove}, @code{memset}, @code{strcpy}, @code{stpcpy}, @code{strncpy}, 8811@code{strcat} and @code{strncat}. 8812 8813There are also checking built-in functions for formatted output functions. 8814@smallexample 8815int __builtin___sprintf_chk (char *s, int flag, size_t os, const char *fmt, ...); 8816int __builtin___snprintf_chk (char *s, size_t maxlen, int flag, size_t os, 8817 const char *fmt, ...); 8818int __builtin___vsprintf_chk (char *s, int flag, size_t os, const char *fmt, 8819 va_list ap); 8820int __builtin___vsnprintf_chk (char *s, size_t maxlen, int flag, size_t os, 8821 const char *fmt, va_list ap); 8822@end smallexample 8823 8824The added @var{flag} argument is passed unchanged to @code{__sprintf_chk} 8825etc.@: functions and can contain implementation specific flags on what 8826additional security measures the checking function might take, such as 8827handling @code{%n} differently. 8828 8829The @var{os} argument is the object size @var{s} points to, like in the 8830other built-in functions. There is a small difference in the behavior 8831though, if @var{os} is @code{(size_t) -1}, the built-in functions are 8832optimized into the non-checking functions only if @var{flag} is 0, otherwise 8833the checking function is called with @var{os} argument set to 8834@code{(size_t) -1}. 8835 8836In addition to this, there are checking built-in functions 8837@code{__builtin___printf_chk}, @code{__builtin___vprintf_chk}, 8838@code{__builtin___fprintf_chk} and @code{__builtin___vfprintf_chk}. 8839These have just one additional argument, @var{flag}, right before 8840format string @var{fmt}. If the compiler is able to optimize them to 8841@code{fputc} etc.@: functions, it does, otherwise the checking function 8842is called and the @var{flag} argument passed to it. 8843 8844@node Pointer Bounds Checker builtins 8845@section Pointer Bounds Checker Built-in Functions 8846@cindex Pointer Bounds Checker builtins 8847@findex __builtin___bnd_set_ptr_bounds 8848@findex __builtin___bnd_narrow_ptr_bounds 8849@findex __builtin___bnd_copy_ptr_bounds 8850@findex __builtin___bnd_init_ptr_bounds 8851@findex __builtin___bnd_null_ptr_bounds 8852@findex __builtin___bnd_store_ptr_bounds 8853@findex __builtin___bnd_chk_ptr_lbounds 8854@findex __builtin___bnd_chk_ptr_ubounds 8855@findex __builtin___bnd_chk_ptr_bounds 8856@findex __builtin___bnd_get_ptr_lbound 8857@findex __builtin___bnd_get_ptr_ubound 8858 8859GCC provides a set of built-in functions to control Pointer Bounds Checker 8860instrumentation. Note that all Pointer Bounds Checker builtins can be used 8861even if you compile with Pointer Bounds Checker off 8862(@option{-fno-check-pointer-bounds}). 8863The behavior may differ in such case as documented below. 8864 8865@deftypefn {Built-in Function} {void *} __builtin___bnd_set_ptr_bounds (const void *@var{q}, size_t @var{size}) 8866 8867This built-in function returns a new pointer with the value of @var{q}, and 8868associate it with the bounds [@var{q}, @var{q}+@var{size}-1]. With Pointer 8869Bounds Checker off, the built-in function just returns the first argument. 8870 8871@smallexample 8872extern void *__wrap_malloc (size_t n) 8873@{ 8874 void *p = (void *)__real_malloc (n); 8875 if (!p) return __builtin___bnd_null_ptr_bounds (p); 8876 return __builtin___bnd_set_ptr_bounds (p, n); 8877@} 8878@end smallexample 8879 8880@end deftypefn 8881 8882@deftypefn {Built-in Function} {void *} __builtin___bnd_narrow_ptr_bounds (const void *@var{p}, const void *@var{q}, size_t @var{size}) 8883 8884This built-in function returns a new pointer with the value of @var{p} 8885and associates it with the narrowed bounds formed by the intersection 8886of bounds associated with @var{q} and the bounds 8887[@var{p}, @var{p} + @var{size} - 1]. 8888With Pointer Bounds Checker off, the built-in function just returns the first 8889argument. 8890 8891@smallexample 8892void init_objects (object *objs, size_t size) 8893@{ 8894 size_t i; 8895 /* Initialize objects one-by-one passing pointers with bounds of 8896 an object, not the full array of objects. */ 8897 for (i = 0; i < size; i++) 8898 init_object (__builtin___bnd_narrow_ptr_bounds (objs + i, objs, 8899 sizeof(object))); 8900@} 8901@end smallexample 8902 8903@end deftypefn 8904 8905@deftypefn {Built-in Function} {void *} __builtin___bnd_copy_ptr_bounds (const void *@var{q}, const void *@var{r}) 8906 8907This built-in function returns a new pointer with the value of @var{q}, 8908and associates it with the bounds already associated with pointer @var{r}. 8909With Pointer Bounds Checker off, the built-in function just returns the first 8910argument. 8911 8912@smallexample 8913/* Here is a way to get pointer to object's field but 8914 still with the full object's bounds. */ 8915int *field_ptr = __builtin___bnd_copy_ptr_bounds (&objptr->int_field, 8916 objptr); 8917@end smallexample 8918 8919@end deftypefn 8920 8921@deftypefn {Built-in Function} {void *} __builtin___bnd_init_ptr_bounds (const void *@var{q}) 8922 8923This built-in function returns a new pointer with the value of @var{q}, and 8924associates it with INIT (allowing full memory access) bounds. With Pointer 8925Bounds Checker off, the built-in function just returns the first argument. 8926 8927@end deftypefn 8928 8929@deftypefn {Built-in Function} {void *} __builtin___bnd_null_ptr_bounds (const void *@var{q}) 8930 8931This built-in function returns a new pointer with the value of @var{q}, and 8932associates it with NULL (allowing no memory access) bounds. With Pointer 8933Bounds Checker off, the built-in function just returns the first argument. 8934 8935@end deftypefn 8936 8937@deftypefn {Built-in Function} void __builtin___bnd_store_ptr_bounds (const void **@var{ptr_addr}, const void *@var{ptr_val}) 8938 8939This built-in function stores the bounds associated with pointer @var{ptr_val} 8940and location @var{ptr_addr} into Bounds Table. This can be useful to propagate 8941bounds from legacy code without touching the associated pointer's memory when 8942pointers are copied as integers. With Pointer Bounds Checker off, the built-in 8943function call is ignored. 8944 8945@end deftypefn 8946 8947@deftypefn {Built-in Function} void __builtin___bnd_chk_ptr_lbounds (const void *@var{q}) 8948 8949This built-in function checks if the pointer @var{q} is within the lower 8950bound of its associated bounds. With Pointer Bounds Checker off, the built-in 8951function call is ignored. 8952 8953@smallexample 8954extern void *__wrap_memset (void *dst, int c, size_t len) 8955@{ 8956 if (len > 0) 8957 @{ 8958 __builtin___bnd_chk_ptr_lbounds (dst); 8959 __builtin___bnd_chk_ptr_ubounds ((char *)dst + len - 1); 8960 __real_memset (dst, c, len); 8961 @} 8962 return dst; 8963@} 8964@end smallexample 8965 8966@end deftypefn 8967 8968@deftypefn {Built-in Function} void __builtin___bnd_chk_ptr_ubounds (const void *@var{q}) 8969 8970This built-in function checks if the pointer @var{q} is within the upper 8971bound of its associated bounds. With Pointer Bounds Checker off, the built-in 8972function call is ignored. 8973 8974@end deftypefn 8975 8976@deftypefn {Built-in Function} void __builtin___bnd_chk_ptr_bounds (const void *@var{q}, size_t @var{size}) 8977 8978This built-in function checks if [@var{q}, @var{q} + @var{size} - 1] is within 8979the lower and upper bounds associated with @var{q}. With Pointer Bounds Checker 8980off, the built-in function call is ignored. 8981 8982@smallexample 8983extern void *__wrap_memcpy (void *dst, const void *src, size_t n) 8984@{ 8985 if (n > 0) 8986 @{ 8987 __bnd_chk_ptr_bounds (dst, n); 8988 __bnd_chk_ptr_bounds (src, n); 8989 __real_memcpy (dst, src, n); 8990 @} 8991 return dst; 8992@} 8993@end smallexample 8994 8995@end deftypefn 8996 8997@deftypefn {Built-in Function} {const void *} __builtin___bnd_get_ptr_lbound (const void *@var{q}) 8998 8999This built-in function returns the lower bound associated 9000with the pointer @var{q}, as a pointer value. 9001This is useful for debugging using @code{printf}. 9002With Pointer Bounds Checker off, the built-in function returns 0. 9003 9004@smallexample 9005void *lb = __builtin___bnd_get_ptr_lbound (q); 9006void *ub = __builtin___bnd_get_ptr_ubound (q); 9007printf ("q = %p lb(q) = %p ub(q) = %p", q, lb, ub); 9008@end smallexample 9009 9010@end deftypefn 9011 9012@deftypefn {Built-in Function} {const void *} __builtin___bnd_get_ptr_ubound (const void *@var{q}) 9013 9014This built-in function returns the upper bound (which is a pointer) associated 9015with the pointer @var{q}. With Pointer Bounds Checker off, 9016the built-in function returns -1. 9017 9018@end deftypefn 9019 9020@node Cilk Plus Builtins 9021@section Cilk Plus C/C++ Language Extension Built-in Functions 9022 9023GCC provides support for the following built-in reduction functions if Cilk Plus 9024is enabled. Cilk Plus can be enabled using the @option{-fcilkplus} flag. 9025 9026@itemize @bullet 9027@item @code{__sec_implicit_index} 9028@item @code{__sec_reduce} 9029@item @code{__sec_reduce_add} 9030@item @code{__sec_reduce_all_nonzero} 9031@item @code{__sec_reduce_all_zero} 9032@item @code{__sec_reduce_any_nonzero} 9033@item @code{__sec_reduce_any_zero} 9034@item @code{__sec_reduce_max} 9035@item @code{__sec_reduce_min} 9036@item @code{__sec_reduce_max_ind} 9037@item @code{__sec_reduce_min_ind} 9038@item @code{__sec_reduce_mul} 9039@item @code{__sec_reduce_mutating} 9040@end itemize 9041 9042Further details and examples about these built-in functions are described 9043in the Cilk Plus language manual which can be found at 9044@uref{http://www.cilkplus.org}. 9045 9046@node Other Builtins 9047@section Other Built-in Functions Provided by GCC 9048@cindex built-in functions 9049@findex __builtin_call_with_static_chain 9050@findex __builtin_fpclassify 9051@findex __builtin_isfinite 9052@findex __builtin_isnormal 9053@findex __builtin_isgreater 9054@findex __builtin_isgreaterequal 9055@findex __builtin_isinf_sign 9056@findex __builtin_isless 9057@findex __builtin_islessequal 9058@findex __builtin_islessgreater 9059@findex __builtin_isunordered 9060@findex __builtin_powi 9061@findex __builtin_powif 9062@findex __builtin_powil 9063@findex _Exit 9064@findex _exit 9065@findex abort 9066@findex abs 9067@findex acos 9068@findex acosf 9069@findex acosh 9070@findex acoshf 9071@findex acoshl 9072@findex acosl 9073@findex alloca 9074@findex asin 9075@findex asinf 9076@findex asinh 9077@findex asinhf 9078@findex asinhl 9079@findex asinl 9080@findex atan 9081@findex atan2 9082@findex atan2f 9083@findex atan2l 9084@findex atanf 9085@findex atanh 9086@findex atanhf 9087@findex atanhl 9088@findex atanl 9089@findex bcmp 9090@findex bzero 9091@findex cabs 9092@findex cabsf 9093@findex cabsl 9094@findex cacos 9095@findex cacosf 9096@findex cacosh 9097@findex cacoshf 9098@findex cacoshl 9099@findex cacosl 9100@findex calloc 9101@findex carg 9102@findex cargf 9103@findex cargl 9104@findex casin 9105@findex casinf 9106@findex casinh 9107@findex casinhf 9108@findex casinhl 9109@findex casinl 9110@findex catan 9111@findex catanf 9112@findex catanh 9113@findex catanhf 9114@findex catanhl 9115@findex catanl 9116@findex cbrt 9117@findex cbrtf 9118@findex cbrtl 9119@findex ccos 9120@findex ccosf 9121@findex ccosh 9122@findex ccoshf 9123@findex ccoshl 9124@findex ccosl 9125@findex ceil 9126@findex ceilf 9127@findex ceill 9128@findex cexp 9129@findex cexpf 9130@findex cexpl 9131@findex cimag 9132@findex cimagf 9133@findex cimagl 9134@findex clog 9135@findex clogf 9136@findex clogl 9137@findex conj 9138@findex conjf 9139@findex conjl 9140@findex copysign 9141@findex copysignf 9142@findex copysignl 9143@findex cos 9144@findex cosf 9145@findex cosh 9146@findex coshf 9147@findex coshl 9148@findex cosl 9149@findex cpow 9150@findex cpowf 9151@findex cpowl 9152@findex cproj 9153@findex cprojf 9154@findex cprojl 9155@findex creal 9156@findex crealf 9157@findex creall 9158@findex csin 9159@findex csinf 9160@findex csinh 9161@findex csinhf 9162@findex csinhl 9163@findex csinl 9164@findex csqrt 9165@findex csqrtf 9166@findex csqrtl 9167@findex ctan 9168@findex ctanf 9169@findex ctanh 9170@findex ctanhf 9171@findex ctanhl 9172@findex ctanl 9173@findex dcgettext 9174@findex dgettext 9175@findex drem 9176@findex dremf 9177@findex dreml 9178@findex erf 9179@findex erfc 9180@findex erfcf 9181@findex erfcl 9182@findex erff 9183@findex erfl 9184@findex exit 9185@findex exp 9186@findex exp10 9187@findex exp10f 9188@findex exp10l 9189@findex exp2 9190@findex exp2f 9191@findex exp2l 9192@findex expf 9193@findex expl 9194@findex expm1 9195@findex expm1f 9196@findex expm1l 9197@findex fabs 9198@findex fabsf 9199@findex fabsl 9200@findex fdim 9201@findex fdimf 9202@findex fdiml 9203@findex ffs 9204@findex floor 9205@findex floorf 9206@findex floorl 9207@findex fma 9208@findex fmaf 9209@findex fmal 9210@findex fmax 9211@findex fmaxf 9212@findex fmaxl 9213@findex fmin 9214@findex fminf 9215@findex fminl 9216@findex fmod 9217@findex fmodf 9218@findex fmodl 9219@findex fprintf 9220@findex fprintf_unlocked 9221@findex fputs 9222@findex fputs_unlocked 9223@findex frexp 9224@findex frexpf 9225@findex frexpl 9226@findex fscanf 9227@findex gamma 9228@findex gammaf 9229@findex gammal 9230@findex gamma_r 9231@findex gammaf_r 9232@findex gammal_r 9233@findex gettext 9234@findex hypot 9235@findex hypotf 9236@findex hypotl 9237@findex ilogb 9238@findex ilogbf 9239@findex ilogbl 9240@findex imaxabs 9241@findex index 9242@findex isalnum 9243@findex isalpha 9244@findex isascii 9245@findex isblank 9246@findex iscntrl 9247@findex isdigit 9248@findex isgraph 9249@findex islower 9250@findex isprint 9251@findex ispunct 9252@findex isspace 9253@findex isupper 9254@findex iswalnum 9255@findex iswalpha 9256@findex iswblank 9257@findex iswcntrl 9258@findex iswdigit 9259@findex iswgraph 9260@findex iswlower 9261@findex iswprint 9262@findex iswpunct 9263@findex iswspace 9264@findex iswupper 9265@findex iswxdigit 9266@findex isxdigit 9267@findex j0 9268@findex j0f 9269@findex j0l 9270@findex j1 9271@findex j1f 9272@findex j1l 9273@findex jn 9274@findex jnf 9275@findex jnl 9276@findex labs 9277@findex ldexp 9278@findex ldexpf 9279@findex ldexpl 9280@findex lgamma 9281@findex lgammaf 9282@findex lgammal 9283@findex lgamma_r 9284@findex lgammaf_r 9285@findex lgammal_r 9286@findex llabs 9287@findex llrint 9288@findex llrintf 9289@findex llrintl 9290@findex llround 9291@findex llroundf 9292@findex llroundl 9293@findex log 9294@findex log10 9295@findex log10f 9296@findex log10l 9297@findex log1p 9298@findex log1pf 9299@findex log1pl 9300@findex log2 9301@findex log2f 9302@findex log2l 9303@findex logb 9304@findex logbf 9305@findex logbl 9306@findex logf 9307@findex logl 9308@findex lrint 9309@findex lrintf 9310@findex lrintl 9311@findex lround 9312@findex lroundf 9313@findex lroundl 9314@findex malloc 9315@findex memchr 9316@findex memcmp 9317@findex memcpy 9318@findex mempcpy 9319@findex memset 9320@findex modf 9321@findex modff 9322@findex modfl 9323@findex nearbyint 9324@findex nearbyintf 9325@findex nearbyintl 9326@findex nextafter 9327@findex nextafterf 9328@findex nextafterl 9329@findex nexttoward 9330@findex nexttowardf 9331@findex nexttowardl 9332@findex pow 9333@findex pow10 9334@findex pow10f 9335@findex pow10l 9336@findex powf 9337@findex powl 9338@findex printf 9339@findex printf_unlocked 9340@findex putchar 9341@findex puts 9342@findex remainder 9343@findex remainderf 9344@findex remainderl 9345@findex remquo 9346@findex remquof 9347@findex remquol 9348@findex rindex 9349@findex rint 9350@findex rintf 9351@findex rintl 9352@findex round 9353@findex roundf 9354@findex roundl 9355@findex scalb 9356@findex scalbf 9357@findex scalbl 9358@findex scalbln 9359@findex scalblnf 9360@findex scalblnf 9361@findex scalbn 9362@findex scalbnf 9363@findex scanfnl 9364@findex signbit 9365@findex signbitf 9366@findex signbitl 9367@findex signbitd32 9368@findex signbitd64 9369@findex signbitd128 9370@findex significand 9371@findex significandf 9372@findex significandl 9373@findex sin 9374@findex sincos 9375@findex sincosf 9376@findex sincosl 9377@findex sinf 9378@findex sinh 9379@findex sinhf 9380@findex sinhl 9381@findex sinl 9382@findex snprintf 9383@findex sprintf 9384@findex sqrt 9385@findex sqrtf 9386@findex sqrtl 9387@findex sscanf 9388@findex stpcpy 9389@findex stpncpy 9390@findex strcasecmp 9391@findex strcat 9392@findex strchr 9393@findex strcmp 9394@findex strcpy 9395@findex strcspn 9396@findex strdup 9397@findex strfmon 9398@findex strftime 9399@findex strlen 9400@findex strncasecmp 9401@findex strncat 9402@findex strncmp 9403@findex strncpy 9404@findex strndup 9405@findex strpbrk 9406@findex strrchr 9407@findex strspn 9408@findex strstr 9409@findex tan 9410@findex tanf 9411@findex tanh 9412@findex tanhf 9413@findex tanhl 9414@findex tanl 9415@findex tgamma 9416@findex tgammaf 9417@findex tgammal 9418@findex toascii 9419@findex tolower 9420@findex toupper 9421@findex towlower 9422@findex towupper 9423@findex trunc 9424@findex truncf 9425@findex truncl 9426@findex vfprintf 9427@findex vfscanf 9428@findex vprintf 9429@findex vscanf 9430@findex vsnprintf 9431@findex vsprintf 9432@findex vsscanf 9433@findex y0 9434@findex y0f 9435@findex y0l 9436@findex y1 9437@findex y1f 9438@findex y1l 9439@findex yn 9440@findex ynf 9441@findex ynl 9442 9443GCC provides a large number of built-in functions other than the ones 9444mentioned above. Some of these are for internal use in the processing 9445of exceptions or variable-length argument lists and are not 9446documented here because they may change from time to time; we do not 9447recommend general use of these functions. 9448 9449The remaining functions are provided for optimization purposes. 9450 9451@opindex fno-builtin 9452GCC includes built-in versions of many of the functions in the standard 9453C library. The versions prefixed with @code{__builtin_} are always 9454treated as having the same meaning as the C library function even if you 9455specify the @option{-fno-builtin} option. (@pxref{C Dialect Options}) 9456Many of these functions are only optimized in certain cases; if they are 9457not optimized in a particular case, a call to the library function is 9458emitted. 9459 9460@opindex ansi 9461@opindex std 9462Outside strict ISO C mode (@option{-ansi}, @option{-std=c90}, 9463@option{-std=c99} or @option{-std=c11}), the functions 9464@code{_exit}, @code{alloca}, @code{bcmp}, @code{bzero}, 9465@code{dcgettext}, @code{dgettext}, @code{dremf}, @code{dreml}, 9466@code{drem}, @code{exp10f}, @code{exp10l}, @code{exp10}, @code{ffsll}, 9467@code{ffsl}, @code{ffs}, @code{fprintf_unlocked}, 9468@code{fputs_unlocked}, @code{gammaf}, @code{gammal}, @code{gamma}, 9469@code{gammaf_r}, @code{gammal_r}, @code{gamma_r}, @code{gettext}, 9470@code{index}, @code{isascii}, @code{j0f}, @code{j0l}, @code{j0}, 9471@code{j1f}, @code{j1l}, @code{j1}, @code{jnf}, @code{jnl}, @code{jn}, 9472@code{lgammaf_r}, @code{lgammal_r}, @code{lgamma_r}, @code{mempcpy}, 9473@code{pow10f}, @code{pow10l}, @code{pow10}, @code{printf_unlocked}, 9474@code{rindex}, @code{scalbf}, @code{scalbl}, @code{scalb}, 9475@code{signbit}, @code{signbitf}, @code{signbitl}, @code{signbitd32}, 9476@code{signbitd64}, @code{signbitd128}, @code{significandf}, 9477@code{significandl}, @code{significand}, @code{sincosf}, 9478@code{sincosl}, @code{sincos}, @code{stpcpy}, @code{stpncpy}, 9479@code{strcasecmp}, @code{strdup}, @code{strfmon}, @code{strncasecmp}, 9480@code{strndup}, @code{toascii}, @code{y0f}, @code{y0l}, @code{y0}, 9481@code{y1f}, @code{y1l}, @code{y1}, @code{ynf}, @code{ynl} and 9482@code{yn} 9483may be handled as built-in functions. 9484All these functions have corresponding versions 9485prefixed with @code{__builtin_}, which may be used even in strict C90 9486mode. 9487 9488The ISO C99 functions 9489@code{_Exit}, @code{acoshf}, @code{acoshl}, @code{acosh}, @code{asinhf}, 9490@code{asinhl}, @code{asinh}, @code{atanhf}, @code{atanhl}, @code{atanh}, 9491@code{cabsf}, @code{cabsl}, @code{cabs}, @code{cacosf}, @code{cacoshf}, 9492@code{cacoshl}, @code{cacosh}, @code{cacosl}, @code{cacos}, 9493@code{cargf}, @code{cargl}, @code{carg}, @code{casinf}, @code{casinhf}, 9494@code{casinhl}, @code{casinh}, @code{casinl}, @code{casin}, 9495@code{catanf}, @code{catanhf}, @code{catanhl}, @code{catanh}, 9496@code{catanl}, @code{catan}, @code{cbrtf}, @code{cbrtl}, @code{cbrt}, 9497@code{ccosf}, @code{ccoshf}, @code{ccoshl}, @code{ccosh}, @code{ccosl}, 9498@code{ccos}, @code{cexpf}, @code{cexpl}, @code{cexp}, @code{cimagf}, 9499@code{cimagl}, @code{cimag}, @code{clogf}, @code{clogl}, @code{clog}, 9500@code{conjf}, @code{conjl}, @code{conj}, @code{copysignf}, @code{copysignl}, 9501@code{copysign}, @code{cpowf}, @code{cpowl}, @code{cpow}, @code{cprojf}, 9502@code{cprojl}, @code{cproj}, @code{crealf}, @code{creall}, @code{creal}, 9503@code{csinf}, @code{csinhf}, @code{csinhl}, @code{csinh}, @code{csinl}, 9504@code{csin}, @code{csqrtf}, @code{csqrtl}, @code{csqrt}, @code{ctanf}, 9505@code{ctanhf}, @code{ctanhl}, @code{ctanh}, @code{ctanl}, @code{ctan}, 9506@code{erfcf}, @code{erfcl}, @code{erfc}, @code{erff}, @code{erfl}, 9507@code{erf}, @code{exp2f}, @code{exp2l}, @code{exp2}, @code{expm1f}, 9508@code{expm1l}, @code{expm1}, @code{fdimf}, @code{fdiml}, @code{fdim}, 9509@code{fmaf}, @code{fmal}, @code{fmaxf}, @code{fmaxl}, @code{fmax}, 9510@code{fma}, @code{fminf}, @code{fminl}, @code{fmin}, @code{hypotf}, 9511@code{hypotl}, @code{hypot}, @code{ilogbf}, @code{ilogbl}, @code{ilogb}, 9512@code{imaxabs}, @code{isblank}, @code{iswblank}, @code{lgammaf}, 9513@code{lgammal}, @code{lgamma}, @code{llabs}, @code{llrintf}, @code{llrintl}, 9514@code{llrint}, @code{llroundf}, @code{llroundl}, @code{llround}, 9515@code{log1pf}, @code{log1pl}, @code{log1p}, @code{log2f}, @code{log2l}, 9516@code{log2}, @code{logbf}, @code{logbl}, @code{logb}, @code{lrintf}, 9517@code{lrintl}, @code{lrint}, @code{lroundf}, @code{lroundl}, 9518@code{lround}, @code{nearbyintf}, @code{nearbyintl}, @code{nearbyint}, 9519@code{nextafterf}, @code{nextafterl}, @code{nextafter}, 9520@code{nexttowardf}, @code{nexttowardl}, @code{nexttoward}, 9521@code{remainderf}, @code{remainderl}, @code{remainder}, @code{remquof}, 9522@code{remquol}, @code{remquo}, @code{rintf}, @code{rintl}, @code{rint}, 9523@code{roundf}, @code{roundl}, @code{round}, @code{scalblnf}, 9524@code{scalblnl}, @code{scalbln}, @code{scalbnf}, @code{scalbnl}, 9525@code{scalbn}, @code{snprintf}, @code{tgammaf}, @code{tgammal}, 9526@code{tgamma}, @code{truncf}, @code{truncl}, @code{trunc}, 9527@code{vfscanf}, @code{vscanf}, @code{vsnprintf} and @code{vsscanf} 9528are handled as built-in functions 9529except in strict ISO C90 mode (@option{-ansi} or @option{-std=c90}). 9530 9531There are also built-in versions of the ISO C99 functions 9532@code{acosf}, @code{acosl}, @code{asinf}, @code{asinl}, @code{atan2f}, 9533@code{atan2l}, @code{atanf}, @code{atanl}, @code{ceilf}, @code{ceill}, 9534@code{cosf}, @code{coshf}, @code{coshl}, @code{cosl}, @code{expf}, 9535@code{expl}, @code{fabsf}, @code{fabsl}, @code{floorf}, @code{floorl}, 9536@code{fmodf}, @code{fmodl}, @code{frexpf}, @code{frexpl}, @code{ldexpf}, 9537@code{ldexpl}, @code{log10f}, @code{log10l}, @code{logf}, @code{logl}, 9538@code{modfl}, @code{modf}, @code{powf}, @code{powl}, @code{sinf}, 9539@code{sinhf}, @code{sinhl}, @code{sinl}, @code{sqrtf}, @code{sqrtl}, 9540@code{tanf}, @code{tanhf}, @code{tanhl} and @code{tanl} 9541that are recognized in any mode since ISO C90 reserves these names for 9542the purpose to which ISO C99 puts them. All these functions have 9543corresponding versions prefixed with @code{__builtin_}. 9544 9545The ISO C94 functions 9546@code{iswalnum}, @code{iswalpha}, @code{iswcntrl}, @code{iswdigit}, 9547@code{iswgraph}, @code{iswlower}, @code{iswprint}, @code{iswpunct}, 9548@code{iswspace}, @code{iswupper}, @code{iswxdigit}, @code{towlower} and 9549@code{towupper} 9550are handled as built-in functions 9551except in strict ISO C90 mode (@option{-ansi} or @option{-std=c90}). 9552 9553The ISO C90 functions 9554@code{abort}, @code{abs}, @code{acos}, @code{asin}, @code{atan2}, 9555@code{atan}, @code{calloc}, @code{ceil}, @code{cosh}, @code{cos}, 9556@code{exit}, @code{exp}, @code{fabs}, @code{floor}, @code{fmod}, 9557@code{fprintf}, @code{fputs}, @code{frexp}, @code{fscanf}, 9558@code{isalnum}, @code{isalpha}, @code{iscntrl}, @code{isdigit}, 9559@code{isgraph}, @code{islower}, @code{isprint}, @code{ispunct}, 9560@code{isspace}, @code{isupper}, @code{isxdigit}, @code{tolower}, 9561@code{toupper}, @code{labs}, @code{ldexp}, @code{log10}, @code{log}, 9562@code{malloc}, @code{memchr}, @code{memcmp}, @code{memcpy}, 9563@code{memset}, @code{modf}, @code{pow}, @code{printf}, @code{putchar}, 9564@code{puts}, @code{scanf}, @code{sinh}, @code{sin}, @code{snprintf}, 9565@code{sprintf}, @code{sqrt}, @code{sscanf}, @code{strcat}, 9566@code{strchr}, @code{strcmp}, @code{strcpy}, @code{strcspn}, 9567@code{strlen}, @code{strncat}, @code{strncmp}, @code{strncpy}, 9568@code{strpbrk}, @code{strrchr}, @code{strspn}, @code{strstr}, 9569@code{tanh}, @code{tan}, @code{vfprintf}, @code{vprintf} and @code{vsprintf} 9570are all recognized as built-in functions unless 9571@option{-fno-builtin} is specified (or @option{-fno-builtin-@var{function}} 9572is specified for an individual function). All of these functions have 9573corresponding versions prefixed with @code{__builtin_}. 9574 9575GCC provides built-in versions of the ISO C99 floating-point comparison 9576macros that avoid raising exceptions for unordered operands. They have 9577the same names as the standard macros ( @code{isgreater}, 9578@code{isgreaterequal}, @code{isless}, @code{islessequal}, 9579@code{islessgreater}, and @code{isunordered}) , with @code{__builtin_} 9580prefixed. We intend for a library implementor to be able to simply 9581@code{#define} each standard macro to its built-in equivalent. 9582In the same fashion, GCC provides @code{fpclassify}, @code{isfinite}, 9583@code{isinf_sign} and @code{isnormal} built-ins used with 9584@code{__builtin_} prefixed. The @code{isinf} and @code{isnan} 9585built-in functions appear both with and without the @code{__builtin_} prefix. 9586 9587@deftypefn {Built-in Function} int __builtin_types_compatible_p (@var{type1}, @var{type2}) 9588 9589You can use the built-in function @code{__builtin_types_compatible_p} to 9590determine whether two types are the same. 9591 9592This built-in function returns 1 if the unqualified versions of the 9593types @var{type1} and @var{type2} (which are types, not expressions) are 9594compatible, 0 otherwise. The result of this built-in function can be 9595used in integer constant expressions. 9596 9597This built-in function ignores top level qualifiers (e.g., @code{const}, 9598@code{volatile}). For example, @code{int} is equivalent to @code{const 9599int}. 9600 9601The type @code{int[]} and @code{int[5]} are compatible. On the other 9602hand, @code{int} and @code{char *} are not compatible, even if the size 9603of their types, on the particular architecture are the same. Also, the 9604amount of pointer indirection is taken into account when determining 9605similarity. Consequently, @code{short *} is not similar to 9606@code{short **}. Furthermore, two types that are typedefed are 9607considered compatible if their underlying types are compatible. 9608 9609An @code{enum} type is not considered to be compatible with another 9610@code{enum} type even if both are compatible with the same integer 9611type; this is what the C standard specifies. 9612For example, @code{enum @{foo, bar@}} is not similar to 9613@code{enum @{hot, dog@}}. 9614 9615You typically use this function in code whose execution varies 9616depending on the arguments' types. For example: 9617 9618@smallexample 9619#define foo(x) \ 9620 (@{ \ 9621 typeof (x) tmp = (x); \ 9622 if (__builtin_types_compatible_p (typeof (x), long double)) \ 9623 tmp = foo_long_double (tmp); \ 9624 else if (__builtin_types_compatible_p (typeof (x), double)) \ 9625 tmp = foo_double (tmp); \ 9626 else if (__builtin_types_compatible_p (typeof (x), float)) \ 9627 tmp = foo_float (tmp); \ 9628 else \ 9629 abort (); \ 9630 tmp; \ 9631 @}) 9632@end smallexample 9633 9634@emph{Note:} This construct is only available for C@. 9635 9636@end deftypefn 9637 9638@deftypefn {Built-in Function} @var{type} __builtin_call_with_static_chain (@var{call_exp}, @var{pointer_exp}) 9639 9640The @var{call_exp} expression must be a function call, and the 9641@var{pointer_exp} expression must be a pointer. The @var{pointer_exp} 9642is passed to the function call in the target's static chain location. 9643The result of builtin is the result of the function call. 9644 9645@emph{Note:} This builtin is only available for C@. 9646This builtin can be used to call Go closures from C. 9647 9648@end deftypefn 9649 9650@deftypefn {Built-in Function} @var{type} __builtin_choose_expr (@var{const_exp}, @var{exp1}, @var{exp2}) 9651 9652You can use the built-in function @code{__builtin_choose_expr} to 9653evaluate code depending on the value of a constant expression. This 9654built-in function returns @var{exp1} if @var{const_exp}, which is an 9655integer constant expression, is nonzero. Otherwise it returns @var{exp2}. 9656 9657This built-in function is analogous to the @samp{? :} operator in C, 9658except that the expression returned has its type unaltered by promotion 9659rules. Also, the built-in function does not evaluate the expression 9660that is not chosen. For example, if @var{const_exp} evaluates to true, 9661@var{exp2} is not evaluated even if it has side-effects. 9662 9663This built-in function can return an lvalue if the chosen argument is an 9664lvalue. 9665 9666If @var{exp1} is returned, the return type is the same as @var{exp1}'s 9667type. Similarly, if @var{exp2} is returned, its return type is the same 9668as @var{exp2}. 9669 9670Example: 9671 9672@smallexample 9673#define foo(x) \ 9674 __builtin_choose_expr ( \ 9675 __builtin_types_compatible_p (typeof (x), double), \ 9676 foo_double (x), \ 9677 __builtin_choose_expr ( \ 9678 __builtin_types_compatible_p (typeof (x), float), \ 9679 foo_float (x), \ 9680 /* @r{The void expression results in a compile-time error} \ 9681 @r{when assigning the result to something.} */ \ 9682 (void)0)) 9683@end smallexample 9684 9685@emph{Note:} This construct is only available for C@. Furthermore, the 9686unused expression (@var{exp1} or @var{exp2} depending on the value of 9687@var{const_exp}) may still generate syntax errors. This may change in 9688future revisions. 9689 9690@end deftypefn 9691 9692@deftypefn {Built-in Function} @var{type} __builtin_complex (@var{real}, @var{imag}) 9693 9694The built-in function @code{__builtin_complex} is provided for use in 9695implementing the ISO C11 macros @code{CMPLXF}, @code{CMPLX} and 9696@code{CMPLXL}. @var{real} and @var{imag} must have the same type, a 9697real binary floating-point type, and the result has the corresponding 9698complex type with real and imaginary parts @var{real} and @var{imag}. 9699Unlike @samp{@var{real} + I * @var{imag}}, this works even when 9700infinities, NaNs and negative zeros are involved. 9701 9702@end deftypefn 9703 9704@deftypefn {Built-in Function} int __builtin_constant_p (@var{exp}) 9705You can use the built-in function @code{__builtin_constant_p} to 9706determine if a value is known to be constant at compile time and hence 9707that GCC can perform constant-folding on expressions involving that 9708value. The argument of the function is the value to test. The function 9709returns the integer 1 if the argument is known to be a compile-time 9710constant and 0 if it is not known to be a compile-time constant. A 9711return of 0 does not indicate that the value is @emph{not} a constant, 9712but merely that GCC cannot prove it is a constant with the specified 9713value of the @option{-O} option. 9714 9715You typically use this function in an embedded application where 9716memory is a critical resource. If you have some complex calculation, 9717you may want it to be folded if it involves constants, but need to call 9718a function if it does not. For example: 9719 9720@smallexample 9721#define Scale_Value(X) \ 9722 (__builtin_constant_p (X) \ 9723 ? ((X) * SCALE + OFFSET) : Scale (X)) 9724@end smallexample 9725 9726You may use this built-in function in either a macro or an inline 9727function. However, if you use it in an inlined function and pass an 9728argument of the function as the argument to the built-in, GCC 9729never returns 1 when you call the inline function with a string constant 9730or compound literal (@pxref{Compound Literals}) and does not return 1 9731when you pass a constant numeric value to the inline function unless you 9732specify the @option{-O} option. 9733 9734You may also use @code{__builtin_constant_p} in initializers for static 9735data. For instance, you can write 9736 9737@smallexample 9738static const int table[] = @{ 9739 __builtin_constant_p (EXPRESSION) ? (EXPRESSION) : -1, 9740 /* @r{@dots{}} */ 9741@}; 9742@end smallexample 9743 9744@noindent 9745This is an acceptable initializer even if @var{EXPRESSION} is not a 9746constant expression, including the case where 9747@code{__builtin_constant_p} returns 1 because @var{EXPRESSION} can be 9748folded to a constant but @var{EXPRESSION} contains operands that are 9749not otherwise permitted in a static initializer (for example, 9750@code{0 && foo ()}). GCC must be more conservative about evaluating the 9751built-in in this case, because it has no opportunity to perform 9752optimization. 9753@end deftypefn 9754 9755@deftypefn {Built-in Function} long __builtin_expect (long @var{exp}, long @var{c}) 9756@opindex fprofile-arcs 9757You may use @code{__builtin_expect} to provide the compiler with 9758branch prediction information. In general, you should prefer to 9759use actual profile feedback for this (@option{-fprofile-arcs}), as 9760programmers are notoriously bad at predicting how their programs 9761actually perform. However, there are applications in which this 9762data is hard to collect. 9763 9764The return value is the value of @var{exp}, which should be an integral 9765expression. The semantics of the built-in are that it is expected that 9766@var{exp} == @var{c}. For example: 9767 9768@smallexample 9769if (__builtin_expect (x, 0)) 9770 foo (); 9771@end smallexample 9772 9773@noindent 9774indicates that we do not expect to call @code{foo}, since 9775we expect @code{x} to be zero. Since you are limited to integral 9776expressions for @var{exp}, you should use constructions such as 9777 9778@smallexample 9779if (__builtin_expect (ptr != NULL, 1)) 9780 foo (*ptr); 9781@end smallexample 9782 9783@noindent 9784when testing pointer or floating-point values. 9785@end deftypefn 9786 9787@deftypefn {Built-in Function} void __builtin_trap (void) 9788This function causes the program to exit abnormally. GCC implements 9789this function by using a target-dependent mechanism (such as 9790intentionally executing an illegal instruction) or by calling 9791@code{abort}. The mechanism used may vary from release to release so 9792you should not rely on any particular implementation. 9793@end deftypefn 9794 9795@deftypefn {Built-in Function} void __builtin_unreachable (void) 9796If control flow reaches the point of the @code{__builtin_unreachable}, 9797the program is undefined. It is useful in situations where the 9798compiler cannot deduce the unreachability of the code. 9799 9800One such case is immediately following an @code{asm} statement that 9801either never terminates, or one that transfers control elsewhere 9802and never returns. In this example, without the 9803@code{__builtin_unreachable}, GCC issues a warning that control 9804reaches the end of a non-void function. It also generates code 9805to return after the @code{asm}. 9806 9807@smallexample 9808int f (int c, int v) 9809@{ 9810 if (c) 9811 @{ 9812 return v; 9813 @} 9814 else 9815 @{ 9816 asm("jmp error_handler"); 9817 __builtin_unreachable (); 9818 @} 9819@} 9820@end smallexample 9821 9822@noindent 9823Because the @code{asm} statement unconditionally transfers control out 9824of the function, control never reaches the end of the function 9825body. The @code{__builtin_unreachable} is in fact unreachable and 9826communicates this fact to the compiler. 9827 9828Another use for @code{__builtin_unreachable} is following a call a 9829function that never returns but that is not declared 9830@code{__attribute__((noreturn))}, as in this example: 9831 9832@smallexample 9833void function_that_never_returns (void); 9834 9835int g (int c) 9836@{ 9837 if (c) 9838 @{ 9839 return 1; 9840 @} 9841 else 9842 @{ 9843 function_that_never_returns (); 9844 __builtin_unreachable (); 9845 @} 9846@} 9847@end smallexample 9848 9849@end deftypefn 9850 9851@deftypefn {Built-in Function} void *__builtin_assume_aligned (const void *@var{exp}, size_t @var{align}, ...) 9852This function returns its first argument, and allows the compiler 9853to assume that the returned pointer is at least @var{align} bytes 9854aligned. This built-in can have either two or three arguments, 9855if it has three, the third argument should have integer type, and 9856if it is nonzero means misalignment offset. For example: 9857 9858@smallexample 9859void *x = __builtin_assume_aligned (arg, 16); 9860@end smallexample 9861 9862@noindent 9863means that the compiler can assume @code{x}, set to @code{arg}, is at least 986416-byte aligned, while: 9865 9866@smallexample 9867void *x = __builtin_assume_aligned (arg, 32, 8); 9868@end smallexample 9869 9870@noindent 9871means that the compiler can assume for @code{x}, set to @code{arg}, that 9872@code{(char *) x - 8} is 32-byte aligned. 9873@end deftypefn 9874 9875@deftypefn {Built-in Function} int __builtin_LINE () 9876This function is the equivalent to the preprocessor @code{__LINE__} 9877macro and returns the line number of the invocation of the built-in. 9878In a C++ default argument for a function @var{F}, it gets the line number of 9879the call to @var{F}. 9880@end deftypefn 9881 9882@deftypefn {Built-in Function} {const char *} __builtin_FUNCTION () 9883This function is the equivalent to the preprocessor @code{__FUNCTION__} 9884macro and returns the function name the invocation of the built-in is in. 9885@end deftypefn 9886 9887@deftypefn {Built-in Function} {const char *} __builtin_FILE () 9888This function is the equivalent to the preprocessor @code{__FILE__} 9889macro and returns the file name the invocation of the built-in is in. 9890In a C++ default argument for a function @var{F}, it gets the file name of 9891the call to @var{F}. 9892@end deftypefn 9893 9894@deftypefn {Built-in Function} void __builtin___clear_cache (char *@var{begin}, char *@var{end}) 9895This function is used to flush the processor's instruction cache for 9896the region of memory between @var{begin} inclusive and @var{end} 9897exclusive. Some targets require that the instruction cache be 9898flushed, after modifying memory containing code, in order to obtain 9899deterministic behavior. 9900 9901If the target does not require instruction cache flushes, 9902@code{__builtin___clear_cache} has no effect. Otherwise either 9903instructions are emitted in-line to clear the instruction cache or a 9904call to the @code{__clear_cache} function in libgcc is made. 9905@end deftypefn 9906 9907@deftypefn {Built-in Function} void __builtin_prefetch (const void *@var{addr}, ...) 9908This function is used to minimize cache-miss latency by moving data into 9909a cache before it is accessed. 9910You can insert calls to @code{__builtin_prefetch} into code for which 9911you know addresses of data in memory that is likely to be accessed soon. 9912If the target supports them, data prefetch instructions are generated. 9913If the prefetch is done early enough before the access then the data will 9914be in the cache by the time it is accessed. 9915 9916The value of @var{addr} is the address of the memory to prefetch. 9917There are two optional arguments, @var{rw} and @var{locality}. 9918The value of @var{rw} is a compile-time constant one or zero; one 9919means that the prefetch is preparing for a write to the memory address 9920and zero, the default, means that the prefetch is preparing for a read. 9921The value @var{locality} must be a compile-time constant integer between 9922zero and three. A value of zero means that the data has no temporal 9923locality, so it need not be left in the cache after the access. A value 9924of three means that the data has a high degree of temporal locality and 9925should be left in all levels of cache possible. Values of one and two 9926mean, respectively, a low or moderate degree of temporal locality. The 9927default is three. 9928 9929@smallexample 9930for (i = 0; i < n; i++) 9931 @{ 9932 a[i] = a[i] + b[i]; 9933 __builtin_prefetch (&a[i+j], 1, 1); 9934 __builtin_prefetch (&b[i+j], 0, 1); 9935 /* @r{@dots{}} */ 9936 @} 9937@end smallexample 9938 9939Data prefetch does not generate faults if @var{addr} is invalid, but 9940the address expression itself must be valid. For example, a prefetch 9941of @code{p->next} does not fault if @code{p->next} is not a valid 9942address, but evaluation faults if @code{p} is not a valid address. 9943 9944If the target does not support data prefetch, the address expression 9945is evaluated if it includes side effects but no other code is generated 9946and GCC does not issue a warning. 9947@end deftypefn 9948 9949@deftypefn {Built-in Function} double __builtin_huge_val (void) 9950Returns a positive infinity, if supported by the floating-point format, 9951else @code{DBL_MAX}. This function is suitable for implementing the 9952ISO C macro @code{HUGE_VAL}. 9953@end deftypefn 9954 9955@deftypefn {Built-in Function} float __builtin_huge_valf (void) 9956Similar to @code{__builtin_huge_val}, except the return type is @code{float}. 9957@end deftypefn 9958 9959@deftypefn {Built-in Function} {long double} __builtin_huge_vall (void) 9960Similar to @code{__builtin_huge_val}, except the return 9961type is @code{long double}. 9962@end deftypefn 9963 9964@deftypefn {Built-in Function} int __builtin_fpclassify (int, int, int, int, int, ...) 9965This built-in implements the C99 fpclassify functionality. The first 9966five int arguments should be the target library's notion of the 9967possible FP classes and are used for return values. They must be 9968constant values and they must appear in this order: @code{FP_NAN}, 9969@code{FP_INFINITE}, @code{FP_NORMAL}, @code{FP_SUBNORMAL} and 9970@code{FP_ZERO}. The ellipsis is for exactly one floating-point value 9971to classify. GCC treats the last argument as type-generic, which 9972means it does not do default promotion from float to double. 9973@end deftypefn 9974 9975@deftypefn {Built-in Function} double __builtin_inf (void) 9976Similar to @code{__builtin_huge_val}, except a warning is generated 9977if the target floating-point format does not support infinities. 9978@end deftypefn 9979 9980@deftypefn {Built-in Function} _Decimal32 __builtin_infd32 (void) 9981Similar to @code{__builtin_inf}, except the return type is @code{_Decimal32}. 9982@end deftypefn 9983 9984@deftypefn {Built-in Function} _Decimal64 __builtin_infd64 (void) 9985Similar to @code{__builtin_inf}, except the return type is @code{_Decimal64}. 9986@end deftypefn 9987 9988@deftypefn {Built-in Function} _Decimal128 __builtin_infd128 (void) 9989Similar to @code{__builtin_inf}, except the return type is @code{_Decimal128}. 9990@end deftypefn 9991 9992@deftypefn {Built-in Function} float __builtin_inff (void) 9993Similar to @code{__builtin_inf}, except the return type is @code{float}. 9994This function is suitable for implementing the ISO C99 macro @code{INFINITY}. 9995@end deftypefn 9996 9997@deftypefn {Built-in Function} {long double} __builtin_infl (void) 9998Similar to @code{__builtin_inf}, except the return 9999type is @code{long double}. 10000@end deftypefn 10001 10002@deftypefn {Built-in Function} int __builtin_isinf_sign (...) 10003Similar to @code{isinf}, except the return value is -1 for 10004an argument of @code{-Inf} and 1 for an argument of @code{+Inf}. 10005Note while the parameter list is an 10006ellipsis, this function only accepts exactly one floating-point 10007argument. GCC treats this parameter as type-generic, which means it 10008does not do default promotion from float to double. 10009@end deftypefn 10010 10011@deftypefn {Built-in Function} double __builtin_nan (const char *str) 10012This is an implementation of the ISO C99 function @code{nan}. 10013 10014Since ISO C99 defines this function in terms of @code{strtod}, which we 10015do not implement, a description of the parsing is in order. The string 10016is parsed as by @code{strtol}; that is, the base is recognized by 10017leading @samp{0} or @samp{0x} prefixes. The number parsed is placed 10018in the significand such that the least significant bit of the number 10019is at the least significant bit of the significand. The number is 10020truncated to fit the significand field provided. The significand is 10021forced to be a quiet NaN@. 10022 10023This function, if given a string literal all of which would have been 10024consumed by @code{strtol}, is evaluated early enough that it is considered a 10025compile-time constant. 10026@end deftypefn 10027 10028@deftypefn {Built-in Function} _Decimal32 __builtin_nand32 (const char *str) 10029Similar to @code{__builtin_nan}, except the return type is @code{_Decimal32}. 10030@end deftypefn 10031 10032@deftypefn {Built-in Function} _Decimal64 __builtin_nand64 (const char *str) 10033Similar to @code{__builtin_nan}, except the return type is @code{_Decimal64}. 10034@end deftypefn 10035 10036@deftypefn {Built-in Function} _Decimal128 __builtin_nand128 (const char *str) 10037Similar to @code{__builtin_nan}, except the return type is @code{_Decimal128}. 10038@end deftypefn 10039 10040@deftypefn {Built-in Function} float __builtin_nanf (const char *str) 10041Similar to @code{__builtin_nan}, except the return type is @code{float}. 10042@end deftypefn 10043 10044@deftypefn {Built-in Function} {long double} __builtin_nanl (const char *str) 10045Similar to @code{__builtin_nan}, except the return type is @code{long double}. 10046@end deftypefn 10047 10048@deftypefn {Built-in Function} double __builtin_nans (const char *str) 10049Similar to @code{__builtin_nan}, except the significand is forced 10050to be a signaling NaN@. The @code{nans} function is proposed by 10051@uref{http://www.open-std.org/jtc1/sc22/wg14/www/docs/n965.htm,,WG14 N965}. 10052@end deftypefn 10053 10054@deftypefn {Built-in Function} float __builtin_nansf (const char *str) 10055Similar to @code{__builtin_nans}, except the return type is @code{float}. 10056@end deftypefn 10057 10058@deftypefn {Built-in Function} {long double} __builtin_nansl (const char *str) 10059Similar to @code{__builtin_nans}, except the return type is @code{long double}. 10060@end deftypefn 10061 10062@deftypefn {Built-in Function} int __builtin_ffs (int x) 10063Returns one plus the index of the least significant 1-bit of @var{x}, or 10064if @var{x} is zero, returns zero. 10065@end deftypefn 10066 10067@deftypefn {Built-in Function} int __builtin_clz (unsigned int x) 10068Returns the number of leading 0-bits in @var{x}, starting at the most 10069significant bit position. If @var{x} is 0, the result is undefined. 10070@end deftypefn 10071 10072@deftypefn {Built-in Function} int __builtin_ctz (unsigned int x) 10073Returns the number of trailing 0-bits in @var{x}, starting at the least 10074significant bit position. If @var{x} is 0, the result is undefined. 10075@end deftypefn 10076 10077@deftypefn {Built-in Function} int __builtin_clrsb (int x) 10078Returns the number of leading redundant sign bits in @var{x}, i.e.@: the 10079number of bits following the most significant bit that are identical 10080to it. There are no special cases for 0 or other values. 10081@end deftypefn 10082 10083@deftypefn {Built-in Function} int __builtin_popcount (unsigned int x) 10084Returns the number of 1-bits in @var{x}. 10085@end deftypefn 10086 10087@deftypefn {Built-in Function} int __builtin_parity (unsigned int x) 10088Returns the parity of @var{x}, i.e.@: the number of 1-bits in @var{x} 10089modulo 2. 10090@end deftypefn 10091 10092@deftypefn {Built-in Function} int __builtin_ffsl (long) 10093Similar to @code{__builtin_ffs}, except the argument type is 10094@code{long}. 10095@end deftypefn 10096 10097@deftypefn {Built-in Function} int __builtin_clzl (unsigned long) 10098Similar to @code{__builtin_clz}, except the argument type is 10099@code{unsigned long}. 10100@end deftypefn 10101 10102@deftypefn {Built-in Function} int __builtin_ctzl (unsigned long) 10103Similar to @code{__builtin_ctz}, except the argument type is 10104@code{unsigned long}. 10105@end deftypefn 10106 10107@deftypefn {Built-in Function} int __builtin_clrsbl (long) 10108Similar to @code{__builtin_clrsb}, except the argument type is 10109@code{long}. 10110@end deftypefn 10111 10112@deftypefn {Built-in Function} int __builtin_popcountl (unsigned long) 10113Similar to @code{__builtin_popcount}, except the argument type is 10114@code{unsigned long}. 10115@end deftypefn 10116 10117@deftypefn {Built-in Function} int __builtin_parityl (unsigned long) 10118Similar to @code{__builtin_parity}, except the argument type is 10119@code{unsigned long}. 10120@end deftypefn 10121 10122@deftypefn {Built-in Function} int __builtin_ffsll (long long) 10123Similar to @code{__builtin_ffs}, except the argument type is 10124@code{long long}. 10125@end deftypefn 10126 10127@deftypefn {Built-in Function} int __builtin_clzll (unsigned long long) 10128Similar to @code{__builtin_clz}, except the argument type is 10129@code{unsigned long long}. 10130@end deftypefn 10131 10132@deftypefn {Built-in Function} int __builtin_ctzll (unsigned long long) 10133Similar to @code{__builtin_ctz}, except the argument type is 10134@code{unsigned long long}. 10135@end deftypefn 10136 10137@deftypefn {Built-in Function} int __builtin_clrsbll (long long) 10138Similar to @code{__builtin_clrsb}, except the argument type is 10139@code{long long}. 10140@end deftypefn 10141 10142@deftypefn {Built-in Function} int __builtin_popcountll (unsigned long long) 10143Similar to @code{__builtin_popcount}, except the argument type is 10144@code{unsigned long long}. 10145@end deftypefn 10146 10147@deftypefn {Built-in Function} int __builtin_parityll (unsigned long long) 10148Similar to @code{__builtin_parity}, except the argument type is 10149@code{unsigned long long}. 10150@end deftypefn 10151 10152@deftypefn {Built-in Function} double __builtin_powi (double, int) 10153Returns the first argument raised to the power of the second. Unlike the 10154@code{pow} function no guarantees about precision and rounding are made. 10155@end deftypefn 10156 10157@deftypefn {Built-in Function} float __builtin_powif (float, int) 10158Similar to @code{__builtin_powi}, except the argument and return types 10159are @code{float}. 10160@end deftypefn 10161 10162@deftypefn {Built-in Function} {long double} __builtin_powil (long double, int) 10163Similar to @code{__builtin_powi}, except the argument and return types 10164are @code{long double}. 10165@end deftypefn 10166 10167@deftypefn {Built-in Function} uint16_t __builtin_bswap16 (uint16_t x) 10168Returns @var{x} with the order of the bytes reversed; for example, 10169@code{0xaabb} becomes @code{0xbbaa}. Byte here always means 10170exactly 8 bits. 10171@end deftypefn 10172 10173@deftypefn {Built-in Function} uint32_t __builtin_bswap32 (uint32_t x) 10174Similar to @code{__builtin_bswap16}, except the argument and return types 10175are 32 bit. 10176@end deftypefn 10177 10178@deftypefn {Built-in Function} uint64_t __builtin_bswap64 (uint64_t x) 10179Similar to @code{__builtin_bswap32}, except the argument and return types 10180are 64 bit. 10181@end deftypefn 10182 10183@node Target Builtins 10184@section Built-in Functions Specific to Particular Target Machines 10185 10186On some target machines, GCC supports many built-in functions specific 10187to those machines. Generally these generate calls to specific machine 10188instructions, but allow the compiler to schedule those calls. 10189 10190@menu 10191* AArch64 Built-in Functions:: 10192* Alpha Built-in Functions:: 10193* Altera Nios II Built-in Functions:: 10194* ARC Built-in Functions:: 10195* ARC SIMD Built-in Functions:: 10196* ARM iWMMXt Built-in Functions:: 10197* ARM C Language Extensions (ACLE):: 10198* ARM Floating Point Status and Control Intrinsics:: 10199* AVR Built-in Functions:: 10200* Blackfin Built-in Functions:: 10201* FR-V Built-in Functions:: 10202* MIPS DSP Built-in Functions:: 10203* MIPS Paired-Single Support:: 10204* MIPS Loongson Built-in Functions:: 10205* Other MIPS Built-in Functions:: 10206* MSP430 Built-in Functions:: 10207* NDS32 Built-in Functions:: 10208* picoChip Built-in Functions:: 10209* PowerPC Built-in Functions:: 10210* PowerPC AltiVec/VSX Built-in Functions:: 10211* PowerPC Hardware Transactional Memory Built-in Functions:: 10212* RX Built-in Functions:: 10213* S/390 System z Built-in Functions:: 10214* SH Built-in Functions:: 10215* SPARC VIS Built-in Functions:: 10216* SPU Built-in Functions:: 10217* TI C6X Built-in Functions:: 10218* TILE-Gx Built-in Functions:: 10219* TILEPro Built-in Functions:: 10220* x86 Built-in Functions:: 10221* x86 transactional memory intrinsics:: 10222@end menu 10223 10224@node AArch64 Built-in Functions 10225@subsection AArch64 Built-in Functions 10226 10227These built-in functions are available for the AArch64 family of 10228processors. 10229@smallexample 10230unsigned int __builtin_aarch64_get_fpcr () 10231void __builtin_aarch64_set_fpcr (unsigned int) 10232unsigned int __builtin_aarch64_get_fpsr () 10233void __builtin_aarch64_set_fpsr (unsigned int) 10234@end smallexample 10235 10236@node Alpha Built-in Functions 10237@subsection Alpha Built-in Functions 10238 10239These built-in functions are available for the Alpha family of 10240processors, depending on the command-line switches used. 10241 10242The following built-in functions are always available. They 10243all generate the machine instruction that is part of the name. 10244 10245@smallexample 10246long __builtin_alpha_implver (void) 10247long __builtin_alpha_rpcc (void) 10248long __builtin_alpha_amask (long) 10249long __builtin_alpha_cmpbge (long, long) 10250long __builtin_alpha_extbl (long, long) 10251long __builtin_alpha_extwl (long, long) 10252long __builtin_alpha_extll (long, long) 10253long __builtin_alpha_extql (long, long) 10254long __builtin_alpha_extwh (long, long) 10255long __builtin_alpha_extlh (long, long) 10256long __builtin_alpha_extqh (long, long) 10257long __builtin_alpha_insbl (long, long) 10258long __builtin_alpha_inswl (long, long) 10259long __builtin_alpha_insll (long, long) 10260long __builtin_alpha_insql (long, long) 10261long __builtin_alpha_inswh (long, long) 10262long __builtin_alpha_inslh (long, long) 10263long __builtin_alpha_insqh (long, long) 10264long __builtin_alpha_mskbl (long, long) 10265long __builtin_alpha_mskwl (long, long) 10266long __builtin_alpha_mskll (long, long) 10267long __builtin_alpha_mskql (long, long) 10268long __builtin_alpha_mskwh (long, long) 10269long __builtin_alpha_msklh (long, long) 10270long __builtin_alpha_mskqh (long, long) 10271long __builtin_alpha_umulh (long, long) 10272long __builtin_alpha_zap (long, long) 10273long __builtin_alpha_zapnot (long, long) 10274@end smallexample 10275 10276The following built-in functions are always with @option{-mmax} 10277or @option{-mcpu=@var{cpu}} where @var{cpu} is @code{pca56} or 10278later. They all generate the machine instruction that is part 10279of the name. 10280 10281@smallexample 10282long __builtin_alpha_pklb (long) 10283long __builtin_alpha_pkwb (long) 10284long __builtin_alpha_unpkbl (long) 10285long __builtin_alpha_unpkbw (long) 10286long __builtin_alpha_minub8 (long, long) 10287long __builtin_alpha_minsb8 (long, long) 10288long __builtin_alpha_minuw4 (long, long) 10289long __builtin_alpha_minsw4 (long, long) 10290long __builtin_alpha_maxub8 (long, long) 10291long __builtin_alpha_maxsb8 (long, long) 10292long __builtin_alpha_maxuw4 (long, long) 10293long __builtin_alpha_maxsw4 (long, long) 10294long __builtin_alpha_perr (long, long) 10295@end smallexample 10296 10297The following built-in functions are always with @option{-mcix} 10298or @option{-mcpu=@var{cpu}} where @var{cpu} is @code{ev67} or 10299later. They all generate the machine instruction that is part 10300of the name. 10301 10302@smallexample 10303long __builtin_alpha_cttz (long) 10304long __builtin_alpha_ctlz (long) 10305long __builtin_alpha_ctpop (long) 10306@end smallexample 10307 10308The following built-in functions are available on systems that use the OSF/1 10309PALcode. Normally they invoke the @code{rduniq} and @code{wruniq} 10310PAL calls, but when invoked with @option{-mtls-kernel}, they invoke 10311@code{rdval} and @code{wrval}. 10312 10313@smallexample 10314void *__builtin_thread_pointer (void) 10315void __builtin_set_thread_pointer (void *) 10316@end smallexample 10317 10318@node Altera Nios II Built-in Functions 10319@subsection Altera Nios II Built-in Functions 10320 10321These built-in functions are available for the Altera Nios II 10322family of processors. 10323 10324The following built-in functions are always available. They 10325all generate the machine instruction that is part of the name. 10326 10327@example 10328int __builtin_ldbio (volatile const void *) 10329int __builtin_ldbuio (volatile const void *) 10330int __builtin_ldhio (volatile const void *) 10331int __builtin_ldhuio (volatile const void *) 10332int __builtin_ldwio (volatile const void *) 10333void __builtin_stbio (volatile void *, int) 10334void __builtin_sthio (volatile void *, int) 10335void __builtin_stwio (volatile void *, int) 10336void __builtin_sync (void) 10337int __builtin_rdctl (int) 10338void __builtin_wrctl (int, int) 10339@end example 10340 10341The following built-in functions are always available. They 10342all generate a Nios II Custom Instruction. The name of the 10343function represents the types that the function takes and 10344returns. The letter before the @code{n} is the return type 10345or void if absent. The @code{n} represents the first parameter 10346to all the custom instructions, the custom instruction number. 10347The two letters after the @code{n} represent the up to two 10348parameters to the function. 10349 10350The letters represent the following data types: 10351@table @code 10352@item <no letter> 10353@code{void} for return type and no parameter for parameter types. 10354 10355@item i 10356@code{int} for return type and parameter type 10357 10358@item f 10359@code{float} for return type and parameter type 10360 10361@item p 10362@code{void *} for return type and parameter type 10363 10364@end table 10365 10366And the function names are: 10367@example 10368void __builtin_custom_n (void) 10369void __builtin_custom_ni (int) 10370void __builtin_custom_nf (float) 10371void __builtin_custom_np (void *) 10372void __builtin_custom_nii (int, int) 10373void __builtin_custom_nif (int, float) 10374void __builtin_custom_nip (int, void *) 10375void __builtin_custom_nfi (float, int) 10376void __builtin_custom_nff (float, float) 10377void __builtin_custom_nfp (float, void *) 10378void __builtin_custom_npi (void *, int) 10379void __builtin_custom_npf (void *, float) 10380void __builtin_custom_npp (void *, void *) 10381int __builtin_custom_in (void) 10382int __builtin_custom_ini (int) 10383int __builtin_custom_inf (float) 10384int __builtin_custom_inp (void *) 10385int __builtin_custom_inii (int, int) 10386int __builtin_custom_inif (int, float) 10387int __builtin_custom_inip (int, void *) 10388int __builtin_custom_infi (float, int) 10389int __builtin_custom_inff (float, float) 10390int __builtin_custom_infp (float, void *) 10391int __builtin_custom_inpi (void *, int) 10392int __builtin_custom_inpf (void *, float) 10393int __builtin_custom_inpp (void *, void *) 10394float __builtin_custom_fn (void) 10395float __builtin_custom_fni (int) 10396float __builtin_custom_fnf (float) 10397float __builtin_custom_fnp (void *) 10398float __builtin_custom_fnii (int, int) 10399float __builtin_custom_fnif (int, float) 10400float __builtin_custom_fnip (int, void *) 10401float __builtin_custom_fnfi (float, int) 10402float __builtin_custom_fnff (float, float) 10403float __builtin_custom_fnfp (float, void *) 10404float __builtin_custom_fnpi (void *, int) 10405float __builtin_custom_fnpf (void *, float) 10406float __builtin_custom_fnpp (void *, void *) 10407void * __builtin_custom_pn (void) 10408void * __builtin_custom_pni (int) 10409void * __builtin_custom_pnf (float) 10410void * __builtin_custom_pnp (void *) 10411void * __builtin_custom_pnii (int, int) 10412void * __builtin_custom_pnif (int, float) 10413void * __builtin_custom_pnip (int, void *) 10414void * __builtin_custom_pnfi (float, int) 10415void * __builtin_custom_pnff (float, float) 10416void * __builtin_custom_pnfp (float, void *) 10417void * __builtin_custom_pnpi (void *, int) 10418void * __builtin_custom_pnpf (void *, float) 10419void * __builtin_custom_pnpp (void *, void *) 10420@end example 10421 10422@node ARC Built-in Functions 10423@subsection ARC Built-in Functions 10424 10425The following built-in functions are provided for ARC targets. The 10426built-ins generate the corresponding assembly instructions. In the 10427examples given below, the generated code often requires an operand or 10428result to be in a register. Where necessary further code will be 10429generated to ensure this is true, but for brevity this is not 10430described in each case. 10431 10432@emph{Note:} Using a built-in to generate an instruction not supported 10433by a target may cause problems. At present the compiler is not 10434guaranteed to detect such misuse, and as a result an internal compiler 10435error may be generated. 10436 10437@deftypefn {Built-in Function} int __builtin_arc_aligned (void *@var{val}, int @var{alignval}) 10438Return 1 if @var{val} is known to have the byte alignment given 10439by @var{alignval}, otherwise return 0. 10440Note that this is different from 10441@smallexample 10442__alignof__(*(char *)@var{val}) >= alignval 10443@end smallexample 10444because __alignof__ sees only the type of the dereference, whereas 10445__builtin_arc_align uses alignment information from the pointer 10446as well as from the pointed-to type. 10447The information available will depend on optimization level. 10448@end deftypefn 10449 10450@deftypefn {Built-in Function} void __builtin_arc_brk (void) 10451Generates 10452@example 10453brk 10454@end example 10455@end deftypefn 10456 10457@deftypefn {Built-in Function} {unsigned int} __builtin_arc_core_read (unsigned int @var{regno}) 10458The operand is the number of a register to be read. Generates: 10459@example 10460mov @var{dest}, r@var{regno} 10461@end example 10462where the value in @var{dest} will be the result returned from the 10463built-in. 10464@end deftypefn 10465 10466@deftypefn {Built-in Function} void __builtin_arc_core_write (unsigned int @var{regno}, unsigned int @var{val}) 10467The first operand is the number of a register to be written, the 10468second operand is a compile time constant to write into that 10469register. Generates: 10470@example 10471mov r@var{regno}, @var{val} 10472@end example 10473@end deftypefn 10474 10475@deftypefn {Built-in Function} int __builtin_arc_divaw (int @var{a}, int @var{b}) 10476Only available if either @option{-mcpu=ARC700} or @option{-meA} is set. 10477Generates: 10478@example 10479divaw @var{dest}, @var{a}, @var{b} 10480@end example 10481where the value in @var{dest} will be the result returned from the 10482built-in. 10483@end deftypefn 10484 10485@deftypefn {Built-in Function} void __builtin_arc_flag (unsigned int @var{a}) 10486Generates 10487@example 10488flag @var{a} 10489@end example 10490@end deftypefn 10491 10492@deftypefn {Built-in Function} {unsigned int} __builtin_arc_lr (unsigned int @var{auxr}) 10493The operand, @var{auxv}, is the address of an auxiliary register and 10494must be a compile time constant. Generates: 10495@example 10496lr @var{dest}, [@var{auxr}] 10497@end example 10498Where the value in @var{dest} will be the result returned from the 10499built-in. 10500@end deftypefn 10501 10502@deftypefn {Built-in Function} void __builtin_arc_mul64 (int @var{a}, int @var{b}) 10503Only available with @option{-mmul64}. Generates: 10504@example 10505mul64 @var{a}, @var{b} 10506@end example 10507@end deftypefn 10508 10509@deftypefn {Built-in Function} void __builtin_arc_mulu64 (unsigned int @var{a}, unsigned int @var{b}) 10510Only available with @option{-mmul64}. Generates: 10511@example 10512mulu64 @var{a}, @var{b} 10513@end example 10514@end deftypefn 10515 10516@deftypefn {Built-in Function} void __builtin_arc_nop (void) 10517Generates: 10518@example 10519nop 10520@end example 10521@end deftypefn 10522 10523@deftypefn {Built-in Function} int __builtin_arc_norm (int @var{src}) 10524Only valid if the @samp{norm} instruction is available through the 10525@option{-mnorm} option or by default with @option{-mcpu=ARC700}. 10526Generates: 10527@example 10528norm @var{dest}, @var{src} 10529@end example 10530Where the value in @var{dest} will be the result returned from the 10531built-in. 10532@end deftypefn 10533 10534@deftypefn {Built-in Function} {short int} __builtin_arc_normw (short int @var{src}) 10535Only valid if the @samp{normw} instruction is available through the 10536@option{-mnorm} option or by default with @option{-mcpu=ARC700}. 10537Generates: 10538@example 10539normw @var{dest}, @var{src} 10540@end example 10541Where the value in @var{dest} will be the result returned from the 10542built-in. 10543@end deftypefn 10544 10545@deftypefn {Built-in Function} void __builtin_arc_rtie (void) 10546Generates: 10547@example 10548rtie 10549@end example 10550@end deftypefn 10551 10552@deftypefn {Built-in Function} void __builtin_arc_sleep (int @var{a} 10553Generates: 10554@example 10555sleep @var{a} 10556@end example 10557@end deftypefn 10558 10559@deftypefn {Built-in Function} void __builtin_arc_sr (unsigned int @var{auxr}, unsigned int @var{val}) 10560The first argument, @var{auxv}, is the address of an auxiliary 10561register, the second argument, @var{val}, is a compile time constant 10562to be written to the register. Generates: 10563@example 10564sr @var{auxr}, [@var{val}] 10565@end example 10566@end deftypefn 10567 10568@deftypefn {Built-in Function} int __builtin_arc_swap (int @var{src}) 10569Only valid with @option{-mswap}. Generates: 10570@example 10571swap @var{dest}, @var{src} 10572@end example 10573Where the value in @var{dest} will be the result returned from the 10574built-in. 10575@end deftypefn 10576 10577@deftypefn {Built-in Function} void __builtin_arc_swi (void) 10578Generates: 10579@example 10580swi 10581@end example 10582@end deftypefn 10583 10584@deftypefn {Built-in Function} void __builtin_arc_sync (void) 10585Only available with @option{-mcpu=ARC700}. Generates: 10586@example 10587sync 10588@end example 10589@end deftypefn 10590 10591@deftypefn {Built-in Function} void __builtin_arc_trap_s (unsigned int @var{c}) 10592Only available with @option{-mcpu=ARC700}. Generates: 10593@example 10594trap_s @var{c} 10595@end example 10596@end deftypefn 10597 10598@deftypefn {Built-in Function} void __builtin_arc_unimp_s (void) 10599Only available with @option{-mcpu=ARC700}. Generates: 10600@example 10601unimp_s 10602@end example 10603@end deftypefn 10604 10605The instructions generated by the following builtins are not 10606considered as candidates for scheduling. They are not moved around by 10607the compiler during scheduling, and thus can be expected to appear 10608where they are put in the C code: 10609@example 10610__builtin_arc_brk() 10611__builtin_arc_core_read() 10612__builtin_arc_core_write() 10613__builtin_arc_flag() 10614__builtin_arc_lr() 10615__builtin_arc_sleep() 10616__builtin_arc_sr() 10617__builtin_arc_swi() 10618@end example 10619 10620@node ARC SIMD Built-in Functions 10621@subsection ARC SIMD Built-in Functions 10622 10623SIMD builtins provided by the compiler can be used to generate the 10624vector instructions. This section describes the available builtins 10625and their usage in programs. With the @option{-msimd} option, the 10626compiler provides 128-bit vector types, which can be specified using 10627the @code{vector_size} attribute. The header file @file{arc-simd.h} 10628can be included to use the following predefined types: 10629@example 10630typedef int __v4si __attribute__((vector_size(16))); 10631typedef short __v8hi __attribute__((vector_size(16))); 10632@end example 10633 10634These types can be used to define 128-bit variables. The built-in 10635functions listed in the following section can be used on these 10636variables to generate the vector operations. 10637 10638For all builtins, @code{__builtin_arc_@var{someinsn}}, the header file 10639@file{arc-simd.h} also provides equivalent macros called 10640@code{_@var{someinsn}} that can be used for programming ease and 10641improved readability. The following macros for DMA control are also 10642provided: 10643@example 10644#define _setup_dma_in_channel_reg _vdiwr 10645#define _setup_dma_out_channel_reg _vdowr 10646@end example 10647 10648The following is a complete list of all the SIMD built-ins provided 10649for ARC, grouped by calling signature. 10650 10651The following take two @code{__v8hi} arguments and return a 10652@code{__v8hi} result: 10653@example 10654__v8hi __builtin_arc_vaddaw (__v8hi, __v8hi) 10655__v8hi __builtin_arc_vaddw (__v8hi, __v8hi) 10656__v8hi __builtin_arc_vand (__v8hi, __v8hi) 10657__v8hi __builtin_arc_vandaw (__v8hi, __v8hi) 10658__v8hi __builtin_arc_vavb (__v8hi, __v8hi) 10659__v8hi __builtin_arc_vavrb (__v8hi, __v8hi) 10660__v8hi __builtin_arc_vbic (__v8hi, __v8hi) 10661__v8hi __builtin_arc_vbicaw (__v8hi, __v8hi) 10662__v8hi __builtin_arc_vdifaw (__v8hi, __v8hi) 10663__v8hi __builtin_arc_vdifw (__v8hi, __v8hi) 10664__v8hi __builtin_arc_veqw (__v8hi, __v8hi) 10665__v8hi __builtin_arc_vh264f (__v8hi, __v8hi) 10666__v8hi __builtin_arc_vh264ft (__v8hi, __v8hi) 10667__v8hi __builtin_arc_vh264fw (__v8hi, __v8hi) 10668__v8hi __builtin_arc_vlew (__v8hi, __v8hi) 10669__v8hi __builtin_arc_vltw (__v8hi, __v8hi) 10670__v8hi __builtin_arc_vmaxaw (__v8hi, __v8hi) 10671__v8hi __builtin_arc_vmaxw (__v8hi, __v8hi) 10672__v8hi __builtin_arc_vminaw (__v8hi, __v8hi) 10673__v8hi __builtin_arc_vminw (__v8hi, __v8hi) 10674__v8hi __builtin_arc_vmr1aw (__v8hi, __v8hi) 10675__v8hi __builtin_arc_vmr1w (__v8hi, __v8hi) 10676__v8hi __builtin_arc_vmr2aw (__v8hi, __v8hi) 10677__v8hi __builtin_arc_vmr2w (__v8hi, __v8hi) 10678__v8hi __builtin_arc_vmr3aw (__v8hi, __v8hi) 10679__v8hi __builtin_arc_vmr3w (__v8hi, __v8hi) 10680__v8hi __builtin_arc_vmr4aw (__v8hi, __v8hi) 10681__v8hi __builtin_arc_vmr4w (__v8hi, __v8hi) 10682__v8hi __builtin_arc_vmr5aw (__v8hi, __v8hi) 10683__v8hi __builtin_arc_vmr5w (__v8hi, __v8hi) 10684__v8hi __builtin_arc_vmr6aw (__v8hi, __v8hi) 10685__v8hi __builtin_arc_vmr6w (__v8hi, __v8hi) 10686__v8hi __builtin_arc_vmr7aw (__v8hi, __v8hi) 10687__v8hi __builtin_arc_vmr7w (__v8hi, __v8hi) 10688__v8hi __builtin_arc_vmrb (__v8hi, __v8hi) 10689__v8hi __builtin_arc_vmulaw (__v8hi, __v8hi) 10690__v8hi __builtin_arc_vmulfaw (__v8hi, __v8hi) 10691__v8hi __builtin_arc_vmulfw (__v8hi, __v8hi) 10692__v8hi __builtin_arc_vmulw (__v8hi, __v8hi) 10693__v8hi __builtin_arc_vnew (__v8hi, __v8hi) 10694__v8hi __builtin_arc_vor (__v8hi, __v8hi) 10695__v8hi __builtin_arc_vsubaw (__v8hi, __v8hi) 10696__v8hi __builtin_arc_vsubw (__v8hi, __v8hi) 10697__v8hi __builtin_arc_vsummw (__v8hi, __v8hi) 10698__v8hi __builtin_arc_vvc1f (__v8hi, __v8hi) 10699__v8hi __builtin_arc_vvc1ft (__v8hi, __v8hi) 10700__v8hi __builtin_arc_vxor (__v8hi, __v8hi) 10701__v8hi __builtin_arc_vxoraw (__v8hi, __v8hi) 10702@end example 10703 10704The following take one @code{__v8hi} and one @code{int} argument and return a 10705@code{__v8hi} result: 10706 10707@example 10708__v8hi __builtin_arc_vbaddw (__v8hi, int) 10709__v8hi __builtin_arc_vbmaxw (__v8hi, int) 10710__v8hi __builtin_arc_vbminw (__v8hi, int) 10711__v8hi __builtin_arc_vbmulaw (__v8hi, int) 10712__v8hi __builtin_arc_vbmulfw (__v8hi, int) 10713__v8hi __builtin_arc_vbmulw (__v8hi, int) 10714__v8hi __builtin_arc_vbrsubw (__v8hi, int) 10715__v8hi __builtin_arc_vbsubw (__v8hi, int) 10716@end example 10717 10718The following take one @code{__v8hi} argument and one @code{int} argument which 10719must be a 3-bit compile time constant indicating a register number 10720I0-I7. They return a @code{__v8hi} result. 10721@example 10722__v8hi __builtin_arc_vasrw (__v8hi, const int) 10723__v8hi __builtin_arc_vsr8 (__v8hi, const int) 10724__v8hi __builtin_arc_vsr8aw (__v8hi, const int) 10725@end example 10726 10727The following take one @code{__v8hi} argument and one @code{int} 10728argument which must be a 6-bit compile time constant. They return a 10729@code{__v8hi} result. 10730@example 10731__v8hi __builtin_arc_vasrpwbi (__v8hi, const int) 10732__v8hi __builtin_arc_vasrrpwbi (__v8hi, const int) 10733__v8hi __builtin_arc_vasrrwi (__v8hi, const int) 10734__v8hi __builtin_arc_vasrsrwi (__v8hi, const int) 10735__v8hi __builtin_arc_vasrwi (__v8hi, const int) 10736__v8hi __builtin_arc_vsr8awi (__v8hi, const int) 10737__v8hi __builtin_arc_vsr8i (__v8hi, const int) 10738@end example 10739 10740The following take one @code{__v8hi} argument and one @code{int} argument which 10741must be a 8-bit compile time constant. They return a @code{__v8hi} 10742result. 10743@example 10744__v8hi __builtin_arc_vd6tapf (__v8hi, const int) 10745__v8hi __builtin_arc_vmvaw (__v8hi, const int) 10746__v8hi __builtin_arc_vmvw (__v8hi, const int) 10747__v8hi __builtin_arc_vmvzw (__v8hi, const int) 10748@end example 10749 10750The following take two @code{int} arguments, the second of which which 10751must be a 8-bit compile time constant. They return a @code{__v8hi} 10752result: 10753@example 10754__v8hi __builtin_arc_vmovaw (int, const int) 10755__v8hi __builtin_arc_vmovw (int, const int) 10756__v8hi __builtin_arc_vmovzw (int, const int) 10757@end example 10758 10759The following take a single @code{__v8hi} argument and return a 10760@code{__v8hi} result: 10761@example 10762__v8hi __builtin_arc_vabsaw (__v8hi) 10763__v8hi __builtin_arc_vabsw (__v8hi) 10764__v8hi __builtin_arc_vaddsuw (__v8hi) 10765__v8hi __builtin_arc_vexch1 (__v8hi) 10766__v8hi __builtin_arc_vexch2 (__v8hi) 10767__v8hi __builtin_arc_vexch4 (__v8hi) 10768__v8hi __builtin_arc_vsignw (__v8hi) 10769__v8hi __builtin_arc_vupbaw (__v8hi) 10770__v8hi __builtin_arc_vupbw (__v8hi) 10771__v8hi __builtin_arc_vupsbaw (__v8hi) 10772__v8hi __builtin_arc_vupsbw (__v8hi) 10773@end example 10774 10775The following take two @code{int} arguments and return no result: 10776@example 10777void __builtin_arc_vdirun (int, int) 10778void __builtin_arc_vdorun (int, int) 10779@end example 10780 10781The following take two @code{int} arguments and return no result. The 10782first argument must a 3-bit compile time constant indicating one of 10783the DR0-DR7 DMA setup channels: 10784@example 10785void __builtin_arc_vdiwr (const int, int) 10786void __builtin_arc_vdowr (const int, int) 10787@end example 10788 10789The following take an @code{int} argument and return no result: 10790@example 10791void __builtin_arc_vendrec (int) 10792void __builtin_arc_vrec (int) 10793void __builtin_arc_vrecrun (int) 10794void __builtin_arc_vrun (int) 10795@end example 10796 10797The following take a @code{__v8hi} argument and two @code{int} 10798arguments and return a @code{__v8hi} result. The second argument must 10799be a 3-bit compile time constants, indicating one the registers I0-I7, 10800and the third argument must be an 8-bit compile time constant. 10801 10802@emph{Note:} Although the equivalent hardware instructions do not take 10803an SIMD register as an operand, these builtins overwrite the relevant 10804bits of the @code{__v8hi} register provided as the first argument with 10805the value loaded from the @code{[Ib, u8]} location in the SDM. 10806 10807@example 10808__v8hi __builtin_arc_vld32 (__v8hi, const int, const int) 10809__v8hi __builtin_arc_vld32wh (__v8hi, const int, const int) 10810__v8hi __builtin_arc_vld32wl (__v8hi, const int, const int) 10811__v8hi __builtin_arc_vld64 (__v8hi, const int, const int) 10812@end example 10813 10814The following take two @code{int} arguments and return a @code{__v8hi} 10815result. The first argument must be a 3-bit compile time constants, 10816indicating one the registers I0-I7, and the second argument must be an 108178-bit compile time constant. 10818 10819@example 10820__v8hi __builtin_arc_vld128 (const int, const int) 10821__v8hi __builtin_arc_vld64w (const int, const int) 10822@end example 10823 10824The following take a @code{__v8hi} argument and two @code{int} 10825arguments and return no result. The second argument must be a 3-bit 10826compile time constants, indicating one the registers I0-I7, and the 10827third argument must be an 8-bit compile time constant. 10828 10829@example 10830void __builtin_arc_vst128 (__v8hi, const int, const int) 10831void __builtin_arc_vst64 (__v8hi, const int, const int) 10832@end example 10833 10834The following take a @code{__v8hi} argument and three @code{int} 10835arguments and return no result. The second argument must be a 3-bit 10836compile-time constant, identifying the 16-bit sub-register to be 10837stored, the third argument must be a 3-bit compile time constants, 10838indicating one the registers I0-I7, and the fourth argument must be an 108398-bit compile time constant. 10840 10841@example 10842void __builtin_arc_vst16_n (__v8hi, const int, const int, const int) 10843void __builtin_arc_vst32_n (__v8hi, const int, const int, const int) 10844@end example 10845 10846@node ARM iWMMXt Built-in Functions 10847@subsection ARM iWMMXt Built-in Functions 10848 10849These built-in functions are available for the ARM family of 10850processors when the @option{-mcpu=iwmmxt} switch is used: 10851 10852@smallexample 10853typedef int v2si __attribute__ ((vector_size (8))); 10854typedef short v4hi __attribute__ ((vector_size (8))); 10855typedef char v8qi __attribute__ ((vector_size (8))); 10856 10857int __builtin_arm_getwcgr0 (void) 10858void __builtin_arm_setwcgr0 (int) 10859int __builtin_arm_getwcgr1 (void) 10860void __builtin_arm_setwcgr1 (int) 10861int __builtin_arm_getwcgr2 (void) 10862void __builtin_arm_setwcgr2 (int) 10863int __builtin_arm_getwcgr3 (void) 10864void __builtin_arm_setwcgr3 (int) 10865int __builtin_arm_textrmsb (v8qi, int) 10866int __builtin_arm_textrmsh (v4hi, int) 10867int __builtin_arm_textrmsw (v2si, int) 10868int __builtin_arm_textrmub (v8qi, int) 10869int __builtin_arm_textrmuh (v4hi, int) 10870int __builtin_arm_textrmuw (v2si, int) 10871v8qi __builtin_arm_tinsrb (v8qi, int, int) 10872v4hi __builtin_arm_tinsrh (v4hi, int, int) 10873v2si __builtin_arm_tinsrw (v2si, int, int) 10874long long __builtin_arm_tmia (long long, int, int) 10875long long __builtin_arm_tmiabb (long long, int, int) 10876long long __builtin_arm_tmiabt (long long, int, int) 10877long long __builtin_arm_tmiaph (long long, int, int) 10878long long __builtin_arm_tmiatb (long long, int, int) 10879long long __builtin_arm_tmiatt (long long, int, int) 10880int __builtin_arm_tmovmskb (v8qi) 10881int __builtin_arm_tmovmskh (v4hi) 10882int __builtin_arm_tmovmskw (v2si) 10883long long __builtin_arm_waccb (v8qi) 10884long long __builtin_arm_wacch (v4hi) 10885long long __builtin_arm_waccw (v2si) 10886v8qi __builtin_arm_waddb (v8qi, v8qi) 10887v8qi __builtin_arm_waddbss (v8qi, v8qi) 10888v8qi __builtin_arm_waddbus (v8qi, v8qi) 10889v4hi __builtin_arm_waddh (v4hi, v4hi) 10890v4hi __builtin_arm_waddhss (v4hi, v4hi) 10891v4hi __builtin_arm_waddhus (v4hi, v4hi) 10892v2si __builtin_arm_waddw (v2si, v2si) 10893v2si __builtin_arm_waddwss (v2si, v2si) 10894v2si __builtin_arm_waddwus (v2si, v2si) 10895v8qi __builtin_arm_walign (v8qi, v8qi, int) 10896long long __builtin_arm_wand(long long, long long) 10897long long __builtin_arm_wandn (long long, long long) 10898v8qi __builtin_arm_wavg2b (v8qi, v8qi) 10899v8qi __builtin_arm_wavg2br (v8qi, v8qi) 10900v4hi __builtin_arm_wavg2h (v4hi, v4hi) 10901v4hi __builtin_arm_wavg2hr (v4hi, v4hi) 10902v8qi __builtin_arm_wcmpeqb (v8qi, v8qi) 10903v4hi __builtin_arm_wcmpeqh (v4hi, v4hi) 10904v2si __builtin_arm_wcmpeqw (v2si, v2si) 10905v8qi __builtin_arm_wcmpgtsb (v8qi, v8qi) 10906v4hi __builtin_arm_wcmpgtsh (v4hi, v4hi) 10907v2si __builtin_arm_wcmpgtsw (v2si, v2si) 10908v8qi __builtin_arm_wcmpgtub (v8qi, v8qi) 10909v4hi __builtin_arm_wcmpgtuh (v4hi, v4hi) 10910v2si __builtin_arm_wcmpgtuw (v2si, v2si) 10911long long __builtin_arm_wmacs (long long, v4hi, v4hi) 10912long long __builtin_arm_wmacsz (v4hi, v4hi) 10913long long __builtin_arm_wmacu (long long, v4hi, v4hi) 10914long long __builtin_arm_wmacuz (v4hi, v4hi) 10915v4hi __builtin_arm_wmadds (v4hi, v4hi) 10916v4hi __builtin_arm_wmaddu (v4hi, v4hi) 10917v8qi __builtin_arm_wmaxsb (v8qi, v8qi) 10918v4hi __builtin_arm_wmaxsh (v4hi, v4hi) 10919v2si __builtin_arm_wmaxsw (v2si, v2si) 10920v8qi __builtin_arm_wmaxub (v8qi, v8qi) 10921v4hi __builtin_arm_wmaxuh (v4hi, v4hi) 10922v2si __builtin_arm_wmaxuw (v2si, v2si) 10923v8qi __builtin_arm_wminsb (v8qi, v8qi) 10924v4hi __builtin_arm_wminsh (v4hi, v4hi) 10925v2si __builtin_arm_wminsw (v2si, v2si) 10926v8qi __builtin_arm_wminub (v8qi, v8qi) 10927v4hi __builtin_arm_wminuh (v4hi, v4hi) 10928v2si __builtin_arm_wminuw (v2si, v2si) 10929v4hi __builtin_arm_wmulsm (v4hi, v4hi) 10930v4hi __builtin_arm_wmulul (v4hi, v4hi) 10931v4hi __builtin_arm_wmulum (v4hi, v4hi) 10932long long __builtin_arm_wor (long long, long long) 10933v2si __builtin_arm_wpackdss (long long, long long) 10934v2si __builtin_arm_wpackdus (long long, long long) 10935v8qi __builtin_arm_wpackhss (v4hi, v4hi) 10936v8qi __builtin_arm_wpackhus (v4hi, v4hi) 10937v4hi __builtin_arm_wpackwss (v2si, v2si) 10938v4hi __builtin_arm_wpackwus (v2si, v2si) 10939long long __builtin_arm_wrord (long long, long long) 10940long long __builtin_arm_wrordi (long long, int) 10941v4hi __builtin_arm_wrorh (v4hi, long long) 10942v4hi __builtin_arm_wrorhi (v4hi, int) 10943v2si __builtin_arm_wrorw (v2si, long long) 10944v2si __builtin_arm_wrorwi (v2si, int) 10945v2si __builtin_arm_wsadb (v2si, v8qi, v8qi) 10946v2si __builtin_arm_wsadbz (v8qi, v8qi) 10947v2si __builtin_arm_wsadh (v2si, v4hi, v4hi) 10948v2si __builtin_arm_wsadhz (v4hi, v4hi) 10949v4hi __builtin_arm_wshufh (v4hi, int) 10950long long __builtin_arm_wslld (long long, long long) 10951long long __builtin_arm_wslldi (long long, int) 10952v4hi __builtin_arm_wsllh (v4hi, long long) 10953v4hi __builtin_arm_wsllhi (v4hi, int) 10954v2si __builtin_arm_wsllw (v2si, long long) 10955v2si __builtin_arm_wsllwi (v2si, int) 10956long long __builtin_arm_wsrad (long long, long long) 10957long long __builtin_arm_wsradi (long long, int) 10958v4hi __builtin_arm_wsrah (v4hi, long long) 10959v4hi __builtin_arm_wsrahi (v4hi, int) 10960v2si __builtin_arm_wsraw (v2si, long long) 10961v2si __builtin_arm_wsrawi (v2si, int) 10962long long __builtin_arm_wsrld (long long, long long) 10963long long __builtin_arm_wsrldi (long long, int) 10964v4hi __builtin_arm_wsrlh (v4hi, long long) 10965v4hi __builtin_arm_wsrlhi (v4hi, int) 10966v2si __builtin_arm_wsrlw (v2si, long long) 10967v2si __builtin_arm_wsrlwi (v2si, int) 10968v8qi __builtin_arm_wsubb (v8qi, v8qi) 10969v8qi __builtin_arm_wsubbss (v8qi, v8qi) 10970v8qi __builtin_arm_wsubbus (v8qi, v8qi) 10971v4hi __builtin_arm_wsubh (v4hi, v4hi) 10972v4hi __builtin_arm_wsubhss (v4hi, v4hi) 10973v4hi __builtin_arm_wsubhus (v4hi, v4hi) 10974v2si __builtin_arm_wsubw (v2si, v2si) 10975v2si __builtin_arm_wsubwss (v2si, v2si) 10976v2si __builtin_arm_wsubwus (v2si, v2si) 10977v4hi __builtin_arm_wunpckehsb (v8qi) 10978v2si __builtin_arm_wunpckehsh (v4hi) 10979long long __builtin_arm_wunpckehsw (v2si) 10980v4hi __builtin_arm_wunpckehub (v8qi) 10981v2si __builtin_arm_wunpckehuh (v4hi) 10982long long __builtin_arm_wunpckehuw (v2si) 10983v4hi __builtin_arm_wunpckelsb (v8qi) 10984v2si __builtin_arm_wunpckelsh (v4hi) 10985long long __builtin_arm_wunpckelsw (v2si) 10986v4hi __builtin_arm_wunpckelub (v8qi) 10987v2si __builtin_arm_wunpckeluh (v4hi) 10988long long __builtin_arm_wunpckeluw (v2si) 10989v8qi __builtin_arm_wunpckihb (v8qi, v8qi) 10990v4hi __builtin_arm_wunpckihh (v4hi, v4hi) 10991v2si __builtin_arm_wunpckihw (v2si, v2si) 10992v8qi __builtin_arm_wunpckilb (v8qi, v8qi) 10993v4hi __builtin_arm_wunpckilh (v4hi, v4hi) 10994v2si __builtin_arm_wunpckilw (v2si, v2si) 10995long long __builtin_arm_wxor (long long, long long) 10996long long __builtin_arm_wzero () 10997@end smallexample 10998 10999 11000@node ARM C Language Extensions (ACLE) 11001@subsection ARM C Language Extensions (ACLE) 11002 11003GCC implements extensions for C as described in the ARM C Language 11004Extensions (ACLE) specification, which can be found at 11005@uref{http://infocenter.arm.com/help/topic/com.arm.doc.ihi0053c/IHI0053C_acle_2_0.pdf}. 11006 11007As a part of ACLE, GCC implements extensions for Advanced SIMD as described in 11008the ARM C Language Extensions Specification. The complete list of Advanced SIMD 11009intrinsics can be found at 11010@uref{http://infocenter.arm.com/help/topic/com.arm.doc.ihi0073a/IHI0073A_arm_neon_intrinsics_ref.pdf}. 11011The built-in intrinsics for the Advanced SIMD extension are available when 11012NEON is enabled. 11013 11014Currently, ARM and AArch64 back ends do not support ACLE 2.0 fully. Both 11015back ends support CRC32 intrinsics from @file{arm_acle.h}. The ARM back end's 1101616-bit floating-point Advanced SIMD intrinsics currently comply to ACLE v1.1. 11017AArch64's back end does not have support for 16-bit floating point Advanced SIMD 11018intrinsics yet. 11019 11020See @ref{ARM Options} and @ref{AArch64 Options} for more information on the 11021availability of extensions. 11022 11023@node ARM Floating Point Status and Control Intrinsics 11024@subsection ARM Floating Point Status and Control Intrinsics 11025 11026These built-in functions are available for the ARM family of 11027processors with floating-point unit. 11028 11029@smallexample 11030unsigned int __builtin_arm_get_fpscr () 11031void __builtin_arm_set_fpscr (unsigned int) 11032@end smallexample 11033 11034@node AVR Built-in Functions 11035@subsection AVR Built-in Functions 11036 11037For each built-in function for AVR, there is an equally named, 11038uppercase built-in macro defined. That way users can easily query if 11039or if not a specific built-in is implemented or not. For example, if 11040@code{__builtin_avr_nop} is available the macro 11041@code{__BUILTIN_AVR_NOP} is defined to @code{1} and undefined otherwise. 11042 11043The following built-in functions map to the respective machine 11044instruction, i.e.@: @code{nop}, @code{sei}, @code{cli}, @code{sleep}, 11045@code{wdr}, @code{swap}, @code{fmul}, @code{fmuls} 11046resp. @code{fmulsu}. The three @code{fmul*} built-ins are implemented 11047as library call if no hardware multiplier is available. 11048 11049@smallexample 11050void __builtin_avr_nop (void) 11051void __builtin_avr_sei (void) 11052void __builtin_avr_cli (void) 11053void __builtin_avr_sleep (void) 11054void __builtin_avr_wdr (void) 11055unsigned char __builtin_avr_swap (unsigned char) 11056unsigned int __builtin_avr_fmul (unsigned char, unsigned char) 11057int __builtin_avr_fmuls (char, char) 11058int __builtin_avr_fmulsu (char, unsigned char) 11059@end smallexample 11060 11061In order to delay execution for a specific number of cycles, GCC 11062implements 11063@smallexample 11064void __builtin_avr_delay_cycles (unsigned long ticks) 11065@end smallexample 11066 11067@noindent 11068@code{ticks} is the number of ticks to delay execution. Note that this 11069built-in does not take into account the effect of interrupts that 11070might increase delay time. @code{ticks} must be a compile-time 11071integer constant; delays with a variable number of cycles are not supported. 11072 11073@smallexample 11074char __builtin_avr_flash_segment (const __memx void*) 11075@end smallexample 11076 11077@noindent 11078This built-in takes a byte address to the 24-bit 11079@ref{AVR Named Address Spaces,address space} @code{__memx} and returns 11080the number of the flash segment (the 64 KiB chunk) where the address 11081points to. Counting starts at @code{0}. 11082If the address does not point to flash memory, return @code{-1}. 11083 11084@smallexample 11085unsigned char __builtin_avr_insert_bits (unsigned long map, unsigned char bits, unsigned char val) 11086@end smallexample 11087 11088@noindent 11089Insert bits from @var{bits} into @var{val} and return the resulting 11090value. The nibbles of @var{map} determine how the insertion is 11091performed: Let @var{X} be the @var{n}-th nibble of @var{map} 11092@enumerate 11093@item If @var{X} is @code{0xf}, 11094then the @var{n}-th bit of @var{val} is returned unaltered. 11095 11096@item If X is in the range 0@dots{}7, 11097then the @var{n}-th result bit is set to the @var{X}-th bit of @var{bits} 11098 11099@item If X is in the range 8@dots{}@code{0xe}, 11100then the @var{n}-th result bit is undefined. 11101@end enumerate 11102 11103@noindent 11104One typical use case for this built-in is adjusting input and 11105output values to non-contiguous port layouts. Some examples: 11106 11107@smallexample 11108// same as val, bits is unused 11109__builtin_avr_insert_bits (0xffffffff, bits, val) 11110@end smallexample 11111 11112@smallexample 11113// same as bits, val is unused 11114__builtin_avr_insert_bits (0x76543210, bits, val) 11115@end smallexample 11116 11117@smallexample 11118// same as rotating bits by 4 11119__builtin_avr_insert_bits (0x32107654, bits, 0) 11120@end smallexample 11121 11122@smallexample 11123// high nibble of result is the high nibble of val 11124// low nibble of result is the low nibble of bits 11125__builtin_avr_insert_bits (0xffff3210, bits, val) 11126@end smallexample 11127 11128@smallexample 11129// reverse the bit order of bits 11130__builtin_avr_insert_bits (0x01234567, bits, 0) 11131@end smallexample 11132 11133@node Blackfin Built-in Functions 11134@subsection Blackfin Built-in Functions 11135 11136Currently, there are two Blackfin-specific built-in functions. These are 11137used for generating @code{CSYNC} and @code{SSYNC} machine insns without 11138using inline assembly; by using these built-in functions the compiler can 11139automatically add workarounds for hardware errata involving these 11140instructions. These functions are named as follows: 11141 11142@smallexample 11143void __builtin_bfin_csync (void) 11144void __builtin_bfin_ssync (void) 11145@end smallexample 11146 11147@node FR-V Built-in Functions 11148@subsection FR-V Built-in Functions 11149 11150GCC provides many FR-V-specific built-in functions. In general, 11151these functions are intended to be compatible with those described 11152by @cite{FR-V Family, Softune C/C++ Compiler Manual (V6), Fujitsu 11153Semiconductor}. The two exceptions are @code{__MDUNPACKH} and 11154@code{__MBTOHE}, the GCC forms of which pass 128-bit values by 11155pointer rather than by value. 11156 11157Most of the functions are named after specific FR-V instructions. 11158Such functions are said to be ``directly mapped'' and are summarized 11159here in tabular form. 11160 11161@menu 11162* Argument Types:: 11163* Directly-mapped Integer Functions:: 11164* Directly-mapped Media Functions:: 11165* Raw read/write Functions:: 11166* Other Built-in Functions:: 11167@end menu 11168 11169@node Argument Types 11170@subsubsection Argument Types 11171 11172The arguments to the built-in functions can be divided into three groups: 11173register numbers, compile-time constants and run-time values. In order 11174to make this classification clear at a glance, the arguments and return 11175values are given the following pseudo types: 11176 11177@multitable @columnfractions .20 .30 .15 .35 11178@item Pseudo type @tab Real C type @tab Constant? @tab Description 11179@item @code{uh} @tab @code{unsigned short} @tab No @tab an unsigned halfword 11180@item @code{uw1} @tab @code{unsigned int} @tab No @tab an unsigned word 11181@item @code{sw1} @tab @code{int} @tab No @tab a signed word 11182@item @code{uw2} @tab @code{unsigned long long} @tab No 11183@tab an unsigned doubleword 11184@item @code{sw2} @tab @code{long long} @tab No @tab a signed doubleword 11185@item @code{const} @tab @code{int} @tab Yes @tab an integer constant 11186@item @code{acc} @tab @code{int} @tab Yes @tab an ACC register number 11187@item @code{iacc} @tab @code{int} @tab Yes @tab an IACC register number 11188@end multitable 11189 11190These pseudo types are not defined by GCC, they are simply a notational 11191convenience used in this manual. 11192 11193Arguments of type @code{uh}, @code{uw1}, @code{sw1}, @code{uw2} 11194and @code{sw2} are evaluated at run time. They correspond to 11195register operands in the underlying FR-V instructions. 11196 11197@code{const} arguments represent immediate operands in the underlying 11198FR-V instructions. They must be compile-time constants. 11199 11200@code{acc} arguments are evaluated at compile time and specify the number 11201of an accumulator register. For example, an @code{acc} argument of 2 11202selects the ACC2 register. 11203 11204@code{iacc} arguments are similar to @code{acc} arguments but specify the 11205number of an IACC register. See @pxref{Other Built-in Functions} 11206for more details. 11207 11208@node Directly-mapped Integer Functions 11209@subsubsection Directly-Mapped Integer Functions 11210 11211The functions listed below map directly to FR-V I-type instructions. 11212 11213@multitable @columnfractions .45 .32 .23 11214@item Function prototype @tab Example usage @tab Assembly output 11215@item @code{sw1 __ADDSS (sw1, sw1)} 11216@tab @code{@var{c} = __ADDSS (@var{a}, @var{b})} 11217@tab @code{ADDSS @var{a},@var{b},@var{c}} 11218@item @code{sw1 __SCAN (sw1, sw1)} 11219@tab @code{@var{c} = __SCAN (@var{a}, @var{b})} 11220@tab @code{SCAN @var{a},@var{b},@var{c}} 11221@item @code{sw1 __SCUTSS (sw1)} 11222@tab @code{@var{b} = __SCUTSS (@var{a})} 11223@tab @code{SCUTSS @var{a},@var{b}} 11224@item @code{sw1 __SLASS (sw1, sw1)} 11225@tab @code{@var{c} = __SLASS (@var{a}, @var{b})} 11226@tab @code{SLASS @var{a},@var{b},@var{c}} 11227@item @code{void __SMASS (sw1, sw1)} 11228@tab @code{__SMASS (@var{a}, @var{b})} 11229@tab @code{SMASS @var{a},@var{b}} 11230@item @code{void __SMSSS (sw1, sw1)} 11231@tab @code{__SMSSS (@var{a}, @var{b})} 11232@tab @code{SMSSS @var{a},@var{b}} 11233@item @code{void __SMU (sw1, sw1)} 11234@tab @code{__SMU (@var{a}, @var{b})} 11235@tab @code{SMU @var{a},@var{b}} 11236@item @code{sw2 __SMUL (sw1, sw1)} 11237@tab @code{@var{c} = __SMUL (@var{a}, @var{b})} 11238@tab @code{SMUL @var{a},@var{b},@var{c}} 11239@item @code{sw1 __SUBSS (sw1, sw1)} 11240@tab @code{@var{c} = __SUBSS (@var{a}, @var{b})} 11241@tab @code{SUBSS @var{a},@var{b},@var{c}} 11242@item @code{uw2 __UMUL (uw1, uw1)} 11243@tab @code{@var{c} = __UMUL (@var{a}, @var{b})} 11244@tab @code{UMUL @var{a},@var{b},@var{c}} 11245@end multitable 11246 11247@node Directly-mapped Media Functions 11248@subsubsection Directly-Mapped Media Functions 11249 11250The functions listed below map directly to FR-V M-type instructions. 11251 11252@multitable @columnfractions .45 .32 .23 11253@item Function prototype @tab Example usage @tab Assembly output 11254@item @code{uw1 __MABSHS (sw1)} 11255@tab @code{@var{b} = __MABSHS (@var{a})} 11256@tab @code{MABSHS @var{a},@var{b}} 11257@item @code{void __MADDACCS (acc, acc)} 11258@tab @code{__MADDACCS (@var{b}, @var{a})} 11259@tab @code{MADDACCS @var{a},@var{b}} 11260@item @code{sw1 __MADDHSS (sw1, sw1)} 11261@tab @code{@var{c} = __MADDHSS (@var{a}, @var{b})} 11262@tab @code{MADDHSS @var{a},@var{b},@var{c}} 11263@item @code{uw1 __MADDHUS (uw1, uw1)} 11264@tab @code{@var{c} = __MADDHUS (@var{a}, @var{b})} 11265@tab @code{MADDHUS @var{a},@var{b},@var{c}} 11266@item @code{uw1 __MAND (uw1, uw1)} 11267@tab @code{@var{c} = __MAND (@var{a}, @var{b})} 11268@tab @code{MAND @var{a},@var{b},@var{c}} 11269@item @code{void __MASACCS (acc, acc)} 11270@tab @code{__MASACCS (@var{b}, @var{a})} 11271@tab @code{MASACCS @var{a},@var{b}} 11272@item @code{uw1 __MAVEH (uw1, uw1)} 11273@tab @code{@var{c} = __MAVEH (@var{a}, @var{b})} 11274@tab @code{MAVEH @var{a},@var{b},@var{c}} 11275@item @code{uw2 __MBTOH (uw1)} 11276@tab @code{@var{b} = __MBTOH (@var{a})} 11277@tab @code{MBTOH @var{a},@var{b}} 11278@item @code{void __MBTOHE (uw1 *, uw1)} 11279@tab @code{__MBTOHE (&@var{b}, @var{a})} 11280@tab @code{MBTOHE @var{a},@var{b}} 11281@item @code{void __MCLRACC (acc)} 11282@tab @code{__MCLRACC (@var{a})} 11283@tab @code{MCLRACC @var{a}} 11284@item @code{void __MCLRACCA (void)} 11285@tab @code{__MCLRACCA ()} 11286@tab @code{MCLRACCA} 11287@item @code{uw1 __Mcop1 (uw1, uw1)} 11288@tab @code{@var{c} = __Mcop1 (@var{a}, @var{b})} 11289@tab @code{Mcop1 @var{a},@var{b},@var{c}} 11290@item @code{uw1 __Mcop2 (uw1, uw1)} 11291@tab @code{@var{c} = __Mcop2 (@var{a}, @var{b})} 11292@tab @code{Mcop2 @var{a},@var{b},@var{c}} 11293@item @code{uw1 __MCPLHI (uw2, const)} 11294@tab @code{@var{c} = __MCPLHI (@var{a}, @var{b})} 11295@tab @code{MCPLHI @var{a},#@var{b},@var{c}} 11296@item @code{uw1 __MCPLI (uw2, const)} 11297@tab @code{@var{c} = __MCPLI (@var{a}, @var{b})} 11298@tab @code{MCPLI @var{a},#@var{b},@var{c}} 11299@item @code{void __MCPXIS (acc, sw1, sw1)} 11300@tab @code{__MCPXIS (@var{c}, @var{a}, @var{b})} 11301@tab @code{MCPXIS @var{a},@var{b},@var{c}} 11302@item @code{void __MCPXIU (acc, uw1, uw1)} 11303@tab @code{__MCPXIU (@var{c}, @var{a}, @var{b})} 11304@tab @code{MCPXIU @var{a},@var{b},@var{c}} 11305@item @code{void __MCPXRS (acc, sw1, sw1)} 11306@tab @code{__MCPXRS (@var{c}, @var{a}, @var{b})} 11307@tab @code{MCPXRS @var{a},@var{b},@var{c}} 11308@item @code{void __MCPXRU (acc, uw1, uw1)} 11309@tab @code{__MCPXRU (@var{c}, @var{a}, @var{b})} 11310@tab @code{MCPXRU @var{a},@var{b},@var{c}} 11311@item @code{uw1 __MCUT (acc, uw1)} 11312@tab @code{@var{c} = __MCUT (@var{a}, @var{b})} 11313@tab @code{MCUT @var{a},@var{b},@var{c}} 11314@item @code{uw1 __MCUTSS (acc, sw1)} 11315@tab @code{@var{c} = __MCUTSS (@var{a}, @var{b})} 11316@tab @code{MCUTSS @var{a},@var{b},@var{c}} 11317@item @code{void __MDADDACCS (acc, acc)} 11318@tab @code{__MDADDACCS (@var{b}, @var{a})} 11319@tab @code{MDADDACCS @var{a},@var{b}} 11320@item @code{void __MDASACCS (acc, acc)} 11321@tab @code{__MDASACCS (@var{b}, @var{a})} 11322@tab @code{MDASACCS @var{a},@var{b}} 11323@item @code{uw2 __MDCUTSSI (acc, const)} 11324@tab @code{@var{c} = __MDCUTSSI (@var{a}, @var{b})} 11325@tab @code{MDCUTSSI @var{a},#@var{b},@var{c}} 11326@item @code{uw2 __MDPACKH (uw2, uw2)} 11327@tab @code{@var{c} = __MDPACKH (@var{a}, @var{b})} 11328@tab @code{MDPACKH @var{a},@var{b},@var{c}} 11329@item @code{uw2 __MDROTLI (uw2, const)} 11330@tab @code{@var{c} = __MDROTLI (@var{a}, @var{b})} 11331@tab @code{MDROTLI @var{a},#@var{b},@var{c}} 11332@item @code{void __MDSUBACCS (acc, acc)} 11333@tab @code{__MDSUBACCS (@var{b}, @var{a})} 11334@tab @code{MDSUBACCS @var{a},@var{b}} 11335@item @code{void __MDUNPACKH (uw1 *, uw2)} 11336@tab @code{__MDUNPACKH (&@var{b}, @var{a})} 11337@tab @code{MDUNPACKH @var{a},@var{b}} 11338@item @code{uw2 __MEXPDHD (uw1, const)} 11339@tab @code{@var{c} = __MEXPDHD (@var{a}, @var{b})} 11340@tab @code{MEXPDHD @var{a},#@var{b},@var{c}} 11341@item @code{uw1 __MEXPDHW (uw1, const)} 11342@tab @code{@var{c} = __MEXPDHW (@var{a}, @var{b})} 11343@tab @code{MEXPDHW @var{a},#@var{b},@var{c}} 11344@item @code{uw1 __MHDSETH (uw1, const)} 11345@tab @code{@var{c} = __MHDSETH (@var{a}, @var{b})} 11346@tab @code{MHDSETH @var{a},#@var{b},@var{c}} 11347@item @code{sw1 __MHDSETS (const)} 11348@tab @code{@var{b} = __MHDSETS (@var{a})} 11349@tab @code{MHDSETS #@var{a},@var{b}} 11350@item @code{uw1 __MHSETHIH (uw1, const)} 11351@tab @code{@var{b} = __MHSETHIH (@var{b}, @var{a})} 11352@tab @code{MHSETHIH #@var{a},@var{b}} 11353@item @code{sw1 __MHSETHIS (sw1, const)} 11354@tab @code{@var{b} = __MHSETHIS (@var{b}, @var{a})} 11355@tab @code{MHSETHIS #@var{a},@var{b}} 11356@item @code{uw1 __MHSETLOH (uw1, const)} 11357@tab @code{@var{b} = __MHSETLOH (@var{b}, @var{a})} 11358@tab @code{MHSETLOH #@var{a},@var{b}} 11359@item @code{sw1 __MHSETLOS (sw1, const)} 11360@tab @code{@var{b} = __MHSETLOS (@var{b}, @var{a})} 11361@tab @code{MHSETLOS #@var{a},@var{b}} 11362@item @code{uw1 __MHTOB (uw2)} 11363@tab @code{@var{b} = __MHTOB (@var{a})} 11364@tab @code{MHTOB @var{a},@var{b}} 11365@item @code{void __MMACHS (acc, sw1, sw1)} 11366@tab @code{__MMACHS (@var{c}, @var{a}, @var{b})} 11367@tab @code{MMACHS @var{a},@var{b},@var{c}} 11368@item @code{void __MMACHU (acc, uw1, uw1)} 11369@tab @code{__MMACHU (@var{c}, @var{a}, @var{b})} 11370@tab @code{MMACHU @var{a},@var{b},@var{c}} 11371@item @code{void __MMRDHS (acc, sw1, sw1)} 11372@tab @code{__MMRDHS (@var{c}, @var{a}, @var{b})} 11373@tab @code{MMRDHS @var{a},@var{b},@var{c}} 11374@item @code{void __MMRDHU (acc, uw1, uw1)} 11375@tab @code{__MMRDHU (@var{c}, @var{a}, @var{b})} 11376@tab @code{MMRDHU @var{a},@var{b},@var{c}} 11377@item @code{void __MMULHS (acc, sw1, sw1)} 11378@tab @code{__MMULHS (@var{c}, @var{a}, @var{b})} 11379@tab @code{MMULHS @var{a},@var{b},@var{c}} 11380@item @code{void __MMULHU (acc, uw1, uw1)} 11381@tab @code{__MMULHU (@var{c}, @var{a}, @var{b})} 11382@tab @code{MMULHU @var{a},@var{b},@var{c}} 11383@item @code{void __MMULXHS (acc, sw1, sw1)} 11384@tab @code{__MMULXHS (@var{c}, @var{a}, @var{b})} 11385@tab @code{MMULXHS @var{a},@var{b},@var{c}} 11386@item @code{void __MMULXHU (acc, uw1, uw1)} 11387@tab @code{__MMULXHU (@var{c}, @var{a}, @var{b})} 11388@tab @code{MMULXHU @var{a},@var{b},@var{c}} 11389@item @code{uw1 __MNOT (uw1)} 11390@tab @code{@var{b} = __MNOT (@var{a})} 11391@tab @code{MNOT @var{a},@var{b}} 11392@item @code{uw1 __MOR (uw1, uw1)} 11393@tab @code{@var{c} = __MOR (@var{a}, @var{b})} 11394@tab @code{MOR @var{a},@var{b},@var{c}} 11395@item @code{uw1 __MPACKH (uh, uh)} 11396@tab @code{@var{c} = __MPACKH (@var{a}, @var{b})} 11397@tab @code{MPACKH @var{a},@var{b},@var{c}} 11398@item @code{sw2 __MQADDHSS (sw2, sw2)} 11399@tab @code{@var{c} = __MQADDHSS (@var{a}, @var{b})} 11400@tab @code{MQADDHSS @var{a},@var{b},@var{c}} 11401@item @code{uw2 __MQADDHUS (uw2, uw2)} 11402@tab @code{@var{c} = __MQADDHUS (@var{a}, @var{b})} 11403@tab @code{MQADDHUS @var{a},@var{b},@var{c}} 11404@item @code{void __MQCPXIS (acc, sw2, sw2)} 11405@tab @code{__MQCPXIS (@var{c}, @var{a}, @var{b})} 11406@tab @code{MQCPXIS @var{a},@var{b},@var{c}} 11407@item @code{void __MQCPXIU (acc, uw2, uw2)} 11408@tab @code{__MQCPXIU (@var{c}, @var{a}, @var{b})} 11409@tab @code{MQCPXIU @var{a},@var{b},@var{c}} 11410@item @code{void __MQCPXRS (acc, sw2, sw2)} 11411@tab @code{__MQCPXRS (@var{c}, @var{a}, @var{b})} 11412@tab @code{MQCPXRS @var{a},@var{b},@var{c}} 11413@item @code{void __MQCPXRU (acc, uw2, uw2)} 11414@tab @code{__MQCPXRU (@var{c}, @var{a}, @var{b})} 11415@tab @code{MQCPXRU @var{a},@var{b},@var{c}} 11416@item @code{sw2 __MQLCLRHS (sw2, sw2)} 11417@tab @code{@var{c} = __MQLCLRHS (@var{a}, @var{b})} 11418@tab @code{MQLCLRHS @var{a},@var{b},@var{c}} 11419@item @code{sw2 __MQLMTHS (sw2, sw2)} 11420@tab @code{@var{c} = __MQLMTHS (@var{a}, @var{b})} 11421@tab @code{MQLMTHS @var{a},@var{b},@var{c}} 11422@item @code{void __MQMACHS (acc, sw2, sw2)} 11423@tab @code{__MQMACHS (@var{c}, @var{a}, @var{b})} 11424@tab @code{MQMACHS @var{a},@var{b},@var{c}} 11425@item @code{void __MQMACHU (acc, uw2, uw2)} 11426@tab @code{__MQMACHU (@var{c}, @var{a}, @var{b})} 11427@tab @code{MQMACHU @var{a},@var{b},@var{c}} 11428@item @code{void __MQMACXHS (acc, sw2, sw2)} 11429@tab @code{__MQMACXHS (@var{c}, @var{a}, @var{b})} 11430@tab @code{MQMACXHS @var{a},@var{b},@var{c}} 11431@item @code{void __MQMULHS (acc, sw2, sw2)} 11432@tab @code{__MQMULHS (@var{c}, @var{a}, @var{b})} 11433@tab @code{MQMULHS @var{a},@var{b},@var{c}} 11434@item @code{void __MQMULHU (acc, uw2, uw2)} 11435@tab @code{__MQMULHU (@var{c}, @var{a}, @var{b})} 11436@tab @code{MQMULHU @var{a},@var{b},@var{c}} 11437@item @code{void __MQMULXHS (acc, sw2, sw2)} 11438@tab @code{__MQMULXHS (@var{c}, @var{a}, @var{b})} 11439@tab @code{MQMULXHS @var{a},@var{b},@var{c}} 11440@item @code{void __MQMULXHU (acc, uw2, uw2)} 11441@tab @code{__MQMULXHU (@var{c}, @var{a}, @var{b})} 11442@tab @code{MQMULXHU @var{a},@var{b},@var{c}} 11443@item @code{sw2 __MQSATHS (sw2, sw2)} 11444@tab @code{@var{c} = __MQSATHS (@var{a}, @var{b})} 11445@tab @code{MQSATHS @var{a},@var{b},@var{c}} 11446@item @code{uw2 __MQSLLHI (uw2, int)} 11447@tab @code{@var{c} = __MQSLLHI (@var{a}, @var{b})} 11448@tab @code{MQSLLHI @var{a},@var{b},@var{c}} 11449@item @code{sw2 __MQSRAHI (sw2, int)} 11450@tab @code{@var{c} = __MQSRAHI (@var{a}, @var{b})} 11451@tab @code{MQSRAHI @var{a},@var{b},@var{c}} 11452@item @code{sw2 __MQSUBHSS (sw2, sw2)} 11453@tab @code{@var{c} = __MQSUBHSS (@var{a}, @var{b})} 11454@tab @code{MQSUBHSS @var{a},@var{b},@var{c}} 11455@item @code{uw2 __MQSUBHUS (uw2, uw2)} 11456@tab @code{@var{c} = __MQSUBHUS (@var{a}, @var{b})} 11457@tab @code{MQSUBHUS @var{a},@var{b},@var{c}} 11458@item @code{void __MQXMACHS (acc, sw2, sw2)} 11459@tab @code{__MQXMACHS (@var{c}, @var{a}, @var{b})} 11460@tab @code{MQXMACHS @var{a},@var{b},@var{c}} 11461@item @code{void __MQXMACXHS (acc, sw2, sw2)} 11462@tab @code{__MQXMACXHS (@var{c}, @var{a}, @var{b})} 11463@tab @code{MQXMACXHS @var{a},@var{b},@var{c}} 11464@item @code{uw1 __MRDACC (acc)} 11465@tab @code{@var{b} = __MRDACC (@var{a})} 11466@tab @code{MRDACC @var{a},@var{b}} 11467@item @code{uw1 __MRDACCG (acc)} 11468@tab @code{@var{b} = __MRDACCG (@var{a})} 11469@tab @code{MRDACCG @var{a},@var{b}} 11470@item @code{uw1 __MROTLI (uw1, const)} 11471@tab @code{@var{c} = __MROTLI (@var{a}, @var{b})} 11472@tab @code{MROTLI @var{a},#@var{b},@var{c}} 11473@item @code{uw1 __MROTRI (uw1, const)} 11474@tab @code{@var{c} = __MROTRI (@var{a}, @var{b})} 11475@tab @code{MROTRI @var{a},#@var{b},@var{c}} 11476@item @code{sw1 __MSATHS (sw1, sw1)} 11477@tab @code{@var{c} = __MSATHS (@var{a}, @var{b})} 11478@tab @code{MSATHS @var{a},@var{b},@var{c}} 11479@item @code{uw1 __MSATHU (uw1, uw1)} 11480@tab @code{@var{c} = __MSATHU (@var{a}, @var{b})} 11481@tab @code{MSATHU @var{a},@var{b},@var{c}} 11482@item @code{uw1 __MSLLHI (uw1, const)} 11483@tab @code{@var{c} = __MSLLHI (@var{a}, @var{b})} 11484@tab @code{MSLLHI @var{a},#@var{b},@var{c}} 11485@item @code{sw1 __MSRAHI (sw1, const)} 11486@tab @code{@var{c} = __MSRAHI (@var{a}, @var{b})} 11487@tab @code{MSRAHI @var{a},#@var{b},@var{c}} 11488@item @code{uw1 __MSRLHI (uw1, const)} 11489@tab @code{@var{c} = __MSRLHI (@var{a}, @var{b})} 11490@tab @code{MSRLHI @var{a},#@var{b},@var{c}} 11491@item @code{void __MSUBACCS (acc, acc)} 11492@tab @code{__MSUBACCS (@var{b}, @var{a})} 11493@tab @code{MSUBACCS @var{a},@var{b}} 11494@item @code{sw1 __MSUBHSS (sw1, sw1)} 11495@tab @code{@var{c} = __MSUBHSS (@var{a}, @var{b})} 11496@tab @code{MSUBHSS @var{a},@var{b},@var{c}} 11497@item @code{uw1 __MSUBHUS (uw1, uw1)} 11498@tab @code{@var{c} = __MSUBHUS (@var{a}, @var{b})} 11499@tab @code{MSUBHUS @var{a},@var{b},@var{c}} 11500@item @code{void __MTRAP (void)} 11501@tab @code{__MTRAP ()} 11502@tab @code{MTRAP} 11503@item @code{uw2 __MUNPACKH (uw1)} 11504@tab @code{@var{b} = __MUNPACKH (@var{a})} 11505@tab @code{MUNPACKH @var{a},@var{b}} 11506@item @code{uw1 __MWCUT (uw2, uw1)} 11507@tab @code{@var{c} = __MWCUT (@var{a}, @var{b})} 11508@tab @code{MWCUT @var{a},@var{b},@var{c}} 11509@item @code{void __MWTACC (acc, uw1)} 11510@tab @code{__MWTACC (@var{b}, @var{a})} 11511@tab @code{MWTACC @var{a},@var{b}} 11512@item @code{void __MWTACCG (acc, uw1)} 11513@tab @code{__MWTACCG (@var{b}, @var{a})} 11514@tab @code{MWTACCG @var{a},@var{b}} 11515@item @code{uw1 __MXOR (uw1, uw1)} 11516@tab @code{@var{c} = __MXOR (@var{a}, @var{b})} 11517@tab @code{MXOR @var{a},@var{b},@var{c}} 11518@end multitable 11519 11520@node Raw read/write Functions 11521@subsubsection Raw Read/Write Functions 11522 11523This sections describes built-in functions related to read and write 11524instructions to access memory. These functions generate 11525@code{membar} instructions to flush the I/O load and stores where 11526appropriate, as described in Fujitsu's manual described above. 11527 11528@table @code 11529 11530@item unsigned char __builtin_read8 (void *@var{data}) 11531@item unsigned short __builtin_read16 (void *@var{data}) 11532@item unsigned long __builtin_read32 (void *@var{data}) 11533@item unsigned long long __builtin_read64 (void *@var{data}) 11534 11535@item void __builtin_write8 (void *@var{data}, unsigned char @var{datum}) 11536@item void __builtin_write16 (void *@var{data}, unsigned short @var{datum}) 11537@item void __builtin_write32 (void *@var{data}, unsigned long @var{datum}) 11538@item void __builtin_write64 (void *@var{data}, unsigned long long @var{datum}) 11539@end table 11540 11541@node Other Built-in Functions 11542@subsubsection Other Built-in Functions 11543 11544This section describes built-in functions that are not named after 11545a specific FR-V instruction. 11546 11547@table @code 11548@item sw2 __IACCreadll (iacc @var{reg}) 11549Return the full 64-bit value of IACC0@. The @var{reg} argument is reserved 11550for future expansion and must be 0. 11551 11552@item sw1 __IACCreadl (iacc @var{reg}) 11553Return the value of IACC0H if @var{reg} is 0 and IACC0L if @var{reg} is 1. 11554Other values of @var{reg} are rejected as invalid. 11555 11556@item void __IACCsetll (iacc @var{reg}, sw2 @var{x}) 11557Set the full 64-bit value of IACC0 to @var{x}. The @var{reg} argument 11558is reserved for future expansion and must be 0. 11559 11560@item void __IACCsetl (iacc @var{reg}, sw1 @var{x}) 11561Set IACC0H to @var{x} if @var{reg} is 0 and IACC0L to @var{x} if @var{reg} 11562is 1. Other values of @var{reg} are rejected as invalid. 11563 11564@item void __data_prefetch0 (const void *@var{x}) 11565Use the @code{dcpl} instruction to load the contents of address @var{x} 11566into the data cache. 11567 11568@item void __data_prefetch (const void *@var{x}) 11569Use the @code{nldub} instruction to load the contents of address @var{x} 11570into the data cache. The instruction is issued in slot I1@. 11571@end table 11572 11573@node MIPS DSP Built-in Functions 11574@subsection MIPS DSP Built-in Functions 11575 11576The MIPS DSP Application-Specific Extension (ASE) includes new 11577instructions that are designed to improve the performance of DSP and 11578media applications. It provides instructions that operate on packed 115798-bit/16-bit integer data, Q7, Q15 and Q31 fractional data. 11580 11581GCC supports MIPS DSP operations using both the generic 11582vector extensions (@pxref{Vector Extensions}) and a collection of 11583MIPS-specific built-in functions. Both kinds of support are 11584enabled by the @option{-mdsp} command-line option. 11585 11586Revision 2 of the ASE was introduced in the second half of 2006. 11587This revision adds extra instructions to the original ASE, but is 11588otherwise backwards-compatible with it. You can select revision 2 11589using the command-line option @option{-mdspr2}; this option implies 11590@option{-mdsp}. 11591 11592The SCOUNT and POS bits of the DSP control register are global. The 11593WRDSP, EXTPDP, EXTPDPV and MTHLIP instructions modify the SCOUNT and 11594POS bits. During optimization, the compiler does not delete these 11595instructions and it does not delete calls to functions containing 11596these instructions. 11597 11598At present, GCC only provides support for operations on 32-bit 11599vectors. The vector type associated with 8-bit integer data is 11600usually called @code{v4i8}, the vector type associated with Q7 11601is usually called @code{v4q7}, the vector type associated with 16-bit 11602integer data is usually called @code{v2i16}, and the vector type 11603associated with Q15 is usually called @code{v2q15}. They can be 11604defined in C as follows: 11605 11606@smallexample 11607typedef signed char v4i8 __attribute__ ((vector_size(4))); 11608typedef signed char v4q7 __attribute__ ((vector_size(4))); 11609typedef short v2i16 __attribute__ ((vector_size(4))); 11610typedef short v2q15 __attribute__ ((vector_size(4))); 11611@end smallexample 11612 11613@code{v4i8}, @code{v4q7}, @code{v2i16} and @code{v2q15} values are 11614initialized in the same way as aggregates. For example: 11615 11616@smallexample 11617v4i8 a = @{1, 2, 3, 4@}; 11618v4i8 b; 11619b = (v4i8) @{5, 6, 7, 8@}; 11620 11621v2q15 c = @{0x0fcb, 0x3a75@}; 11622v2q15 d; 11623d = (v2q15) @{0.1234 * 0x1.0p15, 0.4567 * 0x1.0p15@}; 11624@end smallexample 11625 11626@emph{Note:} The CPU's endianness determines the order in which values 11627are packed. On little-endian targets, the first value is the least 11628significant and the last value is the most significant. The opposite 11629order applies to big-endian targets. For example, the code above 11630sets the lowest byte of @code{a} to @code{1} on little-endian targets 11631and @code{4} on big-endian targets. 11632 11633@emph{Note:} Q7, Q15 and Q31 values must be initialized with their integer 11634representation. As shown in this example, the integer representation 11635of a Q7 value can be obtained by multiplying the fractional value by 11636@code{0x1.0p7}. The equivalent for Q15 values is to multiply by 11637@code{0x1.0p15}. The equivalent for Q31 values is to multiply by 11638@code{0x1.0p31}. 11639 11640The table below lists the @code{v4i8} and @code{v2q15} operations for which 11641hardware support exists. @code{a} and @code{b} are @code{v4i8} values, 11642and @code{c} and @code{d} are @code{v2q15} values. 11643 11644@multitable @columnfractions .50 .50 11645@item C code @tab MIPS instruction 11646@item @code{a + b} @tab @code{addu.qb} 11647@item @code{c + d} @tab @code{addq.ph} 11648@item @code{a - b} @tab @code{subu.qb} 11649@item @code{c - d} @tab @code{subq.ph} 11650@end multitable 11651 11652The table below lists the @code{v2i16} operation for which 11653hardware support exists for the DSP ASE REV 2. @code{e} and @code{f} are 11654@code{v2i16} values. 11655 11656@multitable @columnfractions .50 .50 11657@item C code @tab MIPS instruction 11658@item @code{e * f} @tab @code{mul.ph} 11659@end multitable 11660 11661It is easier to describe the DSP built-in functions if we first define 11662the following types: 11663 11664@smallexample 11665typedef int q31; 11666typedef int i32; 11667typedef unsigned int ui32; 11668typedef long long a64; 11669@end smallexample 11670 11671@code{q31} and @code{i32} are actually the same as @code{int}, but we 11672use @code{q31} to indicate a Q31 fractional value and @code{i32} to 11673indicate a 32-bit integer value. Similarly, @code{a64} is the same as 11674@code{long long}, but we use @code{a64} to indicate values that are 11675placed in one of the four DSP accumulators (@code{$ac0}, 11676@code{$ac1}, @code{$ac2} or @code{$ac3}). 11677 11678Also, some built-in functions prefer or require immediate numbers as 11679parameters, because the corresponding DSP instructions accept both immediate 11680numbers and register operands, or accept immediate numbers only. The 11681immediate parameters are listed as follows. 11682 11683@smallexample 11684imm0_3: 0 to 3. 11685imm0_7: 0 to 7. 11686imm0_15: 0 to 15. 11687imm0_31: 0 to 31. 11688imm0_63: 0 to 63. 11689imm0_255: 0 to 255. 11690imm_n32_31: -32 to 31. 11691imm_n512_511: -512 to 511. 11692@end smallexample 11693 11694The following built-in functions map directly to a particular MIPS DSP 11695instruction. Please refer to the architecture specification 11696for details on what each instruction does. 11697 11698@smallexample 11699v2q15 __builtin_mips_addq_ph (v2q15, v2q15) 11700v2q15 __builtin_mips_addq_s_ph (v2q15, v2q15) 11701q31 __builtin_mips_addq_s_w (q31, q31) 11702v4i8 __builtin_mips_addu_qb (v4i8, v4i8) 11703v4i8 __builtin_mips_addu_s_qb (v4i8, v4i8) 11704v2q15 __builtin_mips_subq_ph (v2q15, v2q15) 11705v2q15 __builtin_mips_subq_s_ph (v2q15, v2q15) 11706q31 __builtin_mips_subq_s_w (q31, q31) 11707v4i8 __builtin_mips_subu_qb (v4i8, v4i8) 11708v4i8 __builtin_mips_subu_s_qb (v4i8, v4i8) 11709i32 __builtin_mips_addsc (i32, i32) 11710i32 __builtin_mips_addwc (i32, i32) 11711i32 __builtin_mips_modsub (i32, i32) 11712i32 __builtin_mips_raddu_w_qb (v4i8) 11713v2q15 __builtin_mips_absq_s_ph (v2q15) 11714q31 __builtin_mips_absq_s_w (q31) 11715v4i8 __builtin_mips_precrq_qb_ph (v2q15, v2q15) 11716v2q15 __builtin_mips_precrq_ph_w (q31, q31) 11717v2q15 __builtin_mips_precrq_rs_ph_w (q31, q31) 11718v4i8 __builtin_mips_precrqu_s_qb_ph (v2q15, v2q15) 11719q31 __builtin_mips_preceq_w_phl (v2q15) 11720q31 __builtin_mips_preceq_w_phr (v2q15) 11721v2q15 __builtin_mips_precequ_ph_qbl (v4i8) 11722v2q15 __builtin_mips_precequ_ph_qbr (v4i8) 11723v2q15 __builtin_mips_precequ_ph_qbla (v4i8) 11724v2q15 __builtin_mips_precequ_ph_qbra (v4i8) 11725v2q15 __builtin_mips_preceu_ph_qbl (v4i8) 11726v2q15 __builtin_mips_preceu_ph_qbr (v4i8) 11727v2q15 __builtin_mips_preceu_ph_qbla (v4i8) 11728v2q15 __builtin_mips_preceu_ph_qbra (v4i8) 11729v4i8 __builtin_mips_shll_qb (v4i8, imm0_7) 11730v4i8 __builtin_mips_shll_qb (v4i8, i32) 11731v2q15 __builtin_mips_shll_ph (v2q15, imm0_15) 11732v2q15 __builtin_mips_shll_ph (v2q15, i32) 11733v2q15 __builtin_mips_shll_s_ph (v2q15, imm0_15) 11734v2q15 __builtin_mips_shll_s_ph (v2q15, i32) 11735q31 __builtin_mips_shll_s_w (q31, imm0_31) 11736q31 __builtin_mips_shll_s_w (q31, i32) 11737v4i8 __builtin_mips_shrl_qb (v4i8, imm0_7) 11738v4i8 __builtin_mips_shrl_qb (v4i8, i32) 11739v2q15 __builtin_mips_shra_ph (v2q15, imm0_15) 11740v2q15 __builtin_mips_shra_ph (v2q15, i32) 11741v2q15 __builtin_mips_shra_r_ph (v2q15, imm0_15) 11742v2q15 __builtin_mips_shra_r_ph (v2q15, i32) 11743q31 __builtin_mips_shra_r_w (q31, imm0_31) 11744q31 __builtin_mips_shra_r_w (q31, i32) 11745v2q15 __builtin_mips_muleu_s_ph_qbl (v4i8, v2q15) 11746v2q15 __builtin_mips_muleu_s_ph_qbr (v4i8, v2q15) 11747v2q15 __builtin_mips_mulq_rs_ph (v2q15, v2q15) 11748q31 __builtin_mips_muleq_s_w_phl (v2q15, v2q15) 11749q31 __builtin_mips_muleq_s_w_phr (v2q15, v2q15) 11750a64 __builtin_mips_dpau_h_qbl (a64, v4i8, v4i8) 11751a64 __builtin_mips_dpau_h_qbr (a64, v4i8, v4i8) 11752a64 __builtin_mips_dpsu_h_qbl (a64, v4i8, v4i8) 11753a64 __builtin_mips_dpsu_h_qbr (a64, v4i8, v4i8) 11754a64 __builtin_mips_dpaq_s_w_ph (a64, v2q15, v2q15) 11755a64 __builtin_mips_dpaq_sa_l_w (a64, q31, q31) 11756a64 __builtin_mips_dpsq_s_w_ph (a64, v2q15, v2q15) 11757a64 __builtin_mips_dpsq_sa_l_w (a64, q31, q31) 11758a64 __builtin_mips_mulsaq_s_w_ph (a64, v2q15, v2q15) 11759a64 __builtin_mips_maq_s_w_phl (a64, v2q15, v2q15) 11760a64 __builtin_mips_maq_s_w_phr (a64, v2q15, v2q15) 11761a64 __builtin_mips_maq_sa_w_phl (a64, v2q15, v2q15) 11762a64 __builtin_mips_maq_sa_w_phr (a64, v2q15, v2q15) 11763i32 __builtin_mips_bitrev (i32) 11764i32 __builtin_mips_insv (i32, i32) 11765v4i8 __builtin_mips_repl_qb (imm0_255) 11766v4i8 __builtin_mips_repl_qb (i32) 11767v2q15 __builtin_mips_repl_ph (imm_n512_511) 11768v2q15 __builtin_mips_repl_ph (i32) 11769void __builtin_mips_cmpu_eq_qb (v4i8, v4i8) 11770void __builtin_mips_cmpu_lt_qb (v4i8, v4i8) 11771void __builtin_mips_cmpu_le_qb (v4i8, v4i8) 11772i32 __builtin_mips_cmpgu_eq_qb (v4i8, v4i8) 11773i32 __builtin_mips_cmpgu_lt_qb (v4i8, v4i8) 11774i32 __builtin_mips_cmpgu_le_qb (v4i8, v4i8) 11775void __builtin_mips_cmp_eq_ph (v2q15, v2q15) 11776void __builtin_mips_cmp_lt_ph (v2q15, v2q15) 11777void __builtin_mips_cmp_le_ph (v2q15, v2q15) 11778v4i8 __builtin_mips_pick_qb (v4i8, v4i8) 11779v2q15 __builtin_mips_pick_ph (v2q15, v2q15) 11780v2q15 __builtin_mips_packrl_ph (v2q15, v2q15) 11781i32 __builtin_mips_extr_w (a64, imm0_31) 11782i32 __builtin_mips_extr_w (a64, i32) 11783i32 __builtin_mips_extr_r_w (a64, imm0_31) 11784i32 __builtin_mips_extr_s_h (a64, i32) 11785i32 __builtin_mips_extr_rs_w (a64, imm0_31) 11786i32 __builtin_mips_extr_rs_w (a64, i32) 11787i32 __builtin_mips_extr_s_h (a64, imm0_31) 11788i32 __builtin_mips_extr_r_w (a64, i32) 11789i32 __builtin_mips_extp (a64, imm0_31) 11790i32 __builtin_mips_extp (a64, i32) 11791i32 __builtin_mips_extpdp (a64, imm0_31) 11792i32 __builtin_mips_extpdp (a64, i32) 11793a64 __builtin_mips_shilo (a64, imm_n32_31) 11794a64 __builtin_mips_shilo (a64, i32) 11795a64 __builtin_mips_mthlip (a64, i32) 11796void __builtin_mips_wrdsp (i32, imm0_63) 11797i32 __builtin_mips_rddsp (imm0_63) 11798i32 __builtin_mips_lbux (void *, i32) 11799i32 __builtin_mips_lhx (void *, i32) 11800i32 __builtin_mips_lwx (void *, i32) 11801a64 __builtin_mips_ldx (void *, i32) [MIPS64 only] 11802i32 __builtin_mips_bposge32 (void) 11803a64 __builtin_mips_madd (a64, i32, i32); 11804a64 __builtin_mips_maddu (a64, ui32, ui32); 11805a64 __builtin_mips_msub (a64, i32, i32); 11806a64 __builtin_mips_msubu (a64, ui32, ui32); 11807a64 __builtin_mips_mult (i32, i32); 11808a64 __builtin_mips_multu (ui32, ui32); 11809@end smallexample 11810 11811The following built-in functions map directly to a particular MIPS DSP REV 2 11812instruction. Please refer to the architecture specification 11813for details on what each instruction does. 11814 11815@smallexample 11816v4q7 __builtin_mips_absq_s_qb (v4q7); 11817v2i16 __builtin_mips_addu_ph (v2i16, v2i16); 11818v2i16 __builtin_mips_addu_s_ph (v2i16, v2i16); 11819v4i8 __builtin_mips_adduh_qb (v4i8, v4i8); 11820v4i8 __builtin_mips_adduh_r_qb (v4i8, v4i8); 11821i32 __builtin_mips_append (i32, i32, imm0_31); 11822i32 __builtin_mips_balign (i32, i32, imm0_3); 11823i32 __builtin_mips_cmpgdu_eq_qb (v4i8, v4i8); 11824i32 __builtin_mips_cmpgdu_lt_qb (v4i8, v4i8); 11825i32 __builtin_mips_cmpgdu_le_qb (v4i8, v4i8); 11826a64 __builtin_mips_dpa_w_ph (a64, v2i16, v2i16); 11827a64 __builtin_mips_dps_w_ph (a64, v2i16, v2i16); 11828v2i16 __builtin_mips_mul_ph (v2i16, v2i16); 11829v2i16 __builtin_mips_mul_s_ph (v2i16, v2i16); 11830q31 __builtin_mips_mulq_rs_w (q31, q31); 11831v2q15 __builtin_mips_mulq_s_ph (v2q15, v2q15); 11832q31 __builtin_mips_mulq_s_w (q31, q31); 11833a64 __builtin_mips_mulsa_w_ph (a64, v2i16, v2i16); 11834v4i8 __builtin_mips_precr_qb_ph (v2i16, v2i16); 11835v2i16 __builtin_mips_precr_sra_ph_w (i32, i32, imm0_31); 11836v2i16 __builtin_mips_precr_sra_r_ph_w (i32, i32, imm0_31); 11837i32 __builtin_mips_prepend (i32, i32, imm0_31); 11838v4i8 __builtin_mips_shra_qb (v4i8, imm0_7); 11839v4i8 __builtin_mips_shra_r_qb (v4i8, imm0_7); 11840v4i8 __builtin_mips_shra_qb (v4i8, i32); 11841v4i8 __builtin_mips_shra_r_qb (v4i8, i32); 11842v2i16 __builtin_mips_shrl_ph (v2i16, imm0_15); 11843v2i16 __builtin_mips_shrl_ph (v2i16, i32); 11844v2i16 __builtin_mips_subu_ph (v2i16, v2i16); 11845v2i16 __builtin_mips_subu_s_ph (v2i16, v2i16); 11846v4i8 __builtin_mips_subuh_qb (v4i8, v4i8); 11847v4i8 __builtin_mips_subuh_r_qb (v4i8, v4i8); 11848v2q15 __builtin_mips_addqh_ph (v2q15, v2q15); 11849v2q15 __builtin_mips_addqh_r_ph (v2q15, v2q15); 11850q31 __builtin_mips_addqh_w (q31, q31); 11851q31 __builtin_mips_addqh_r_w (q31, q31); 11852v2q15 __builtin_mips_subqh_ph (v2q15, v2q15); 11853v2q15 __builtin_mips_subqh_r_ph (v2q15, v2q15); 11854q31 __builtin_mips_subqh_w (q31, q31); 11855q31 __builtin_mips_subqh_r_w (q31, q31); 11856a64 __builtin_mips_dpax_w_ph (a64, v2i16, v2i16); 11857a64 __builtin_mips_dpsx_w_ph (a64, v2i16, v2i16); 11858a64 __builtin_mips_dpaqx_s_w_ph (a64, v2q15, v2q15); 11859a64 __builtin_mips_dpaqx_sa_w_ph (a64, v2q15, v2q15); 11860a64 __builtin_mips_dpsqx_s_w_ph (a64, v2q15, v2q15); 11861a64 __builtin_mips_dpsqx_sa_w_ph (a64, v2q15, v2q15); 11862@end smallexample 11863 11864 11865@node MIPS Paired-Single Support 11866@subsection MIPS Paired-Single Support 11867 11868The MIPS64 architecture includes a number of instructions that 11869operate on pairs of single-precision floating-point values. 11870Each pair is packed into a 64-bit floating-point register, 11871with one element being designated the ``upper half'' and 11872the other being designated the ``lower half''. 11873 11874GCC supports paired-single operations using both the generic 11875vector extensions (@pxref{Vector Extensions}) and a collection of 11876MIPS-specific built-in functions. Both kinds of support are 11877enabled by the @option{-mpaired-single} command-line option. 11878 11879The vector type associated with paired-single values is usually 11880called @code{v2sf}. It can be defined in C as follows: 11881 11882@smallexample 11883typedef float v2sf __attribute__ ((vector_size (8))); 11884@end smallexample 11885 11886@code{v2sf} values are initialized in the same way as aggregates. 11887For example: 11888 11889@smallexample 11890v2sf a = @{1.5, 9.1@}; 11891v2sf b; 11892float e, f; 11893b = (v2sf) @{e, f@}; 11894@end smallexample 11895 11896@emph{Note:} The CPU's endianness determines which value is stored in 11897the upper half of a register and which value is stored in the lower half. 11898On little-endian targets, the first value is the lower one and the second 11899value is the upper one. The opposite order applies to big-endian targets. 11900For example, the code above sets the lower half of @code{a} to 11901@code{1.5} on little-endian targets and @code{9.1} on big-endian targets. 11902 11903@node MIPS Loongson Built-in Functions 11904@subsection MIPS Loongson Built-in Functions 11905 11906GCC provides intrinsics to access the SIMD instructions provided by the 11907ST Microelectronics Loongson-2E and -2F processors. These intrinsics, 11908available after inclusion of the @code{loongson.h} header file, 11909operate on the following 64-bit vector types: 11910 11911@itemize 11912@item @code{uint8x8_t}, a vector of eight unsigned 8-bit integers; 11913@item @code{uint16x4_t}, a vector of four unsigned 16-bit integers; 11914@item @code{uint32x2_t}, a vector of two unsigned 32-bit integers; 11915@item @code{int8x8_t}, a vector of eight signed 8-bit integers; 11916@item @code{int16x4_t}, a vector of four signed 16-bit integers; 11917@item @code{int32x2_t}, a vector of two signed 32-bit integers. 11918@end itemize 11919 11920The intrinsics provided are listed below; each is named after the 11921machine instruction to which it corresponds, with suffixes added as 11922appropriate to distinguish intrinsics that expand to the same machine 11923instruction yet have different argument types. Refer to the architecture 11924documentation for a description of the functionality of each 11925instruction. 11926 11927@smallexample 11928int16x4_t packsswh (int32x2_t s, int32x2_t t); 11929int8x8_t packsshb (int16x4_t s, int16x4_t t); 11930uint8x8_t packushb (uint16x4_t s, uint16x4_t t); 11931uint32x2_t paddw_u (uint32x2_t s, uint32x2_t t); 11932uint16x4_t paddh_u (uint16x4_t s, uint16x4_t t); 11933uint8x8_t paddb_u (uint8x8_t s, uint8x8_t t); 11934int32x2_t paddw_s (int32x2_t s, int32x2_t t); 11935int16x4_t paddh_s (int16x4_t s, int16x4_t t); 11936int8x8_t paddb_s (int8x8_t s, int8x8_t t); 11937uint64_t paddd_u (uint64_t s, uint64_t t); 11938int64_t paddd_s (int64_t s, int64_t t); 11939int16x4_t paddsh (int16x4_t s, int16x4_t t); 11940int8x8_t paddsb (int8x8_t s, int8x8_t t); 11941uint16x4_t paddush (uint16x4_t s, uint16x4_t t); 11942uint8x8_t paddusb (uint8x8_t s, uint8x8_t t); 11943uint64_t pandn_ud (uint64_t s, uint64_t t); 11944uint32x2_t pandn_uw (uint32x2_t s, uint32x2_t t); 11945uint16x4_t pandn_uh (uint16x4_t s, uint16x4_t t); 11946uint8x8_t pandn_ub (uint8x8_t s, uint8x8_t t); 11947int64_t pandn_sd (int64_t s, int64_t t); 11948int32x2_t pandn_sw (int32x2_t s, int32x2_t t); 11949int16x4_t pandn_sh (int16x4_t s, int16x4_t t); 11950int8x8_t pandn_sb (int8x8_t s, int8x8_t t); 11951uint16x4_t pavgh (uint16x4_t s, uint16x4_t t); 11952uint8x8_t pavgb (uint8x8_t s, uint8x8_t t); 11953uint32x2_t pcmpeqw_u (uint32x2_t s, uint32x2_t t); 11954uint16x4_t pcmpeqh_u (uint16x4_t s, uint16x4_t t); 11955uint8x8_t pcmpeqb_u (uint8x8_t s, uint8x8_t t); 11956int32x2_t pcmpeqw_s (int32x2_t s, int32x2_t t); 11957int16x4_t pcmpeqh_s (int16x4_t s, int16x4_t t); 11958int8x8_t pcmpeqb_s (int8x8_t s, int8x8_t t); 11959uint32x2_t pcmpgtw_u (uint32x2_t s, uint32x2_t t); 11960uint16x4_t pcmpgth_u (uint16x4_t s, uint16x4_t t); 11961uint8x8_t pcmpgtb_u (uint8x8_t s, uint8x8_t t); 11962int32x2_t pcmpgtw_s (int32x2_t s, int32x2_t t); 11963int16x4_t pcmpgth_s (int16x4_t s, int16x4_t t); 11964int8x8_t pcmpgtb_s (int8x8_t s, int8x8_t t); 11965uint16x4_t pextrh_u (uint16x4_t s, int field); 11966int16x4_t pextrh_s (int16x4_t s, int field); 11967uint16x4_t pinsrh_0_u (uint16x4_t s, uint16x4_t t); 11968uint16x4_t pinsrh_1_u (uint16x4_t s, uint16x4_t t); 11969uint16x4_t pinsrh_2_u (uint16x4_t s, uint16x4_t t); 11970uint16x4_t pinsrh_3_u (uint16x4_t s, uint16x4_t t); 11971int16x4_t pinsrh_0_s (int16x4_t s, int16x4_t t); 11972int16x4_t pinsrh_1_s (int16x4_t s, int16x4_t t); 11973int16x4_t pinsrh_2_s (int16x4_t s, int16x4_t t); 11974int16x4_t pinsrh_3_s (int16x4_t s, int16x4_t t); 11975int32x2_t pmaddhw (int16x4_t s, int16x4_t t); 11976int16x4_t pmaxsh (int16x4_t s, int16x4_t t); 11977uint8x8_t pmaxub (uint8x8_t s, uint8x8_t t); 11978int16x4_t pminsh (int16x4_t s, int16x4_t t); 11979uint8x8_t pminub (uint8x8_t s, uint8x8_t t); 11980uint8x8_t pmovmskb_u (uint8x8_t s); 11981int8x8_t pmovmskb_s (int8x8_t s); 11982uint16x4_t pmulhuh (uint16x4_t s, uint16x4_t t); 11983int16x4_t pmulhh (int16x4_t s, int16x4_t t); 11984int16x4_t pmullh (int16x4_t s, int16x4_t t); 11985int64_t pmuluw (uint32x2_t s, uint32x2_t t); 11986uint8x8_t pasubub (uint8x8_t s, uint8x8_t t); 11987uint16x4_t biadd (uint8x8_t s); 11988uint16x4_t psadbh (uint8x8_t s, uint8x8_t t); 11989uint16x4_t pshufh_u (uint16x4_t dest, uint16x4_t s, uint8_t order); 11990int16x4_t pshufh_s (int16x4_t dest, int16x4_t s, uint8_t order); 11991uint16x4_t psllh_u (uint16x4_t s, uint8_t amount); 11992int16x4_t psllh_s (int16x4_t s, uint8_t amount); 11993uint32x2_t psllw_u (uint32x2_t s, uint8_t amount); 11994int32x2_t psllw_s (int32x2_t s, uint8_t amount); 11995uint16x4_t psrlh_u (uint16x4_t s, uint8_t amount); 11996int16x4_t psrlh_s (int16x4_t s, uint8_t amount); 11997uint32x2_t psrlw_u (uint32x2_t s, uint8_t amount); 11998int32x2_t psrlw_s (int32x2_t s, uint8_t amount); 11999uint16x4_t psrah_u (uint16x4_t s, uint8_t amount); 12000int16x4_t psrah_s (int16x4_t s, uint8_t amount); 12001uint32x2_t psraw_u (uint32x2_t s, uint8_t amount); 12002int32x2_t psraw_s (int32x2_t s, uint8_t amount); 12003uint32x2_t psubw_u (uint32x2_t s, uint32x2_t t); 12004uint16x4_t psubh_u (uint16x4_t s, uint16x4_t t); 12005uint8x8_t psubb_u (uint8x8_t s, uint8x8_t t); 12006int32x2_t psubw_s (int32x2_t s, int32x2_t t); 12007int16x4_t psubh_s (int16x4_t s, int16x4_t t); 12008int8x8_t psubb_s (int8x8_t s, int8x8_t t); 12009uint64_t psubd_u (uint64_t s, uint64_t t); 12010int64_t psubd_s (int64_t s, int64_t t); 12011int16x4_t psubsh (int16x4_t s, int16x4_t t); 12012int8x8_t psubsb (int8x8_t s, int8x8_t t); 12013uint16x4_t psubush (uint16x4_t s, uint16x4_t t); 12014uint8x8_t psubusb (uint8x8_t s, uint8x8_t t); 12015uint32x2_t punpckhwd_u (uint32x2_t s, uint32x2_t t); 12016uint16x4_t punpckhhw_u (uint16x4_t s, uint16x4_t t); 12017uint8x8_t punpckhbh_u (uint8x8_t s, uint8x8_t t); 12018int32x2_t punpckhwd_s (int32x2_t s, int32x2_t t); 12019int16x4_t punpckhhw_s (int16x4_t s, int16x4_t t); 12020int8x8_t punpckhbh_s (int8x8_t s, int8x8_t t); 12021uint32x2_t punpcklwd_u (uint32x2_t s, uint32x2_t t); 12022uint16x4_t punpcklhw_u (uint16x4_t s, uint16x4_t t); 12023uint8x8_t punpcklbh_u (uint8x8_t s, uint8x8_t t); 12024int32x2_t punpcklwd_s (int32x2_t s, int32x2_t t); 12025int16x4_t punpcklhw_s (int16x4_t s, int16x4_t t); 12026int8x8_t punpcklbh_s (int8x8_t s, int8x8_t t); 12027@end smallexample 12028 12029@menu 12030* Paired-Single Arithmetic:: 12031* Paired-Single Built-in Functions:: 12032* MIPS-3D Built-in Functions:: 12033@end menu 12034 12035@node Paired-Single Arithmetic 12036@subsubsection Paired-Single Arithmetic 12037 12038The table below lists the @code{v2sf} operations for which hardware 12039support exists. @code{a}, @code{b} and @code{c} are @code{v2sf} 12040values and @code{x} is an integral value. 12041 12042@multitable @columnfractions .50 .50 12043@item C code @tab MIPS instruction 12044@item @code{a + b} @tab @code{add.ps} 12045@item @code{a - b} @tab @code{sub.ps} 12046@item @code{-a} @tab @code{neg.ps} 12047@item @code{a * b} @tab @code{mul.ps} 12048@item @code{a * b + c} @tab @code{madd.ps} 12049@item @code{a * b - c} @tab @code{msub.ps} 12050@item @code{-(a * b + c)} @tab @code{nmadd.ps} 12051@item @code{-(a * b - c)} @tab @code{nmsub.ps} 12052@item @code{x ? a : b} @tab @code{movn.ps}/@code{movz.ps} 12053@end multitable 12054 12055Note that the multiply-accumulate instructions can be disabled 12056using the command-line option @code{-mno-fused-madd}. 12057 12058@node Paired-Single Built-in Functions 12059@subsubsection Paired-Single Built-in Functions 12060 12061The following paired-single functions map directly to a particular 12062MIPS instruction. Please refer to the architecture specification 12063for details on what each instruction does. 12064 12065@table @code 12066@item v2sf __builtin_mips_pll_ps (v2sf, v2sf) 12067Pair lower lower (@code{pll.ps}). 12068 12069@item v2sf __builtin_mips_pul_ps (v2sf, v2sf) 12070Pair upper lower (@code{pul.ps}). 12071 12072@item v2sf __builtin_mips_plu_ps (v2sf, v2sf) 12073Pair lower upper (@code{plu.ps}). 12074 12075@item v2sf __builtin_mips_puu_ps (v2sf, v2sf) 12076Pair upper upper (@code{puu.ps}). 12077 12078@item v2sf __builtin_mips_cvt_ps_s (float, float) 12079Convert pair to paired single (@code{cvt.ps.s}). 12080 12081@item float __builtin_mips_cvt_s_pl (v2sf) 12082Convert pair lower to single (@code{cvt.s.pl}). 12083 12084@item float __builtin_mips_cvt_s_pu (v2sf) 12085Convert pair upper to single (@code{cvt.s.pu}). 12086 12087@item v2sf __builtin_mips_abs_ps (v2sf) 12088Absolute value (@code{abs.ps}). 12089 12090@item v2sf __builtin_mips_alnv_ps (v2sf, v2sf, int) 12091Align variable (@code{alnv.ps}). 12092 12093@emph{Note:} The value of the third parameter must be 0 or 4 12094modulo 8, otherwise the result is unpredictable. Please read the 12095instruction description for details. 12096@end table 12097 12098The following multi-instruction functions are also available. 12099In each case, @var{cond} can be any of the 16 floating-point conditions: 12100@code{f}, @code{un}, @code{eq}, @code{ueq}, @code{olt}, @code{ult}, 12101@code{ole}, @code{ule}, @code{sf}, @code{ngle}, @code{seq}, @code{ngl}, 12102@code{lt}, @code{nge}, @code{le} or @code{ngt}. 12103 12104@table @code 12105@item v2sf __builtin_mips_movt_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d}) 12106@itemx v2sf __builtin_mips_movf_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d}) 12107Conditional move based on floating-point comparison (@code{c.@var{cond}.ps}, 12108@code{movt.ps}/@code{movf.ps}). 12109 12110The @code{movt} functions return the value @var{x} computed by: 12111 12112@smallexample 12113c.@var{cond}.ps @var{cc},@var{a},@var{b} 12114mov.ps @var{x},@var{c} 12115movt.ps @var{x},@var{d},@var{cc} 12116@end smallexample 12117 12118The @code{movf} functions are similar but use @code{movf.ps} instead 12119of @code{movt.ps}. 12120 12121@item int __builtin_mips_upper_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}) 12122@itemx int __builtin_mips_lower_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}) 12123Comparison of two paired-single values (@code{c.@var{cond}.ps}, 12124@code{bc1t}/@code{bc1f}). 12125 12126These functions compare @var{a} and @var{b} using @code{c.@var{cond}.ps} 12127and return either the upper or lower half of the result. For example: 12128 12129@smallexample 12130v2sf a, b; 12131if (__builtin_mips_upper_c_eq_ps (a, b)) 12132 upper_halves_are_equal (); 12133else 12134 upper_halves_are_unequal (); 12135 12136if (__builtin_mips_lower_c_eq_ps (a, b)) 12137 lower_halves_are_equal (); 12138else 12139 lower_halves_are_unequal (); 12140@end smallexample 12141@end table 12142 12143@node MIPS-3D Built-in Functions 12144@subsubsection MIPS-3D Built-in Functions 12145 12146The MIPS-3D Application-Specific Extension (ASE) includes additional 12147paired-single instructions that are designed to improve the performance 12148of 3D graphics operations. Support for these instructions is controlled 12149by the @option{-mips3d} command-line option. 12150 12151The functions listed below map directly to a particular MIPS-3D 12152instruction. Please refer to the architecture specification for 12153more details on what each instruction does. 12154 12155@table @code 12156@item v2sf __builtin_mips_addr_ps (v2sf, v2sf) 12157Reduction add (@code{addr.ps}). 12158 12159@item v2sf __builtin_mips_mulr_ps (v2sf, v2sf) 12160Reduction multiply (@code{mulr.ps}). 12161 12162@item v2sf __builtin_mips_cvt_pw_ps (v2sf) 12163Convert paired single to paired word (@code{cvt.pw.ps}). 12164 12165@item v2sf __builtin_mips_cvt_ps_pw (v2sf) 12166Convert paired word to paired single (@code{cvt.ps.pw}). 12167 12168@item float __builtin_mips_recip1_s (float) 12169@itemx double __builtin_mips_recip1_d (double) 12170@itemx v2sf __builtin_mips_recip1_ps (v2sf) 12171Reduced-precision reciprocal (sequence step 1) (@code{recip1.@var{fmt}}). 12172 12173@item float __builtin_mips_recip2_s (float, float) 12174@itemx double __builtin_mips_recip2_d (double, double) 12175@itemx v2sf __builtin_mips_recip2_ps (v2sf, v2sf) 12176Reduced-precision reciprocal (sequence step 2) (@code{recip2.@var{fmt}}). 12177 12178@item float __builtin_mips_rsqrt1_s (float) 12179@itemx double __builtin_mips_rsqrt1_d (double) 12180@itemx v2sf __builtin_mips_rsqrt1_ps (v2sf) 12181Reduced-precision reciprocal square root (sequence step 1) 12182(@code{rsqrt1.@var{fmt}}). 12183 12184@item float __builtin_mips_rsqrt2_s (float, float) 12185@itemx double __builtin_mips_rsqrt2_d (double, double) 12186@itemx v2sf __builtin_mips_rsqrt2_ps (v2sf, v2sf) 12187Reduced-precision reciprocal square root (sequence step 2) 12188(@code{rsqrt2.@var{fmt}}). 12189@end table 12190 12191The following multi-instruction functions are also available. 12192In each case, @var{cond} can be any of the 16 floating-point conditions: 12193@code{f}, @code{un}, @code{eq}, @code{ueq}, @code{olt}, @code{ult}, 12194@code{ole}, @code{ule}, @code{sf}, @code{ngle}, @code{seq}, 12195@code{ngl}, @code{lt}, @code{nge}, @code{le} or @code{ngt}. 12196 12197@table @code 12198@item int __builtin_mips_cabs_@var{cond}_s (float @var{a}, float @var{b}) 12199@itemx int __builtin_mips_cabs_@var{cond}_d (double @var{a}, double @var{b}) 12200Absolute comparison of two scalar values (@code{cabs.@var{cond}.@var{fmt}}, 12201@code{bc1t}/@code{bc1f}). 12202 12203These functions compare @var{a} and @var{b} using @code{cabs.@var{cond}.s} 12204or @code{cabs.@var{cond}.d} and return the result as a boolean value. 12205For example: 12206 12207@smallexample 12208float a, b; 12209if (__builtin_mips_cabs_eq_s (a, b)) 12210 true (); 12211else 12212 false (); 12213@end smallexample 12214 12215@item int __builtin_mips_upper_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}) 12216@itemx int __builtin_mips_lower_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}) 12217Absolute comparison of two paired-single values (@code{cabs.@var{cond}.ps}, 12218@code{bc1t}/@code{bc1f}). 12219 12220These functions compare @var{a} and @var{b} using @code{cabs.@var{cond}.ps} 12221and return either the upper or lower half of the result. For example: 12222 12223@smallexample 12224v2sf a, b; 12225if (__builtin_mips_upper_cabs_eq_ps (a, b)) 12226 upper_halves_are_equal (); 12227else 12228 upper_halves_are_unequal (); 12229 12230if (__builtin_mips_lower_cabs_eq_ps (a, b)) 12231 lower_halves_are_equal (); 12232else 12233 lower_halves_are_unequal (); 12234@end smallexample 12235 12236@item v2sf __builtin_mips_movt_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d}) 12237@itemx v2sf __builtin_mips_movf_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d}) 12238Conditional move based on absolute comparison (@code{cabs.@var{cond}.ps}, 12239@code{movt.ps}/@code{movf.ps}). 12240 12241The @code{movt} functions return the value @var{x} computed by: 12242 12243@smallexample 12244cabs.@var{cond}.ps @var{cc},@var{a},@var{b} 12245mov.ps @var{x},@var{c} 12246movt.ps @var{x},@var{d},@var{cc} 12247@end smallexample 12248 12249The @code{movf} functions are similar but use @code{movf.ps} instead 12250of @code{movt.ps}. 12251 12252@item int __builtin_mips_any_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}) 12253@itemx int __builtin_mips_all_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}) 12254@itemx int __builtin_mips_any_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}) 12255@itemx int __builtin_mips_all_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}) 12256Comparison of two paired-single values 12257(@code{c.@var{cond}.ps}/@code{cabs.@var{cond}.ps}, 12258@code{bc1any2t}/@code{bc1any2f}). 12259 12260These functions compare @var{a} and @var{b} using @code{c.@var{cond}.ps} 12261or @code{cabs.@var{cond}.ps}. The @code{any} forms return true if either 12262result is true and the @code{all} forms return true if both results are true. 12263For example: 12264 12265@smallexample 12266v2sf a, b; 12267if (__builtin_mips_any_c_eq_ps (a, b)) 12268 one_is_true (); 12269else 12270 both_are_false (); 12271 12272if (__builtin_mips_all_c_eq_ps (a, b)) 12273 both_are_true (); 12274else 12275 one_is_false (); 12276@end smallexample 12277 12278@item int __builtin_mips_any_c_@var{cond}_4s (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d}) 12279@itemx int __builtin_mips_all_c_@var{cond}_4s (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d}) 12280@itemx int __builtin_mips_any_cabs_@var{cond}_4s (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d}) 12281@itemx int __builtin_mips_all_cabs_@var{cond}_4s (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d}) 12282Comparison of four paired-single values 12283(@code{c.@var{cond}.ps}/@code{cabs.@var{cond}.ps}, 12284@code{bc1any4t}/@code{bc1any4f}). 12285 12286These functions use @code{c.@var{cond}.ps} or @code{cabs.@var{cond}.ps} 12287to compare @var{a} with @var{b} and to compare @var{c} with @var{d}. 12288The @code{any} forms return true if any of the four results are true 12289and the @code{all} forms return true if all four results are true. 12290For example: 12291 12292@smallexample 12293v2sf a, b, c, d; 12294if (__builtin_mips_any_c_eq_4s (a, b, c, d)) 12295 some_are_true (); 12296else 12297 all_are_false (); 12298 12299if (__builtin_mips_all_c_eq_4s (a, b, c, d)) 12300 all_are_true (); 12301else 12302 some_are_false (); 12303@end smallexample 12304@end table 12305 12306@node Other MIPS Built-in Functions 12307@subsection Other MIPS Built-in Functions 12308 12309GCC provides other MIPS-specific built-in functions: 12310 12311@table @code 12312@item void __builtin_mips_cache (int @var{op}, const volatile void *@var{addr}) 12313Insert a @samp{cache} instruction with operands @var{op} and @var{addr}. 12314GCC defines the preprocessor macro @code{___GCC_HAVE_BUILTIN_MIPS_CACHE} 12315when this function is available. 12316 12317@item unsigned int __builtin_mips_get_fcsr (void) 12318@itemx void __builtin_mips_set_fcsr (unsigned int @var{value}) 12319Get and set the contents of the floating-point control and status register 12320(FPU control register 31). These functions are only available in hard-float 12321code but can be called in both MIPS16 and non-MIPS16 contexts. 12322 12323@code{__builtin_mips_set_fcsr} can be used to change any bit of the 12324register except the condition codes, which GCC assumes are preserved. 12325@end table 12326 12327@node MSP430 Built-in Functions 12328@subsection MSP430 Built-in Functions 12329 12330GCC provides a couple of special builtin functions to aid in the 12331writing of interrupt handlers in C. 12332 12333@table @code 12334@item __bic_SR_register_on_exit (int @var{mask}) 12335This clears the indicated bits in the saved copy of the status register 12336currently residing on the stack. This only works inside interrupt 12337handlers and the changes to the status register will only take affect 12338once the handler returns. 12339 12340@item __bis_SR_register_on_exit (int @var{mask}) 12341This sets the indicated bits in the saved copy of the status register 12342currently residing on the stack. This only works inside interrupt 12343handlers and the changes to the status register will only take affect 12344once the handler returns. 12345 12346@item __delay_cycles (long long @var{cycles}) 12347This inserts an instruction sequence that takes exactly @var{cycles} 12348cycles (between 0 and about 17E9) to complete. The inserted sequence 12349may use jumps, loops, or no-ops, and does not interfere with any other 12350instructions. Note that @var{cycles} must be a compile-time constant 12351integer - that is, you must pass a number, not a variable that may be 12352optimized to a constant later. The number of cycles delayed by this 12353builtin is exact. 12354@end table 12355 12356@node NDS32 Built-in Functions 12357@subsection NDS32 Built-in Functions 12358 12359These built-in functions are available for the NDS32 target: 12360 12361@deftypefn {Built-in Function} void __builtin_nds32_isync (int *@var{addr}) 12362Insert an ISYNC instruction into the instruction stream where 12363@var{addr} is an instruction address for serialization. 12364@end deftypefn 12365 12366@deftypefn {Built-in Function} void __builtin_nds32_isb (void) 12367Insert an ISB instruction into the instruction stream. 12368@end deftypefn 12369 12370@deftypefn {Built-in Function} int __builtin_nds32_mfsr (int @var{sr}) 12371Return the content of a system register which is mapped by @var{sr}. 12372@end deftypefn 12373 12374@deftypefn {Built-in Function} int __builtin_nds32_mfusr (int @var{usr}) 12375Return the content of a user space register which is mapped by @var{usr}. 12376@end deftypefn 12377 12378@deftypefn {Built-in Function} void __builtin_nds32_mtsr (int @var{value}, int @var{sr}) 12379Move the @var{value} to a system register which is mapped by @var{sr}. 12380@end deftypefn 12381 12382@deftypefn {Built-in Function} void __builtin_nds32_mtusr (int @var{value}, int @var{usr}) 12383Move the @var{value} to a user space register which is mapped by @var{usr}. 12384@end deftypefn 12385 12386@deftypefn {Built-in Function} void __builtin_nds32_setgie_en (void) 12387Enable global interrupt. 12388@end deftypefn 12389 12390@deftypefn {Built-in Function} void __builtin_nds32_setgie_dis (void) 12391Disable global interrupt. 12392@end deftypefn 12393 12394@node picoChip Built-in Functions 12395@subsection picoChip Built-in Functions 12396 12397GCC provides an interface to selected machine instructions from the 12398picoChip instruction set. 12399 12400@table @code 12401@item int __builtin_sbc (int @var{value}) 12402Sign bit count. Return the number of consecutive bits in @var{value} 12403that have the same value as the sign bit. The result is the number of 12404leading sign bits minus one, giving the number of redundant sign bits in 12405@var{value}. 12406 12407@item int __builtin_byteswap (int @var{value}) 12408Byte swap. Return the result of swapping the upper and lower bytes of 12409@var{value}. 12410 12411@item int __builtin_brev (int @var{value}) 12412Bit reversal. Return the result of reversing the bits in 12413@var{value}. Bit 15 is swapped with bit 0, bit 14 is swapped with bit 1, 12414and so on. 12415 12416@item int __builtin_adds (int @var{x}, int @var{y}) 12417Saturating addition. Return the result of adding @var{x} and @var{y}, 12418storing the value 32767 if the result overflows. 12419 12420@item int __builtin_subs (int @var{x}, int @var{y}) 12421Saturating subtraction. Return the result of subtracting @var{y} from 12422@var{x}, storing the value @minus{}32768 if the result overflows. 12423 12424@item void __builtin_halt (void) 12425Halt. The processor stops execution. This built-in is useful for 12426implementing assertions. 12427 12428@end table 12429 12430@node PowerPC Built-in Functions 12431@subsection PowerPC Built-in Functions 12432 12433These built-in functions are available for the PowerPC family of 12434processors: 12435@smallexample 12436float __builtin_recipdivf (float, float); 12437float __builtin_rsqrtf (float); 12438double __builtin_recipdiv (double, double); 12439double __builtin_rsqrt (double); 12440uint64_t __builtin_ppc_get_timebase (); 12441unsigned long __builtin_ppc_mftb (); 12442double __builtin_unpack_longdouble (long double, int); 12443long double __builtin_pack_longdouble (double, double); 12444@end smallexample 12445 12446The @code{vec_rsqrt}, @code{__builtin_rsqrt}, and 12447@code{__builtin_rsqrtf} functions generate multiple instructions to 12448implement the reciprocal sqrt functionality using reciprocal sqrt 12449estimate instructions. 12450 12451The @code{__builtin_recipdiv}, and @code{__builtin_recipdivf} 12452functions generate multiple instructions to implement division using 12453the reciprocal estimate instructions. 12454 12455The @code{__builtin_ppc_get_timebase} and @code{__builtin_ppc_mftb} 12456functions generate instructions to read the Time Base Register. The 12457@code{__builtin_ppc_get_timebase} function may generate multiple 12458instructions and always returns the 64 bits of the Time Base Register. 12459The @code{__builtin_ppc_mftb} function always generates one instruction and 12460returns the Time Base Register value as an unsigned long, throwing away 12461the most significant word on 32-bit environments. 12462 12463The following built-in functions are available for the PowerPC family 12464of processors, starting with ISA 2.06 or later (@option{-mcpu=power7} 12465or @option{-mpopcntd}): 12466@smallexample 12467long __builtin_bpermd (long, long); 12468int __builtin_divwe (int, int); 12469int __builtin_divweo (int, int); 12470unsigned int __builtin_divweu (unsigned int, unsigned int); 12471unsigned int __builtin_divweuo (unsigned int, unsigned int); 12472long __builtin_divde (long, long); 12473long __builtin_divdeo (long, long); 12474unsigned long __builtin_divdeu (unsigned long, unsigned long); 12475unsigned long __builtin_divdeuo (unsigned long, unsigned long); 12476unsigned int cdtbcd (unsigned int); 12477unsigned int cbcdtd (unsigned int); 12478unsigned int addg6s (unsigned int, unsigned int); 12479@end smallexample 12480 12481The @code{__builtin_divde}, @code{__builtin_divdeo}, 12482@code{__builtin_divdeu}, @code{__builtin_divdeou} functions require a 1248364-bit environment support ISA 2.06 or later. 12484 12485The following built-in functions are available for the PowerPC family 12486of processors when hardware decimal floating point 12487(@option{-mhard-dfp}) is available: 12488@smallexample 12489_Decimal64 __builtin_dxex (_Decimal64); 12490_Decimal128 __builtin_dxexq (_Decimal128); 12491_Decimal64 __builtin_ddedpd (int, _Decimal64); 12492_Decimal128 __builtin_ddedpdq (int, _Decimal128); 12493_Decimal64 __builtin_denbcd (int, _Decimal64); 12494_Decimal128 __builtin_denbcdq (int, _Decimal128); 12495_Decimal64 __builtin_diex (_Decimal64, _Decimal64); 12496_Decimal128 _builtin_diexq (_Decimal128, _Decimal128); 12497_Decimal64 __builtin_dscli (_Decimal64, int); 12498_Decimal128 __builtin_dscliq (_Decimal128, int); 12499_Decimal64 __builtin_dscri (_Decimal64, int); 12500_Decimal128 __builtin_dscriq (_Decimal128, int); 12501unsigned long long __builtin_unpack_dec128 (_Decimal128, int); 12502_Decimal128 __builtin_pack_dec128 (unsigned long long, unsigned long long); 12503@end smallexample 12504 12505The following built-in functions are available for the PowerPC family 12506of processors when the Vector Scalar (vsx) instruction set is 12507available: 12508@smallexample 12509unsigned long long __builtin_unpack_vector_int128 (vector __int128_t, int); 12510vector __int128_t __builtin_pack_vector_int128 (unsigned long long, 12511 unsigned long long); 12512@end smallexample 12513 12514@node PowerPC AltiVec/VSX Built-in Functions 12515@subsection PowerPC AltiVec Built-in Functions 12516 12517GCC provides an interface for the PowerPC family of processors to access 12518the AltiVec operations described in Motorola's AltiVec Programming 12519Interface Manual. The interface is made available by including 12520@code{<altivec.h>} and using @option{-maltivec} and 12521@option{-mabi=altivec}. The interface supports the following vector 12522types. 12523 12524@smallexample 12525vector unsigned char 12526vector signed char 12527vector bool char 12528 12529vector unsigned short 12530vector signed short 12531vector bool short 12532vector pixel 12533 12534vector unsigned int 12535vector signed int 12536vector bool int 12537vector float 12538@end smallexample 12539 12540If @option{-mvsx} is used the following additional vector types are 12541implemented. 12542 12543@smallexample 12544vector unsigned long 12545vector signed long 12546vector double 12547@end smallexample 12548 12549The long types are only implemented for 64-bit code generation, and 12550the long type is only used in the floating point/integer conversion 12551instructions. 12552 12553GCC's implementation of the high-level language interface available from 12554C and C++ code differs from Motorola's documentation in several ways. 12555 12556@itemize @bullet 12557 12558@item 12559A vector constant is a list of constant expressions within curly braces. 12560 12561@item 12562A vector initializer requires no cast if the vector constant is of the 12563same type as the variable it is initializing. 12564 12565@item 12566If @code{signed} or @code{unsigned} is omitted, the signedness of the 12567vector type is the default signedness of the base type. The default 12568varies depending on the operating system, so a portable program should 12569always specify the signedness. 12570 12571@item 12572Compiling with @option{-maltivec} adds keywords @code{__vector}, 12573@code{vector}, @code{__pixel}, @code{pixel}, @code{__bool} and 12574@code{bool}. When compiling ISO C, the context-sensitive substitution 12575of the keywords @code{vector}, @code{pixel} and @code{bool} is 12576disabled. To use them, you must include @code{<altivec.h>} instead. 12577 12578@item 12579GCC allows using a @code{typedef} name as the type specifier for a 12580vector type. 12581 12582@item 12583For C, overloaded functions are implemented with macros so the following 12584does not work: 12585 12586@smallexample 12587 vec_add ((vector signed int)@{1, 2, 3, 4@}, foo); 12588@end smallexample 12589 12590@noindent 12591Since @code{vec_add} is a macro, the vector constant in the example 12592is treated as four separate arguments. Wrap the entire argument in 12593parentheses for this to work. 12594@end itemize 12595 12596@emph{Note:} Only the @code{<altivec.h>} interface is supported. 12597Internally, GCC uses built-in functions to achieve the functionality in 12598the aforementioned header file, but they are not supported and are 12599subject to change without notice. 12600 12601The following interfaces are supported for the generic and specific 12602AltiVec operations and the AltiVec predicates. In cases where there 12603is a direct mapping between generic and specific operations, only the 12604generic names are shown here, although the specific operations can also 12605be used. 12606 12607Arguments that are documented as @code{const int} require literal 12608integral values within the range required for that operation. 12609 12610@smallexample 12611vector signed char vec_abs (vector signed char); 12612vector signed short vec_abs (vector signed short); 12613vector signed int vec_abs (vector signed int); 12614vector float vec_abs (vector float); 12615 12616vector signed char vec_abss (vector signed char); 12617vector signed short vec_abss (vector signed short); 12618vector signed int vec_abss (vector signed int); 12619 12620vector signed char vec_add (vector bool char, vector signed char); 12621vector signed char vec_add (vector signed char, vector bool char); 12622vector signed char vec_add (vector signed char, vector signed char); 12623vector unsigned char vec_add (vector bool char, vector unsigned char); 12624vector unsigned char vec_add (vector unsigned char, vector bool char); 12625vector unsigned char vec_add (vector unsigned char, 12626 vector unsigned char); 12627vector signed short vec_add (vector bool short, vector signed short); 12628vector signed short vec_add (vector signed short, vector bool short); 12629vector signed short vec_add (vector signed short, vector signed short); 12630vector unsigned short vec_add (vector bool short, 12631 vector unsigned short); 12632vector unsigned short vec_add (vector unsigned short, 12633 vector bool short); 12634vector unsigned short vec_add (vector unsigned short, 12635 vector unsigned short); 12636vector signed int vec_add (vector bool int, vector signed int); 12637vector signed int vec_add (vector signed int, vector bool int); 12638vector signed int vec_add (vector signed int, vector signed int); 12639vector unsigned int vec_add (vector bool int, vector unsigned int); 12640vector unsigned int vec_add (vector unsigned int, vector bool int); 12641vector unsigned int vec_add (vector unsigned int, vector unsigned int); 12642vector float vec_add (vector float, vector float); 12643 12644vector float vec_vaddfp (vector float, vector float); 12645 12646vector signed int vec_vadduwm (vector bool int, vector signed int); 12647vector signed int vec_vadduwm (vector signed int, vector bool int); 12648vector signed int vec_vadduwm (vector signed int, vector signed int); 12649vector unsigned int vec_vadduwm (vector bool int, vector unsigned int); 12650vector unsigned int vec_vadduwm (vector unsigned int, vector bool int); 12651vector unsigned int vec_vadduwm (vector unsigned int, 12652 vector unsigned int); 12653 12654vector signed short vec_vadduhm (vector bool short, 12655 vector signed short); 12656vector signed short vec_vadduhm (vector signed short, 12657 vector bool short); 12658vector signed short vec_vadduhm (vector signed short, 12659 vector signed short); 12660vector unsigned short vec_vadduhm (vector bool short, 12661 vector unsigned short); 12662vector unsigned short vec_vadduhm (vector unsigned short, 12663 vector bool short); 12664vector unsigned short vec_vadduhm (vector unsigned short, 12665 vector unsigned short); 12666 12667vector signed char vec_vaddubm (vector bool char, vector signed char); 12668vector signed char vec_vaddubm (vector signed char, vector bool char); 12669vector signed char vec_vaddubm (vector signed char, vector signed char); 12670vector unsigned char vec_vaddubm (vector bool char, 12671 vector unsigned char); 12672vector unsigned char vec_vaddubm (vector unsigned char, 12673 vector bool char); 12674vector unsigned char vec_vaddubm (vector unsigned char, 12675 vector unsigned char); 12676 12677vector unsigned int vec_addc (vector unsigned int, vector unsigned int); 12678 12679vector unsigned char vec_adds (vector bool char, vector unsigned char); 12680vector unsigned char vec_adds (vector unsigned char, vector bool char); 12681vector unsigned char vec_adds (vector unsigned char, 12682 vector unsigned char); 12683vector signed char vec_adds (vector bool char, vector signed char); 12684vector signed char vec_adds (vector signed char, vector bool char); 12685vector signed char vec_adds (vector signed char, vector signed char); 12686vector unsigned short vec_adds (vector bool short, 12687 vector unsigned short); 12688vector unsigned short vec_adds (vector unsigned short, 12689 vector bool short); 12690vector unsigned short vec_adds (vector unsigned short, 12691 vector unsigned short); 12692vector signed short vec_adds (vector bool short, vector signed short); 12693vector signed short vec_adds (vector signed short, vector bool short); 12694vector signed short vec_adds (vector signed short, vector signed short); 12695vector unsigned int vec_adds (vector bool int, vector unsigned int); 12696vector unsigned int vec_adds (vector unsigned int, vector bool int); 12697vector unsigned int vec_adds (vector unsigned int, vector unsigned int); 12698vector signed int vec_adds (vector bool int, vector signed int); 12699vector signed int vec_adds (vector signed int, vector bool int); 12700vector signed int vec_adds (vector signed int, vector signed int); 12701 12702vector signed int vec_vaddsws (vector bool int, vector signed int); 12703vector signed int vec_vaddsws (vector signed int, vector bool int); 12704vector signed int vec_vaddsws (vector signed int, vector signed int); 12705 12706vector unsigned int vec_vadduws (vector bool int, vector unsigned int); 12707vector unsigned int vec_vadduws (vector unsigned int, vector bool int); 12708vector unsigned int vec_vadduws (vector unsigned int, 12709 vector unsigned int); 12710 12711vector signed short vec_vaddshs (vector bool short, 12712 vector signed short); 12713vector signed short vec_vaddshs (vector signed short, 12714 vector bool short); 12715vector signed short vec_vaddshs (vector signed short, 12716 vector signed short); 12717 12718vector unsigned short vec_vadduhs (vector bool short, 12719 vector unsigned short); 12720vector unsigned short vec_vadduhs (vector unsigned short, 12721 vector bool short); 12722vector unsigned short vec_vadduhs (vector unsigned short, 12723 vector unsigned short); 12724 12725vector signed char vec_vaddsbs (vector bool char, vector signed char); 12726vector signed char vec_vaddsbs (vector signed char, vector bool char); 12727vector signed char vec_vaddsbs (vector signed char, vector signed char); 12728 12729vector unsigned char vec_vaddubs (vector bool char, 12730 vector unsigned char); 12731vector unsigned char vec_vaddubs (vector unsigned char, 12732 vector bool char); 12733vector unsigned char vec_vaddubs (vector unsigned char, 12734 vector unsigned char); 12735 12736vector float vec_and (vector float, vector float); 12737vector float vec_and (vector float, vector bool int); 12738vector float vec_and (vector bool int, vector float); 12739vector bool int vec_and (vector bool int, vector bool int); 12740vector signed int vec_and (vector bool int, vector signed int); 12741vector signed int vec_and (vector signed int, vector bool int); 12742vector signed int vec_and (vector signed int, vector signed int); 12743vector unsigned int vec_and (vector bool int, vector unsigned int); 12744vector unsigned int vec_and (vector unsigned int, vector bool int); 12745vector unsigned int vec_and (vector unsigned int, vector unsigned int); 12746vector bool short vec_and (vector bool short, vector bool short); 12747vector signed short vec_and (vector bool short, vector signed short); 12748vector signed short vec_and (vector signed short, vector bool short); 12749vector signed short vec_and (vector signed short, vector signed short); 12750vector unsigned short vec_and (vector bool short, 12751 vector unsigned short); 12752vector unsigned short vec_and (vector unsigned short, 12753 vector bool short); 12754vector unsigned short vec_and (vector unsigned short, 12755 vector unsigned short); 12756vector signed char vec_and (vector bool char, vector signed char); 12757vector bool char vec_and (vector bool char, vector bool char); 12758vector signed char vec_and (vector signed char, vector bool char); 12759vector signed char vec_and (vector signed char, vector signed char); 12760vector unsigned char vec_and (vector bool char, vector unsigned char); 12761vector unsigned char vec_and (vector unsigned char, vector bool char); 12762vector unsigned char vec_and (vector unsigned char, 12763 vector unsigned char); 12764 12765vector float vec_andc (vector float, vector float); 12766vector float vec_andc (vector float, vector bool int); 12767vector float vec_andc (vector bool int, vector float); 12768vector bool int vec_andc (vector bool int, vector bool int); 12769vector signed int vec_andc (vector bool int, vector signed int); 12770vector signed int vec_andc (vector signed int, vector bool int); 12771vector signed int vec_andc (vector signed int, vector signed int); 12772vector unsigned int vec_andc (vector bool int, vector unsigned int); 12773vector unsigned int vec_andc (vector unsigned int, vector bool int); 12774vector unsigned int vec_andc (vector unsigned int, vector unsigned int); 12775vector bool short vec_andc (vector bool short, vector bool short); 12776vector signed short vec_andc (vector bool short, vector signed short); 12777vector signed short vec_andc (vector signed short, vector bool short); 12778vector signed short vec_andc (vector signed short, vector signed short); 12779vector unsigned short vec_andc (vector bool short, 12780 vector unsigned short); 12781vector unsigned short vec_andc (vector unsigned short, 12782 vector bool short); 12783vector unsigned short vec_andc (vector unsigned short, 12784 vector unsigned short); 12785vector signed char vec_andc (vector bool char, vector signed char); 12786vector bool char vec_andc (vector bool char, vector bool char); 12787vector signed char vec_andc (vector signed char, vector bool char); 12788vector signed char vec_andc (vector signed char, vector signed char); 12789vector unsigned char vec_andc (vector bool char, vector unsigned char); 12790vector unsigned char vec_andc (vector unsigned char, vector bool char); 12791vector unsigned char vec_andc (vector unsigned char, 12792 vector unsigned char); 12793 12794vector unsigned char vec_avg (vector unsigned char, 12795 vector unsigned char); 12796vector signed char vec_avg (vector signed char, vector signed char); 12797vector unsigned short vec_avg (vector unsigned short, 12798 vector unsigned short); 12799vector signed short vec_avg (vector signed short, vector signed short); 12800vector unsigned int vec_avg (vector unsigned int, vector unsigned int); 12801vector signed int vec_avg (vector signed int, vector signed int); 12802 12803vector signed int vec_vavgsw (vector signed int, vector signed int); 12804 12805vector unsigned int vec_vavguw (vector unsigned int, 12806 vector unsigned int); 12807 12808vector signed short vec_vavgsh (vector signed short, 12809 vector signed short); 12810 12811vector unsigned short vec_vavguh (vector unsigned short, 12812 vector unsigned short); 12813 12814vector signed char vec_vavgsb (vector signed char, vector signed char); 12815 12816vector unsigned char vec_vavgub (vector unsigned char, 12817 vector unsigned char); 12818 12819vector float vec_copysign (vector float); 12820 12821vector float vec_ceil (vector float); 12822 12823vector signed int vec_cmpb (vector float, vector float); 12824 12825vector bool char vec_cmpeq (vector signed char, vector signed char); 12826vector bool char vec_cmpeq (vector unsigned char, vector unsigned char); 12827vector bool short vec_cmpeq (vector signed short, vector signed short); 12828vector bool short vec_cmpeq (vector unsigned short, 12829 vector unsigned short); 12830vector bool int vec_cmpeq (vector signed int, vector signed int); 12831vector bool int vec_cmpeq (vector unsigned int, vector unsigned int); 12832vector bool int vec_cmpeq (vector float, vector float); 12833 12834vector bool int vec_vcmpeqfp (vector float, vector float); 12835 12836vector bool int vec_vcmpequw (vector signed int, vector signed int); 12837vector bool int vec_vcmpequw (vector unsigned int, vector unsigned int); 12838 12839vector bool short vec_vcmpequh (vector signed short, 12840 vector signed short); 12841vector bool short vec_vcmpequh (vector unsigned short, 12842 vector unsigned short); 12843 12844vector bool char vec_vcmpequb (vector signed char, vector signed char); 12845vector bool char vec_vcmpequb (vector unsigned char, 12846 vector unsigned char); 12847 12848vector bool int vec_cmpge (vector float, vector float); 12849 12850vector bool char vec_cmpgt (vector unsigned char, vector unsigned char); 12851vector bool char vec_cmpgt (vector signed char, vector signed char); 12852vector bool short vec_cmpgt (vector unsigned short, 12853 vector unsigned short); 12854vector bool short vec_cmpgt (vector signed short, vector signed short); 12855vector bool int vec_cmpgt (vector unsigned int, vector unsigned int); 12856vector bool int vec_cmpgt (vector signed int, vector signed int); 12857vector bool int vec_cmpgt (vector float, vector float); 12858 12859vector bool int vec_vcmpgtfp (vector float, vector float); 12860 12861vector bool int vec_vcmpgtsw (vector signed int, vector signed int); 12862 12863vector bool int vec_vcmpgtuw (vector unsigned int, vector unsigned int); 12864 12865vector bool short vec_vcmpgtsh (vector signed short, 12866 vector signed short); 12867 12868vector bool short vec_vcmpgtuh (vector unsigned short, 12869 vector unsigned short); 12870 12871vector bool char vec_vcmpgtsb (vector signed char, vector signed char); 12872 12873vector bool char vec_vcmpgtub (vector unsigned char, 12874 vector unsigned char); 12875 12876vector bool int vec_cmple (vector float, vector float); 12877 12878vector bool char vec_cmplt (vector unsigned char, vector unsigned char); 12879vector bool char vec_cmplt (vector signed char, vector signed char); 12880vector bool short vec_cmplt (vector unsigned short, 12881 vector unsigned short); 12882vector bool short vec_cmplt (vector signed short, vector signed short); 12883vector bool int vec_cmplt (vector unsigned int, vector unsigned int); 12884vector bool int vec_cmplt (vector signed int, vector signed int); 12885vector bool int vec_cmplt (vector float, vector float); 12886 12887vector float vec_cpsgn (vector float, vector float); 12888 12889vector float vec_ctf (vector unsigned int, const int); 12890vector float vec_ctf (vector signed int, const int); 12891vector double vec_ctf (vector unsigned long, const int); 12892vector double vec_ctf (vector signed long, const int); 12893 12894vector float vec_vcfsx (vector signed int, const int); 12895 12896vector float vec_vcfux (vector unsigned int, const int); 12897 12898vector signed int vec_cts (vector float, const int); 12899vector signed long vec_cts (vector double, const int); 12900 12901vector unsigned int vec_ctu (vector float, const int); 12902vector unsigned long vec_ctu (vector double, const int); 12903 12904void vec_dss (const int); 12905 12906void vec_dssall (void); 12907 12908void vec_dst (const vector unsigned char *, int, const int); 12909void vec_dst (const vector signed char *, int, const int); 12910void vec_dst (const vector bool char *, int, const int); 12911void vec_dst (const vector unsigned short *, int, const int); 12912void vec_dst (const vector signed short *, int, const int); 12913void vec_dst (const vector bool short *, int, const int); 12914void vec_dst (const vector pixel *, int, const int); 12915void vec_dst (const vector unsigned int *, int, const int); 12916void vec_dst (const vector signed int *, int, const int); 12917void vec_dst (const vector bool int *, int, const int); 12918void vec_dst (const vector float *, int, const int); 12919void vec_dst (const unsigned char *, int, const int); 12920void vec_dst (const signed char *, int, const int); 12921void vec_dst (const unsigned short *, int, const int); 12922void vec_dst (const short *, int, const int); 12923void vec_dst (const unsigned int *, int, const int); 12924void vec_dst (const int *, int, const int); 12925void vec_dst (const unsigned long *, int, const int); 12926void vec_dst (const long *, int, const int); 12927void vec_dst (const float *, int, const int); 12928 12929void vec_dstst (const vector unsigned char *, int, const int); 12930void vec_dstst (const vector signed char *, int, const int); 12931void vec_dstst (const vector bool char *, int, const int); 12932void vec_dstst (const vector unsigned short *, int, const int); 12933void vec_dstst (const vector signed short *, int, const int); 12934void vec_dstst (const vector bool short *, int, const int); 12935void vec_dstst (const vector pixel *, int, const int); 12936void vec_dstst (const vector unsigned int *, int, const int); 12937void vec_dstst (const vector signed int *, int, const int); 12938void vec_dstst (const vector bool int *, int, const int); 12939void vec_dstst (const vector float *, int, const int); 12940void vec_dstst (const unsigned char *, int, const int); 12941void vec_dstst (const signed char *, int, const int); 12942void vec_dstst (const unsigned short *, int, const int); 12943void vec_dstst (const short *, int, const int); 12944void vec_dstst (const unsigned int *, int, const int); 12945void vec_dstst (const int *, int, const int); 12946void vec_dstst (const unsigned long *, int, const int); 12947void vec_dstst (const long *, int, const int); 12948void vec_dstst (const float *, int, const int); 12949 12950void vec_dststt (const vector unsigned char *, int, const int); 12951void vec_dststt (const vector signed char *, int, const int); 12952void vec_dststt (const vector bool char *, int, const int); 12953void vec_dststt (const vector unsigned short *, int, const int); 12954void vec_dststt (const vector signed short *, int, const int); 12955void vec_dststt (const vector bool short *, int, const int); 12956void vec_dststt (const vector pixel *, int, const int); 12957void vec_dststt (const vector unsigned int *, int, const int); 12958void vec_dststt (const vector signed int *, int, const int); 12959void vec_dststt (const vector bool int *, int, const int); 12960void vec_dststt (const vector float *, int, const int); 12961void vec_dststt (const unsigned char *, int, const int); 12962void vec_dststt (const signed char *, int, const int); 12963void vec_dststt (const unsigned short *, int, const int); 12964void vec_dststt (const short *, int, const int); 12965void vec_dststt (const unsigned int *, int, const int); 12966void vec_dststt (const int *, int, const int); 12967void vec_dststt (const unsigned long *, int, const int); 12968void vec_dststt (const long *, int, const int); 12969void vec_dststt (const float *, int, const int); 12970 12971void vec_dstt (const vector unsigned char *, int, const int); 12972void vec_dstt (const vector signed char *, int, const int); 12973void vec_dstt (const vector bool char *, int, const int); 12974void vec_dstt (const vector unsigned short *, int, const int); 12975void vec_dstt (const vector signed short *, int, const int); 12976void vec_dstt (const vector bool short *, int, const int); 12977void vec_dstt (const vector pixel *, int, const int); 12978void vec_dstt (const vector unsigned int *, int, const int); 12979void vec_dstt (const vector signed int *, int, const int); 12980void vec_dstt (const vector bool int *, int, const int); 12981void vec_dstt (const vector float *, int, const int); 12982void vec_dstt (const unsigned char *, int, const int); 12983void vec_dstt (const signed char *, int, const int); 12984void vec_dstt (const unsigned short *, int, const int); 12985void vec_dstt (const short *, int, const int); 12986void vec_dstt (const unsigned int *, int, const int); 12987void vec_dstt (const int *, int, const int); 12988void vec_dstt (const unsigned long *, int, const int); 12989void vec_dstt (const long *, int, const int); 12990void vec_dstt (const float *, int, const int); 12991 12992vector float vec_expte (vector float); 12993 12994vector float vec_floor (vector float); 12995 12996vector float vec_ld (int, const vector float *); 12997vector float vec_ld (int, const float *); 12998vector bool int vec_ld (int, const vector bool int *); 12999vector signed int vec_ld (int, const vector signed int *); 13000vector signed int vec_ld (int, const int *); 13001vector signed int vec_ld (int, const long *); 13002vector unsigned int vec_ld (int, const vector unsigned int *); 13003vector unsigned int vec_ld (int, const unsigned int *); 13004vector unsigned int vec_ld (int, const unsigned long *); 13005vector bool short vec_ld (int, const vector bool short *); 13006vector pixel vec_ld (int, const vector pixel *); 13007vector signed short vec_ld (int, const vector signed short *); 13008vector signed short vec_ld (int, const short *); 13009vector unsigned short vec_ld (int, const vector unsigned short *); 13010vector unsigned short vec_ld (int, const unsigned short *); 13011vector bool char vec_ld (int, const vector bool char *); 13012vector signed char vec_ld (int, const vector signed char *); 13013vector signed char vec_ld (int, const signed char *); 13014vector unsigned char vec_ld (int, const vector unsigned char *); 13015vector unsigned char vec_ld (int, const unsigned char *); 13016 13017vector signed char vec_lde (int, const signed char *); 13018vector unsigned char vec_lde (int, const unsigned char *); 13019vector signed short vec_lde (int, const short *); 13020vector unsigned short vec_lde (int, const unsigned short *); 13021vector float vec_lde (int, const float *); 13022vector signed int vec_lde (int, const int *); 13023vector unsigned int vec_lde (int, const unsigned int *); 13024vector signed int vec_lde (int, const long *); 13025vector unsigned int vec_lde (int, const unsigned long *); 13026 13027vector float vec_lvewx (int, float *); 13028vector signed int vec_lvewx (int, int *); 13029vector unsigned int vec_lvewx (int, unsigned int *); 13030vector signed int vec_lvewx (int, long *); 13031vector unsigned int vec_lvewx (int, unsigned long *); 13032 13033vector signed short vec_lvehx (int, short *); 13034vector unsigned short vec_lvehx (int, unsigned short *); 13035 13036vector signed char vec_lvebx (int, char *); 13037vector unsigned char vec_lvebx (int, unsigned char *); 13038 13039vector float vec_ldl (int, const vector float *); 13040vector float vec_ldl (int, const float *); 13041vector bool int vec_ldl (int, const vector bool int *); 13042vector signed int vec_ldl (int, const vector signed int *); 13043vector signed int vec_ldl (int, const int *); 13044vector signed int vec_ldl (int, const long *); 13045vector unsigned int vec_ldl (int, const vector unsigned int *); 13046vector unsigned int vec_ldl (int, const unsigned int *); 13047vector unsigned int vec_ldl (int, const unsigned long *); 13048vector bool short vec_ldl (int, const vector bool short *); 13049vector pixel vec_ldl (int, const vector pixel *); 13050vector signed short vec_ldl (int, const vector signed short *); 13051vector signed short vec_ldl (int, const short *); 13052vector unsigned short vec_ldl (int, const vector unsigned short *); 13053vector unsigned short vec_ldl (int, const unsigned short *); 13054vector bool char vec_ldl (int, const vector bool char *); 13055vector signed char vec_ldl (int, const vector signed char *); 13056vector signed char vec_ldl (int, const signed char *); 13057vector unsigned char vec_ldl (int, const vector unsigned char *); 13058vector unsigned char vec_ldl (int, const unsigned char *); 13059 13060vector float vec_loge (vector float); 13061 13062vector unsigned char vec_lvsl (int, const volatile unsigned char *); 13063vector unsigned char vec_lvsl (int, const volatile signed char *); 13064vector unsigned char vec_lvsl (int, const volatile unsigned short *); 13065vector unsigned char vec_lvsl (int, const volatile short *); 13066vector unsigned char vec_lvsl (int, const volatile unsigned int *); 13067vector unsigned char vec_lvsl (int, const volatile int *); 13068vector unsigned char vec_lvsl (int, const volatile unsigned long *); 13069vector unsigned char vec_lvsl (int, const volatile long *); 13070vector unsigned char vec_lvsl (int, const volatile float *); 13071 13072vector unsigned char vec_lvsr (int, const volatile unsigned char *); 13073vector unsigned char vec_lvsr (int, const volatile signed char *); 13074vector unsigned char vec_lvsr (int, const volatile unsigned short *); 13075vector unsigned char vec_lvsr (int, const volatile short *); 13076vector unsigned char vec_lvsr (int, const volatile unsigned int *); 13077vector unsigned char vec_lvsr (int, const volatile int *); 13078vector unsigned char vec_lvsr (int, const volatile unsigned long *); 13079vector unsigned char vec_lvsr (int, const volatile long *); 13080vector unsigned char vec_lvsr (int, const volatile float *); 13081 13082vector float vec_madd (vector float, vector float, vector float); 13083 13084vector signed short vec_madds (vector signed short, 13085 vector signed short, 13086 vector signed short); 13087 13088vector unsigned char vec_max (vector bool char, vector unsigned char); 13089vector unsigned char vec_max (vector unsigned char, vector bool char); 13090vector unsigned char vec_max (vector unsigned char, 13091 vector unsigned char); 13092vector signed char vec_max (vector bool char, vector signed char); 13093vector signed char vec_max (vector signed char, vector bool char); 13094vector signed char vec_max (vector signed char, vector signed char); 13095vector unsigned short vec_max (vector bool short, 13096 vector unsigned short); 13097vector unsigned short vec_max (vector unsigned short, 13098 vector bool short); 13099vector unsigned short vec_max (vector unsigned short, 13100 vector unsigned short); 13101vector signed short vec_max (vector bool short, vector signed short); 13102vector signed short vec_max (vector signed short, vector bool short); 13103vector signed short vec_max (vector signed short, vector signed short); 13104vector unsigned int vec_max (vector bool int, vector unsigned int); 13105vector unsigned int vec_max (vector unsigned int, vector bool int); 13106vector unsigned int vec_max (vector unsigned int, vector unsigned int); 13107vector signed int vec_max (vector bool int, vector signed int); 13108vector signed int vec_max (vector signed int, vector bool int); 13109vector signed int vec_max (vector signed int, vector signed int); 13110vector float vec_max (vector float, vector float); 13111 13112vector float vec_vmaxfp (vector float, vector float); 13113 13114vector signed int vec_vmaxsw (vector bool int, vector signed int); 13115vector signed int vec_vmaxsw (vector signed int, vector bool int); 13116vector signed int vec_vmaxsw (vector signed int, vector signed int); 13117 13118vector unsigned int vec_vmaxuw (vector bool int, vector unsigned int); 13119vector unsigned int vec_vmaxuw (vector unsigned int, vector bool int); 13120vector unsigned int vec_vmaxuw (vector unsigned int, 13121 vector unsigned int); 13122 13123vector signed short vec_vmaxsh (vector bool short, vector signed short); 13124vector signed short vec_vmaxsh (vector signed short, vector bool short); 13125vector signed short vec_vmaxsh (vector signed short, 13126 vector signed short); 13127 13128vector unsigned short vec_vmaxuh (vector bool short, 13129 vector unsigned short); 13130vector unsigned short vec_vmaxuh (vector unsigned short, 13131 vector bool short); 13132vector unsigned short vec_vmaxuh (vector unsigned short, 13133 vector unsigned short); 13134 13135vector signed char vec_vmaxsb (vector bool char, vector signed char); 13136vector signed char vec_vmaxsb (vector signed char, vector bool char); 13137vector signed char vec_vmaxsb (vector signed char, vector signed char); 13138 13139vector unsigned char vec_vmaxub (vector bool char, 13140 vector unsigned char); 13141vector unsigned char vec_vmaxub (vector unsigned char, 13142 vector bool char); 13143vector unsigned char vec_vmaxub (vector unsigned char, 13144 vector unsigned char); 13145 13146vector bool char vec_mergeh (vector bool char, vector bool char); 13147vector signed char vec_mergeh (vector signed char, vector signed char); 13148vector unsigned char vec_mergeh (vector unsigned char, 13149 vector unsigned char); 13150vector bool short vec_mergeh (vector bool short, vector bool short); 13151vector pixel vec_mergeh (vector pixel, vector pixel); 13152vector signed short vec_mergeh (vector signed short, 13153 vector signed short); 13154vector unsigned short vec_mergeh (vector unsigned short, 13155 vector unsigned short); 13156vector float vec_mergeh (vector float, vector float); 13157vector bool int vec_mergeh (vector bool int, vector bool int); 13158vector signed int vec_mergeh (vector signed int, vector signed int); 13159vector unsigned int vec_mergeh (vector unsigned int, 13160 vector unsigned int); 13161 13162vector float vec_vmrghw (vector float, vector float); 13163vector bool int vec_vmrghw (vector bool int, vector bool int); 13164vector signed int vec_vmrghw (vector signed int, vector signed int); 13165vector unsigned int vec_vmrghw (vector unsigned int, 13166 vector unsigned int); 13167 13168vector bool short vec_vmrghh (vector bool short, vector bool short); 13169vector signed short vec_vmrghh (vector signed short, 13170 vector signed short); 13171vector unsigned short vec_vmrghh (vector unsigned short, 13172 vector unsigned short); 13173vector pixel vec_vmrghh (vector pixel, vector pixel); 13174 13175vector bool char vec_vmrghb (vector bool char, vector bool char); 13176vector signed char vec_vmrghb (vector signed char, vector signed char); 13177vector unsigned char vec_vmrghb (vector unsigned char, 13178 vector unsigned char); 13179 13180vector bool char vec_mergel (vector bool char, vector bool char); 13181vector signed char vec_mergel (vector signed char, vector signed char); 13182vector unsigned char vec_mergel (vector unsigned char, 13183 vector unsigned char); 13184vector bool short vec_mergel (vector bool short, vector bool short); 13185vector pixel vec_mergel (vector pixel, vector pixel); 13186vector signed short vec_mergel (vector signed short, 13187 vector signed short); 13188vector unsigned short vec_mergel (vector unsigned short, 13189 vector unsigned short); 13190vector float vec_mergel (vector float, vector float); 13191vector bool int vec_mergel (vector bool int, vector bool int); 13192vector signed int vec_mergel (vector signed int, vector signed int); 13193vector unsigned int vec_mergel (vector unsigned int, 13194 vector unsigned int); 13195 13196vector float vec_vmrglw (vector float, vector float); 13197vector signed int vec_vmrglw (vector signed int, vector signed int); 13198vector unsigned int vec_vmrglw (vector unsigned int, 13199 vector unsigned int); 13200vector bool int vec_vmrglw (vector bool int, vector bool int); 13201 13202vector bool short vec_vmrglh (vector bool short, vector bool short); 13203vector signed short vec_vmrglh (vector signed short, 13204 vector signed short); 13205vector unsigned short vec_vmrglh (vector unsigned short, 13206 vector unsigned short); 13207vector pixel vec_vmrglh (vector pixel, vector pixel); 13208 13209vector bool char vec_vmrglb (vector bool char, vector bool char); 13210vector signed char vec_vmrglb (vector signed char, vector signed char); 13211vector unsigned char vec_vmrglb (vector unsigned char, 13212 vector unsigned char); 13213 13214vector unsigned short vec_mfvscr (void); 13215 13216vector unsigned char vec_min (vector bool char, vector unsigned char); 13217vector unsigned char vec_min (vector unsigned char, vector bool char); 13218vector unsigned char vec_min (vector unsigned char, 13219 vector unsigned char); 13220vector signed char vec_min (vector bool char, vector signed char); 13221vector signed char vec_min (vector signed char, vector bool char); 13222vector signed char vec_min (vector signed char, vector signed char); 13223vector unsigned short vec_min (vector bool short, 13224 vector unsigned short); 13225vector unsigned short vec_min (vector unsigned short, 13226 vector bool short); 13227vector unsigned short vec_min (vector unsigned short, 13228 vector unsigned short); 13229vector signed short vec_min (vector bool short, vector signed short); 13230vector signed short vec_min (vector signed short, vector bool short); 13231vector signed short vec_min (vector signed short, vector signed short); 13232vector unsigned int vec_min (vector bool int, vector unsigned int); 13233vector unsigned int vec_min (vector unsigned int, vector bool int); 13234vector unsigned int vec_min (vector unsigned int, vector unsigned int); 13235vector signed int vec_min (vector bool int, vector signed int); 13236vector signed int vec_min (vector signed int, vector bool int); 13237vector signed int vec_min (vector signed int, vector signed int); 13238vector float vec_min (vector float, vector float); 13239 13240vector float vec_vminfp (vector float, vector float); 13241 13242vector signed int vec_vminsw (vector bool int, vector signed int); 13243vector signed int vec_vminsw (vector signed int, vector bool int); 13244vector signed int vec_vminsw (vector signed int, vector signed int); 13245 13246vector unsigned int vec_vminuw (vector bool int, vector unsigned int); 13247vector unsigned int vec_vminuw (vector unsigned int, vector bool int); 13248vector unsigned int vec_vminuw (vector unsigned int, 13249 vector unsigned int); 13250 13251vector signed short vec_vminsh (vector bool short, vector signed short); 13252vector signed short vec_vminsh (vector signed short, vector bool short); 13253vector signed short vec_vminsh (vector signed short, 13254 vector signed short); 13255 13256vector unsigned short vec_vminuh (vector bool short, 13257 vector unsigned short); 13258vector unsigned short vec_vminuh (vector unsigned short, 13259 vector bool short); 13260vector unsigned short vec_vminuh (vector unsigned short, 13261 vector unsigned short); 13262 13263vector signed char vec_vminsb (vector bool char, vector signed char); 13264vector signed char vec_vminsb (vector signed char, vector bool char); 13265vector signed char vec_vminsb (vector signed char, vector signed char); 13266 13267vector unsigned char vec_vminub (vector bool char, 13268 vector unsigned char); 13269vector unsigned char vec_vminub (vector unsigned char, 13270 vector bool char); 13271vector unsigned char vec_vminub (vector unsigned char, 13272 vector unsigned char); 13273 13274vector signed short vec_mladd (vector signed short, 13275 vector signed short, 13276 vector signed short); 13277vector signed short vec_mladd (vector signed short, 13278 vector unsigned short, 13279 vector unsigned short); 13280vector signed short vec_mladd (vector unsigned short, 13281 vector signed short, 13282 vector signed short); 13283vector unsigned short vec_mladd (vector unsigned short, 13284 vector unsigned short, 13285 vector unsigned short); 13286 13287vector signed short vec_mradds (vector signed short, 13288 vector signed short, 13289 vector signed short); 13290 13291vector unsigned int vec_msum (vector unsigned char, 13292 vector unsigned char, 13293 vector unsigned int); 13294vector signed int vec_msum (vector signed char, 13295 vector unsigned char, 13296 vector signed int); 13297vector unsigned int vec_msum (vector unsigned short, 13298 vector unsigned short, 13299 vector unsigned int); 13300vector signed int vec_msum (vector signed short, 13301 vector signed short, 13302 vector signed int); 13303 13304vector signed int vec_vmsumshm (vector signed short, 13305 vector signed short, 13306 vector signed int); 13307 13308vector unsigned int vec_vmsumuhm (vector unsigned short, 13309 vector unsigned short, 13310 vector unsigned int); 13311 13312vector signed int vec_vmsummbm (vector signed char, 13313 vector unsigned char, 13314 vector signed int); 13315 13316vector unsigned int vec_vmsumubm (vector unsigned char, 13317 vector unsigned char, 13318 vector unsigned int); 13319 13320vector unsigned int vec_msums (vector unsigned short, 13321 vector unsigned short, 13322 vector unsigned int); 13323vector signed int vec_msums (vector signed short, 13324 vector signed short, 13325 vector signed int); 13326 13327vector signed int vec_vmsumshs (vector signed short, 13328 vector signed short, 13329 vector signed int); 13330 13331vector unsigned int vec_vmsumuhs (vector unsigned short, 13332 vector unsigned short, 13333 vector unsigned int); 13334 13335void vec_mtvscr (vector signed int); 13336void vec_mtvscr (vector unsigned int); 13337void vec_mtvscr (vector bool int); 13338void vec_mtvscr (vector signed short); 13339void vec_mtvscr (vector unsigned short); 13340void vec_mtvscr (vector bool short); 13341void vec_mtvscr (vector pixel); 13342void vec_mtvscr (vector signed char); 13343void vec_mtvscr (vector unsigned char); 13344void vec_mtvscr (vector bool char); 13345 13346vector unsigned short vec_mule (vector unsigned char, 13347 vector unsigned char); 13348vector signed short vec_mule (vector signed char, 13349 vector signed char); 13350vector unsigned int vec_mule (vector unsigned short, 13351 vector unsigned short); 13352vector signed int vec_mule (vector signed short, vector signed short); 13353 13354vector signed int vec_vmulesh (vector signed short, 13355 vector signed short); 13356 13357vector unsigned int vec_vmuleuh (vector unsigned short, 13358 vector unsigned short); 13359 13360vector signed short vec_vmulesb (vector signed char, 13361 vector signed char); 13362 13363vector unsigned short vec_vmuleub (vector unsigned char, 13364 vector unsigned char); 13365 13366vector unsigned short vec_mulo (vector unsigned char, 13367 vector unsigned char); 13368vector signed short vec_mulo (vector signed char, vector signed char); 13369vector unsigned int vec_mulo (vector unsigned short, 13370 vector unsigned short); 13371vector signed int vec_mulo (vector signed short, vector signed short); 13372 13373vector signed int vec_vmulosh (vector signed short, 13374 vector signed short); 13375 13376vector unsigned int vec_vmulouh (vector unsigned short, 13377 vector unsigned short); 13378 13379vector signed short vec_vmulosb (vector signed char, 13380 vector signed char); 13381 13382vector unsigned short vec_vmuloub (vector unsigned char, 13383 vector unsigned char); 13384 13385vector float vec_nmsub (vector float, vector float, vector float); 13386 13387vector float vec_nor (vector float, vector float); 13388vector signed int vec_nor (vector signed int, vector signed int); 13389vector unsigned int vec_nor (vector unsigned int, vector unsigned int); 13390vector bool int vec_nor (vector bool int, vector bool int); 13391vector signed short vec_nor (vector signed short, vector signed short); 13392vector unsigned short vec_nor (vector unsigned short, 13393 vector unsigned short); 13394vector bool short vec_nor (vector bool short, vector bool short); 13395vector signed char vec_nor (vector signed char, vector signed char); 13396vector unsigned char vec_nor (vector unsigned char, 13397 vector unsigned char); 13398vector bool char vec_nor (vector bool char, vector bool char); 13399 13400vector float vec_or (vector float, vector float); 13401vector float vec_or (vector float, vector bool int); 13402vector float vec_or (vector bool int, vector float); 13403vector bool int vec_or (vector bool int, vector bool int); 13404vector signed int vec_or (vector bool int, vector signed int); 13405vector signed int vec_or (vector signed int, vector bool int); 13406vector signed int vec_or (vector signed int, vector signed int); 13407vector unsigned int vec_or (vector bool int, vector unsigned int); 13408vector unsigned int vec_or (vector unsigned int, vector bool int); 13409vector unsigned int vec_or (vector unsigned int, vector unsigned int); 13410vector bool short vec_or (vector bool short, vector bool short); 13411vector signed short vec_or (vector bool short, vector signed short); 13412vector signed short vec_or (vector signed short, vector bool short); 13413vector signed short vec_or (vector signed short, vector signed short); 13414vector unsigned short vec_or (vector bool short, vector unsigned short); 13415vector unsigned short vec_or (vector unsigned short, vector bool short); 13416vector unsigned short vec_or (vector unsigned short, 13417 vector unsigned short); 13418vector signed char vec_or (vector bool char, vector signed char); 13419vector bool char vec_or (vector bool char, vector bool char); 13420vector signed char vec_or (vector signed char, vector bool char); 13421vector signed char vec_or (vector signed char, vector signed char); 13422vector unsigned char vec_or (vector bool char, vector unsigned char); 13423vector unsigned char vec_or (vector unsigned char, vector bool char); 13424vector unsigned char vec_or (vector unsigned char, 13425 vector unsigned char); 13426 13427vector signed char vec_pack (vector signed short, vector signed short); 13428vector unsigned char vec_pack (vector unsigned short, 13429 vector unsigned short); 13430vector bool char vec_pack (vector bool short, vector bool short); 13431vector signed short vec_pack (vector signed int, vector signed int); 13432vector unsigned short vec_pack (vector unsigned int, 13433 vector unsigned int); 13434vector bool short vec_pack (vector bool int, vector bool int); 13435 13436vector bool short vec_vpkuwum (vector bool int, vector bool int); 13437vector signed short vec_vpkuwum (vector signed int, vector signed int); 13438vector unsigned short vec_vpkuwum (vector unsigned int, 13439 vector unsigned int); 13440 13441vector bool char vec_vpkuhum (vector bool short, vector bool short); 13442vector signed char vec_vpkuhum (vector signed short, 13443 vector signed short); 13444vector unsigned char vec_vpkuhum (vector unsigned short, 13445 vector unsigned short); 13446 13447vector pixel vec_packpx (vector unsigned int, vector unsigned int); 13448 13449vector unsigned char vec_packs (vector unsigned short, 13450 vector unsigned short); 13451vector signed char vec_packs (vector signed short, vector signed short); 13452vector unsigned short vec_packs (vector unsigned int, 13453 vector unsigned int); 13454vector signed short vec_packs (vector signed int, vector signed int); 13455 13456vector signed short vec_vpkswss (vector signed int, vector signed int); 13457 13458vector unsigned short vec_vpkuwus (vector unsigned int, 13459 vector unsigned int); 13460 13461vector signed char vec_vpkshss (vector signed short, 13462 vector signed short); 13463 13464vector unsigned char vec_vpkuhus (vector unsigned short, 13465 vector unsigned short); 13466 13467vector unsigned char vec_packsu (vector unsigned short, 13468 vector unsigned short); 13469vector unsigned char vec_packsu (vector signed short, 13470 vector signed short); 13471vector unsigned short vec_packsu (vector unsigned int, 13472 vector unsigned int); 13473vector unsigned short vec_packsu (vector signed int, vector signed int); 13474 13475vector unsigned short vec_vpkswus (vector signed int, 13476 vector signed int); 13477 13478vector unsigned char vec_vpkshus (vector signed short, 13479 vector signed short); 13480 13481vector float vec_perm (vector float, 13482 vector float, 13483 vector unsigned char); 13484vector signed int vec_perm (vector signed int, 13485 vector signed int, 13486 vector unsigned char); 13487vector unsigned int vec_perm (vector unsigned int, 13488 vector unsigned int, 13489 vector unsigned char); 13490vector bool int vec_perm (vector bool int, 13491 vector bool int, 13492 vector unsigned char); 13493vector signed short vec_perm (vector signed short, 13494 vector signed short, 13495 vector unsigned char); 13496vector unsigned short vec_perm (vector unsigned short, 13497 vector unsigned short, 13498 vector unsigned char); 13499vector bool short vec_perm (vector bool short, 13500 vector bool short, 13501 vector unsigned char); 13502vector pixel vec_perm (vector pixel, 13503 vector pixel, 13504 vector unsigned char); 13505vector signed char vec_perm (vector signed char, 13506 vector signed char, 13507 vector unsigned char); 13508vector unsigned char vec_perm (vector unsigned char, 13509 vector unsigned char, 13510 vector unsigned char); 13511vector bool char vec_perm (vector bool char, 13512 vector bool char, 13513 vector unsigned char); 13514 13515vector float vec_re (vector float); 13516 13517vector signed char vec_rl (vector signed char, 13518 vector unsigned char); 13519vector unsigned char vec_rl (vector unsigned char, 13520 vector unsigned char); 13521vector signed short vec_rl (vector signed short, vector unsigned short); 13522vector unsigned short vec_rl (vector unsigned short, 13523 vector unsigned short); 13524vector signed int vec_rl (vector signed int, vector unsigned int); 13525vector unsigned int vec_rl (vector unsigned int, vector unsigned int); 13526 13527vector signed int vec_vrlw (vector signed int, vector unsigned int); 13528vector unsigned int vec_vrlw (vector unsigned int, vector unsigned int); 13529 13530vector signed short vec_vrlh (vector signed short, 13531 vector unsigned short); 13532vector unsigned short vec_vrlh (vector unsigned short, 13533 vector unsigned short); 13534 13535vector signed char vec_vrlb (vector signed char, vector unsigned char); 13536vector unsigned char vec_vrlb (vector unsigned char, 13537 vector unsigned char); 13538 13539vector float vec_round (vector float); 13540 13541vector float vec_recip (vector float, vector float); 13542 13543vector float vec_rsqrt (vector float); 13544 13545vector float vec_rsqrte (vector float); 13546 13547vector float vec_sel (vector float, vector float, vector bool int); 13548vector float vec_sel (vector float, vector float, vector unsigned int); 13549vector signed int vec_sel (vector signed int, 13550 vector signed int, 13551 vector bool int); 13552vector signed int vec_sel (vector signed int, 13553 vector signed int, 13554 vector unsigned int); 13555vector unsigned int vec_sel (vector unsigned int, 13556 vector unsigned int, 13557 vector bool int); 13558vector unsigned int vec_sel (vector unsigned int, 13559 vector unsigned int, 13560 vector unsigned int); 13561vector bool int vec_sel (vector bool int, 13562 vector bool int, 13563 vector bool int); 13564vector bool int vec_sel (vector bool int, 13565 vector bool int, 13566 vector unsigned int); 13567vector signed short vec_sel (vector signed short, 13568 vector signed short, 13569 vector bool short); 13570vector signed short vec_sel (vector signed short, 13571 vector signed short, 13572 vector unsigned short); 13573vector unsigned short vec_sel (vector unsigned short, 13574 vector unsigned short, 13575 vector bool short); 13576vector unsigned short vec_sel (vector unsigned short, 13577 vector unsigned short, 13578 vector unsigned short); 13579vector bool short vec_sel (vector bool short, 13580 vector bool short, 13581 vector bool short); 13582vector bool short vec_sel (vector bool short, 13583 vector bool short, 13584 vector unsigned short); 13585vector signed char vec_sel (vector signed char, 13586 vector signed char, 13587 vector bool char); 13588vector signed char vec_sel (vector signed char, 13589 vector signed char, 13590 vector unsigned char); 13591vector unsigned char vec_sel (vector unsigned char, 13592 vector unsigned char, 13593 vector bool char); 13594vector unsigned char vec_sel (vector unsigned char, 13595 vector unsigned char, 13596 vector unsigned char); 13597vector bool char vec_sel (vector bool char, 13598 vector bool char, 13599 vector bool char); 13600vector bool char vec_sel (vector bool char, 13601 vector bool char, 13602 vector unsigned char); 13603 13604vector signed char vec_sl (vector signed char, 13605 vector unsigned char); 13606vector unsigned char vec_sl (vector unsigned char, 13607 vector unsigned char); 13608vector signed short vec_sl (vector signed short, vector unsigned short); 13609vector unsigned short vec_sl (vector unsigned short, 13610 vector unsigned short); 13611vector signed int vec_sl (vector signed int, vector unsigned int); 13612vector unsigned int vec_sl (vector unsigned int, vector unsigned int); 13613 13614vector signed int vec_vslw (vector signed int, vector unsigned int); 13615vector unsigned int vec_vslw (vector unsigned int, vector unsigned int); 13616 13617vector signed short vec_vslh (vector signed short, 13618 vector unsigned short); 13619vector unsigned short vec_vslh (vector unsigned short, 13620 vector unsigned short); 13621 13622vector signed char vec_vslb (vector signed char, vector unsigned char); 13623vector unsigned char vec_vslb (vector unsigned char, 13624 vector unsigned char); 13625 13626vector float vec_sld (vector float, vector float, const int); 13627vector signed int vec_sld (vector signed int, 13628 vector signed int, 13629 const int); 13630vector unsigned int vec_sld (vector unsigned int, 13631 vector unsigned int, 13632 const int); 13633vector bool int vec_sld (vector bool int, 13634 vector bool int, 13635 const int); 13636vector signed short vec_sld (vector signed short, 13637 vector signed short, 13638 const int); 13639vector unsigned short vec_sld (vector unsigned short, 13640 vector unsigned short, 13641 const int); 13642vector bool short vec_sld (vector bool short, 13643 vector bool short, 13644 const int); 13645vector pixel vec_sld (vector pixel, 13646 vector pixel, 13647 const int); 13648vector signed char vec_sld (vector signed char, 13649 vector signed char, 13650 const int); 13651vector unsigned char vec_sld (vector unsigned char, 13652 vector unsigned char, 13653 const int); 13654vector bool char vec_sld (vector bool char, 13655 vector bool char, 13656 const int); 13657 13658vector signed int vec_sll (vector signed int, 13659 vector unsigned int); 13660vector signed int vec_sll (vector signed int, 13661 vector unsigned short); 13662vector signed int vec_sll (vector signed int, 13663 vector unsigned char); 13664vector unsigned int vec_sll (vector unsigned int, 13665 vector unsigned int); 13666vector unsigned int vec_sll (vector unsigned int, 13667 vector unsigned short); 13668vector unsigned int vec_sll (vector unsigned int, 13669 vector unsigned char); 13670vector bool int vec_sll (vector bool int, 13671 vector unsigned int); 13672vector bool int vec_sll (vector bool int, 13673 vector unsigned short); 13674vector bool int vec_sll (vector bool int, 13675 vector unsigned char); 13676vector signed short vec_sll (vector signed short, 13677 vector unsigned int); 13678vector signed short vec_sll (vector signed short, 13679 vector unsigned short); 13680vector signed short vec_sll (vector signed short, 13681 vector unsigned char); 13682vector unsigned short vec_sll (vector unsigned short, 13683 vector unsigned int); 13684vector unsigned short vec_sll (vector unsigned short, 13685 vector unsigned short); 13686vector unsigned short vec_sll (vector unsigned short, 13687 vector unsigned char); 13688vector bool short vec_sll (vector bool short, vector unsigned int); 13689vector bool short vec_sll (vector bool short, vector unsigned short); 13690vector bool short vec_sll (vector bool short, vector unsigned char); 13691vector pixel vec_sll (vector pixel, vector unsigned int); 13692vector pixel vec_sll (vector pixel, vector unsigned short); 13693vector pixel vec_sll (vector pixel, vector unsigned char); 13694vector signed char vec_sll (vector signed char, vector unsigned int); 13695vector signed char vec_sll (vector signed char, vector unsigned short); 13696vector signed char vec_sll (vector signed char, vector unsigned char); 13697vector unsigned char vec_sll (vector unsigned char, 13698 vector unsigned int); 13699vector unsigned char vec_sll (vector unsigned char, 13700 vector unsigned short); 13701vector unsigned char vec_sll (vector unsigned char, 13702 vector unsigned char); 13703vector bool char vec_sll (vector bool char, vector unsigned int); 13704vector bool char vec_sll (vector bool char, vector unsigned short); 13705vector bool char vec_sll (vector bool char, vector unsigned char); 13706 13707vector float vec_slo (vector float, vector signed char); 13708vector float vec_slo (vector float, vector unsigned char); 13709vector signed int vec_slo (vector signed int, vector signed char); 13710vector signed int vec_slo (vector signed int, vector unsigned char); 13711vector unsigned int vec_slo (vector unsigned int, vector signed char); 13712vector unsigned int vec_slo (vector unsigned int, vector unsigned char); 13713vector signed short vec_slo (vector signed short, vector signed char); 13714vector signed short vec_slo (vector signed short, vector unsigned char); 13715vector unsigned short vec_slo (vector unsigned short, 13716 vector signed char); 13717vector unsigned short vec_slo (vector unsigned short, 13718 vector unsigned char); 13719vector pixel vec_slo (vector pixel, vector signed char); 13720vector pixel vec_slo (vector pixel, vector unsigned char); 13721vector signed char vec_slo (vector signed char, vector signed char); 13722vector signed char vec_slo (vector signed char, vector unsigned char); 13723vector unsigned char vec_slo (vector unsigned char, vector signed char); 13724vector unsigned char vec_slo (vector unsigned char, 13725 vector unsigned char); 13726 13727vector signed char vec_splat (vector signed char, const int); 13728vector unsigned char vec_splat (vector unsigned char, const int); 13729vector bool char vec_splat (vector bool char, const int); 13730vector signed short vec_splat (vector signed short, const int); 13731vector unsigned short vec_splat (vector unsigned short, const int); 13732vector bool short vec_splat (vector bool short, const int); 13733vector pixel vec_splat (vector pixel, const int); 13734vector float vec_splat (vector float, const int); 13735vector signed int vec_splat (vector signed int, const int); 13736vector unsigned int vec_splat (vector unsigned int, const int); 13737vector bool int vec_splat (vector bool int, const int); 13738vector signed long vec_splat (vector signed long, const int); 13739vector unsigned long vec_splat (vector unsigned long, const int); 13740 13741vector signed char vec_splats (signed char); 13742vector unsigned char vec_splats (unsigned char); 13743vector signed short vec_splats (signed short); 13744vector unsigned short vec_splats (unsigned short); 13745vector signed int vec_splats (signed int); 13746vector unsigned int vec_splats (unsigned int); 13747vector float vec_splats (float); 13748 13749vector float vec_vspltw (vector float, const int); 13750vector signed int vec_vspltw (vector signed int, const int); 13751vector unsigned int vec_vspltw (vector unsigned int, const int); 13752vector bool int vec_vspltw (vector bool int, const int); 13753 13754vector bool short vec_vsplth (vector bool short, const int); 13755vector signed short vec_vsplth (vector signed short, const int); 13756vector unsigned short vec_vsplth (vector unsigned short, const int); 13757vector pixel vec_vsplth (vector pixel, const int); 13758 13759vector signed char vec_vspltb (vector signed char, const int); 13760vector unsigned char vec_vspltb (vector unsigned char, const int); 13761vector bool char vec_vspltb (vector bool char, const int); 13762 13763vector signed char vec_splat_s8 (const int); 13764 13765vector signed short vec_splat_s16 (const int); 13766 13767vector signed int vec_splat_s32 (const int); 13768 13769vector unsigned char vec_splat_u8 (const int); 13770 13771vector unsigned short vec_splat_u16 (const int); 13772 13773vector unsigned int vec_splat_u32 (const int); 13774 13775vector signed char vec_sr (vector signed char, vector unsigned char); 13776vector unsigned char vec_sr (vector unsigned char, 13777 vector unsigned char); 13778vector signed short vec_sr (vector signed short, 13779 vector unsigned short); 13780vector unsigned short vec_sr (vector unsigned short, 13781 vector unsigned short); 13782vector signed int vec_sr (vector signed int, vector unsigned int); 13783vector unsigned int vec_sr (vector unsigned int, vector unsigned int); 13784 13785vector signed int vec_vsrw (vector signed int, vector unsigned int); 13786vector unsigned int vec_vsrw (vector unsigned int, vector unsigned int); 13787 13788vector signed short vec_vsrh (vector signed short, 13789 vector unsigned short); 13790vector unsigned short vec_vsrh (vector unsigned short, 13791 vector unsigned short); 13792 13793vector signed char vec_vsrb (vector signed char, vector unsigned char); 13794vector unsigned char vec_vsrb (vector unsigned char, 13795 vector unsigned char); 13796 13797vector signed char vec_sra (vector signed char, vector unsigned char); 13798vector unsigned char vec_sra (vector unsigned char, 13799 vector unsigned char); 13800vector signed short vec_sra (vector signed short, 13801 vector unsigned short); 13802vector unsigned short vec_sra (vector unsigned short, 13803 vector unsigned short); 13804vector signed int vec_sra (vector signed int, vector unsigned int); 13805vector unsigned int vec_sra (vector unsigned int, vector unsigned int); 13806 13807vector signed int vec_vsraw (vector signed int, vector unsigned int); 13808vector unsigned int vec_vsraw (vector unsigned int, 13809 vector unsigned int); 13810 13811vector signed short vec_vsrah (vector signed short, 13812 vector unsigned short); 13813vector unsigned short vec_vsrah (vector unsigned short, 13814 vector unsigned short); 13815 13816vector signed char vec_vsrab (vector signed char, vector unsigned char); 13817vector unsigned char vec_vsrab (vector unsigned char, 13818 vector unsigned char); 13819 13820vector signed int vec_srl (vector signed int, vector unsigned int); 13821vector signed int vec_srl (vector signed int, vector unsigned short); 13822vector signed int vec_srl (vector signed int, vector unsigned char); 13823vector unsigned int vec_srl (vector unsigned int, vector unsigned int); 13824vector unsigned int vec_srl (vector unsigned int, 13825 vector unsigned short); 13826vector unsigned int vec_srl (vector unsigned int, vector unsigned char); 13827vector bool int vec_srl (vector bool int, vector unsigned int); 13828vector bool int vec_srl (vector bool int, vector unsigned short); 13829vector bool int vec_srl (vector bool int, vector unsigned char); 13830vector signed short vec_srl (vector signed short, vector unsigned int); 13831vector signed short vec_srl (vector signed short, 13832 vector unsigned short); 13833vector signed short vec_srl (vector signed short, vector unsigned char); 13834vector unsigned short vec_srl (vector unsigned short, 13835 vector unsigned int); 13836vector unsigned short vec_srl (vector unsigned short, 13837 vector unsigned short); 13838vector unsigned short vec_srl (vector unsigned short, 13839 vector unsigned char); 13840vector bool short vec_srl (vector bool short, vector unsigned int); 13841vector bool short vec_srl (vector bool short, vector unsigned short); 13842vector bool short vec_srl (vector bool short, vector unsigned char); 13843vector pixel vec_srl (vector pixel, vector unsigned int); 13844vector pixel vec_srl (vector pixel, vector unsigned short); 13845vector pixel vec_srl (vector pixel, vector unsigned char); 13846vector signed char vec_srl (vector signed char, vector unsigned int); 13847vector signed char vec_srl (vector signed char, vector unsigned short); 13848vector signed char vec_srl (vector signed char, vector unsigned char); 13849vector unsigned char vec_srl (vector unsigned char, 13850 vector unsigned int); 13851vector unsigned char vec_srl (vector unsigned char, 13852 vector unsigned short); 13853vector unsigned char vec_srl (vector unsigned char, 13854 vector unsigned char); 13855vector bool char vec_srl (vector bool char, vector unsigned int); 13856vector bool char vec_srl (vector bool char, vector unsigned short); 13857vector bool char vec_srl (vector bool char, vector unsigned char); 13858 13859vector float vec_sro (vector float, vector signed char); 13860vector float vec_sro (vector float, vector unsigned char); 13861vector signed int vec_sro (vector signed int, vector signed char); 13862vector signed int vec_sro (vector signed int, vector unsigned char); 13863vector unsigned int vec_sro (vector unsigned int, vector signed char); 13864vector unsigned int vec_sro (vector unsigned int, vector unsigned char); 13865vector signed short vec_sro (vector signed short, vector signed char); 13866vector signed short vec_sro (vector signed short, vector unsigned char); 13867vector unsigned short vec_sro (vector unsigned short, 13868 vector signed char); 13869vector unsigned short vec_sro (vector unsigned short, 13870 vector unsigned char); 13871vector pixel vec_sro (vector pixel, vector signed char); 13872vector pixel vec_sro (vector pixel, vector unsigned char); 13873vector signed char vec_sro (vector signed char, vector signed char); 13874vector signed char vec_sro (vector signed char, vector unsigned char); 13875vector unsigned char vec_sro (vector unsigned char, vector signed char); 13876vector unsigned char vec_sro (vector unsigned char, 13877 vector unsigned char); 13878 13879void vec_st (vector float, int, vector float *); 13880void vec_st (vector float, int, float *); 13881void vec_st (vector signed int, int, vector signed int *); 13882void vec_st (vector signed int, int, int *); 13883void vec_st (vector unsigned int, int, vector unsigned int *); 13884void vec_st (vector unsigned int, int, unsigned int *); 13885void vec_st (vector bool int, int, vector bool int *); 13886void vec_st (vector bool int, int, unsigned int *); 13887void vec_st (vector bool int, int, int *); 13888void vec_st (vector signed short, int, vector signed short *); 13889void vec_st (vector signed short, int, short *); 13890void vec_st (vector unsigned short, int, vector unsigned short *); 13891void vec_st (vector unsigned short, int, unsigned short *); 13892void vec_st (vector bool short, int, vector bool short *); 13893void vec_st (vector bool short, int, unsigned short *); 13894void vec_st (vector pixel, int, vector pixel *); 13895void vec_st (vector pixel, int, unsigned short *); 13896void vec_st (vector pixel, int, short *); 13897void vec_st (vector bool short, int, short *); 13898void vec_st (vector signed char, int, vector signed char *); 13899void vec_st (vector signed char, int, signed char *); 13900void vec_st (vector unsigned char, int, vector unsigned char *); 13901void vec_st (vector unsigned char, int, unsigned char *); 13902void vec_st (vector bool char, int, vector bool char *); 13903void vec_st (vector bool char, int, unsigned char *); 13904void vec_st (vector bool char, int, signed char *); 13905 13906void vec_ste (vector signed char, int, signed char *); 13907void vec_ste (vector unsigned char, int, unsigned char *); 13908void vec_ste (vector bool char, int, signed char *); 13909void vec_ste (vector bool char, int, unsigned char *); 13910void vec_ste (vector signed short, int, short *); 13911void vec_ste (vector unsigned short, int, unsigned short *); 13912void vec_ste (vector bool short, int, short *); 13913void vec_ste (vector bool short, int, unsigned short *); 13914void vec_ste (vector pixel, int, short *); 13915void vec_ste (vector pixel, int, unsigned short *); 13916void vec_ste (vector float, int, float *); 13917void vec_ste (vector signed int, int, int *); 13918void vec_ste (vector unsigned int, int, unsigned int *); 13919void vec_ste (vector bool int, int, int *); 13920void vec_ste (vector bool int, int, unsigned int *); 13921 13922void vec_stvewx (vector float, int, float *); 13923void vec_stvewx (vector signed int, int, int *); 13924void vec_stvewx (vector unsigned int, int, unsigned int *); 13925void vec_stvewx (vector bool int, int, int *); 13926void vec_stvewx (vector bool int, int, unsigned int *); 13927 13928void vec_stvehx (vector signed short, int, short *); 13929void vec_stvehx (vector unsigned short, int, unsigned short *); 13930void vec_stvehx (vector bool short, int, short *); 13931void vec_stvehx (vector bool short, int, unsigned short *); 13932void vec_stvehx (vector pixel, int, short *); 13933void vec_stvehx (vector pixel, int, unsigned short *); 13934 13935void vec_stvebx (vector signed char, int, signed char *); 13936void vec_stvebx (vector unsigned char, int, unsigned char *); 13937void vec_stvebx (vector bool char, int, signed char *); 13938void vec_stvebx (vector bool char, int, unsigned char *); 13939 13940void vec_stl (vector float, int, vector float *); 13941void vec_stl (vector float, int, float *); 13942void vec_stl (vector signed int, int, vector signed int *); 13943void vec_stl (vector signed int, int, int *); 13944void vec_stl (vector unsigned int, int, vector unsigned int *); 13945void vec_stl (vector unsigned int, int, unsigned int *); 13946void vec_stl (vector bool int, int, vector bool int *); 13947void vec_stl (vector bool int, int, unsigned int *); 13948void vec_stl (vector bool int, int, int *); 13949void vec_stl (vector signed short, int, vector signed short *); 13950void vec_stl (vector signed short, int, short *); 13951void vec_stl (vector unsigned short, int, vector unsigned short *); 13952void vec_stl (vector unsigned short, int, unsigned short *); 13953void vec_stl (vector bool short, int, vector bool short *); 13954void vec_stl (vector bool short, int, unsigned short *); 13955void vec_stl (vector bool short, int, short *); 13956void vec_stl (vector pixel, int, vector pixel *); 13957void vec_stl (vector pixel, int, unsigned short *); 13958void vec_stl (vector pixel, int, short *); 13959void vec_stl (vector signed char, int, vector signed char *); 13960void vec_stl (vector signed char, int, signed char *); 13961void vec_stl (vector unsigned char, int, vector unsigned char *); 13962void vec_stl (vector unsigned char, int, unsigned char *); 13963void vec_stl (vector bool char, int, vector bool char *); 13964void vec_stl (vector bool char, int, unsigned char *); 13965void vec_stl (vector bool char, int, signed char *); 13966 13967vector signed char vec_sub (vector bool char, vector signed char); 13968vector signed char vec_sub (vector signed char, vector bool char); 13969vector signed char vec_sub (vector signed char, vector signed char); 13970vector unsigned char vec_sub (vector bool char, vector unsigned char); 13971vector unsigned char vec_sub (vector unsigned char, vector bool char); 13972vector unsigned char vec_sub (vector unsigned char, 13973 vector unsigned char); 13974vector signed short vec_sub (vector bool short, vector signed short); 13975vector signed short vec_sub (vector signed short, vector bool short); 13976vector signed short vec_sub (vector signed short, vector signed short); 13977vector unsigned short vec_sub (vector bool short, 13978 vector unsigned short); 13979vector unsigned short vec_sub (vector unsigned short, 13980 vector bool short); 13981vector unsigned short vec_sub (vector unsigned short, 13982 vector unsigned short); 13983vector signed int vec_sub (vector bool int, vector signed int); 13984vector signed int vec_sub (vector signed int, vector bool int); 13985vector signed int vec_sub (vector signed int, vector signed int); 13986vector unsigned int vec_sub (vector bool int, vector unsigned int); 13987vector unsigned int vec_sub (vector unsigned int, vector bool int); 13988vector unsigned int vec_sub (vector unsigned int, vector unsigned int); 13989vector float vec_sub (vector float, vector float); 13990 13991vector float vec_vsubfp (vector float, vector float); 13992 13993vector signed int vec_vsubuwm (vector bool int, vector signed int); 13994vector signed int vec_vsubuwm (vector signed int, vector bool int); 13995vector signed int vec_vsubuwm (vector signed int, vector signed int); 13996vector unsigned int vec_vsubuwm (vector bool int, vector unsigned int); 13997vector unsigned int vec_vsubuwm (vector unsigned int, vector bool int); 13998vector unsigned int vec_vsubuwm (vector unsigned int, 13999 vector unsigned int); 14000 14001vector signed short vec_vsubuhm (vector bool short, 14002 vector signed short); 14003vector signed short vec_vsubuhm (vector signed short, 14004 vector bool short); 14005vector signed short vec_vsubuhm (vector signed short, 14006 vector signed short); 14007vector unsigned short vec_vsubuhm (vector bool short, 14008 vector unsigned short); 14009vector unsigned short vec_vsubuhm (vector unsigned short, 14010 vector bool short); 14011vector unsigned short vec_vsubuhm (vector unsigned short, 14012 vector unsigned short); 14013 14014vector signed char vec_vsububm (vector bool char, vector signed char); 14015vector signed char vec_vsububm (vector signed char, vector bool char); 14016vector signed char vec_vsububm (vector signed char, vector signed char); 14017vector unsigned char vec_vsububm (vector bool char, 14018 vector unsigned char); 14019vector unsigned char vec_vsububm (vector unsigned char, 14020 vector bool char); 14021vector unsigned char vec_vsububm (vector unsigned char, 14022 vector unsigned char); 14023 14024vector unsigned int vec_subc (vector unsigned int, vector unsigned int); 14025 14026vector unsigned char vec_subs (vector bool char, vector unsigned char); 14027vector unsigned char vec_subs (vector unsigned char, vector bool char); 14028vector unsigned char vec_subs (vector unsigned char, 14029 vector unsigned char); 14030vector signed char vec_subs (vector bool char, vector signed char); 14031vector signed char vec_subs (vector signed char, vector bool char); 14032vector signed char vec_subs (vector signed char, vector signed char); 14033vector unsigned short vec_subs (vector bool short, 14034 vector unsigned short); 14035vector unsigned short vec_subs (vector unsigned short, 14036 vector bool short); 14037vector unsigned short vec_subs (vector unsigned short, 14038 vector unsigned short); 14039vector signed short vec_subs (vector bool short, vector signed short); 14040vector signed short vec_subs (vector signed short, vector bool short); 14041vector signed short vec_subs (vector signed short, vector signed short); 14042vector unsigned int vec_subs (vector bool int, vector unsigned int); 14043vector unsigned int vec_subs (vector unsigned int, vector bool int); 14044vector unsigned int vec_subs (vector unsigned int, vector unsigned int); 14045vector signed int vec_subs (vector bool int, vector signed int); 14046vector signed int vec_subs (vector signed int, vector bool int); 14047vector signed int vec_subs (vector signed int, vector signed int); 14048 14049vector signed int vec_vsubsws (vector bool int, vector signed int); 14050vector signed int vec_vsubsws (vector signed int, vector bool int); 14051vector signed int vec_vsubsws (vector signed int, vector signed int); 14052 14053vector unsigned int vec_vsubuws (vector bool int, vector unsigned int); 14054vector unsigned int vec_vsubuws (vector unsigned int, vector bool int); 14055vector unsigned int vec_vsubuws (vector unsigned int, 14056 vector unsigned int); 14057 14058vector signed short vec_vsubshs (vector bool short, 14059 vector signed short); 14060vector signed short vec_vsubshs (vector signed short, 14061 vector bool short); 14062vector signed short vec_vsubshs (vector signed short, 14063 vector signed short); 14064 14065vector unsigned short vec_vsubuhs (vector bool short, 14066 vector unsigned short); 14067vector unsigned short vec_vsubuhs (vector unsigned short, 14068 vector bool short); 14069vector unsigned short vec_vsubuhs (vector unsigned short, 14070 vector unsigned short); 14071 14072vector signed char vec_vsubsbs (vector bool char, vector signed char); 14073vector signed char vec_vsubsbs (vector signed char, vector bool char); 14074vector signed char vec_vsubsbs (vector signed char, vector signed char); 14075 14076vector unsigned char vec_vsububs (vector bool char, 14077 vector unsigned char); 14078vector unsigned char vec_vsububs (vector unsigned char, 14079 vector bool char); 14080vector unsigned char vec_vsububs (vector unsigned char, 14081 vector unsigned char); 14082 14083vector unsigned int vec_sum4s (vector unsigned char, 14084 vector unsigned int); 14085vector signed int vec_sum4s (vector signed char, vector signed int); 14086vector signed int vec_sum4s (vector signed short, vector signed int); 14087 14088vector signed int vec_vsum4shs (vector signed short, vector signed int); 14089 14090vector signed int vec_vsum4sbs (vector signed char, vector signed int); 14091 14092vector unsigned int vec_vsum4ubs (vector unsigned char, 14093 vector unsigned int); 14094 14095vector signed int vec_sum2s (vector signed int, vector signed int); 14096 14097vector signed int vec_sums (vector signed int, vector signed int); 14098 14099vector float vec_trunc (vector float); 14100 14101vector signed short vec_unpackh (vector signed char); 14102vector bool short vec_unpackh (vector bool char); 14103vector signed int vec_unpackh (vector signed short); 14104vector bool int vec_unpackh (vector bool short); 14105vector unsigned int vec_unpackh (vector pixel); 14106 14107vector bool int vec_vupkhsh (vector bool short); 14108vector signed int vec_vupkhsh (vector signed short); 14109 14110vector unsigned int vec_vupkhpx (vector pixel); 14111 14112vector bool short vec_vupkhsb (vector bool char); 14113vector signed short vec_vupkhsb (vector signed char); 14114 14115vector signed short vec_unpackl (vector signed char); 14116vector bool short vec_unpackl (vector bool char); 14117vector unsigned int vec_unpackl (vector pixel); 14118vector signed int vec_unpackl (vector signed short); 14119vector bool int vec_unpackl (vector bool short); 14120 14121vector unsigned int vec_vupklpx (vector pixel); 14122 14123vector bool int vec_vupklsh (vector bool short); 14124vector signed int vec_vupklsh (vector signed short); 14125 14126vector bool short vec_vupklsb (vector bool char); 14127vector signed short vec_vupklsb (vector signed char); 14128 14129vector float vec_xor (vector float, vector float); 14130vector float vec_xor (vector float, vector bool int); 14131vector float vec_xor (vector bool int, vector float); 14132vector bool int vec_xor (vector bool int, vector bool int); 14133vector signed int vec_xor (vector bool int, vector signed int); 14134vector signed int vec_xor (vector signed int, vector bool int); 14135vector signed int vec_xor (vector signed int, vector signed int); 14136vector unsigned int vec_xor (vector bool int, vector unsigned int); 14137vector unsigned int vec_xor (vector unsigned int, vector bool int); 14138vector unsigned int vec_xor (vector unsigned int, vector unsigned int); 14139vector bool short vec_xor (vector bool short, vector bool short); 14140vector signed short vec_xor (vector bool short, vector signed short); 14141vector signed short vec_xor (vector signed short, vector bool short); 14142vector signed short vec_xor (vector signed short, vector signed short); 14143vector unsigned short vec_xor (vector bool short, 14144 vector unsigned short); 14145vector unsigned short vec_xor (vector unsigned short, 14146 vector bool short); 14147vector unsigned short vec_xor (vector unsigned short, 14148 vector unsigned short); 14149vector signed char vec_xor (vector bool char, vector signed char); 14150vector bool char vec_xor (vector bool char, vector bool char); 14151vector signed char vec_xor (vector signed char, vector bool char); 14152vector signed char vec_xor (vector signed char, vector signed char); 14153vector unsigned char vec_xor (vector bool char, vector unsigned char); 14154vector unsigned char vec_xor (vector unsigned char, vector bool char); 14155vector unsigned char vec_xor (vector unsigned char, 14156 vector unsigned char); 14157 14158int vec_all_eq (vector signed char, vector bool char); 14159int vec_all_eq (vector signed char, vector signed char); 14160int vec_all_eq (vector unsigned char, vector bool char); 14161int vec_all_eq (vector unsigned char, vector unsigned char); 14162int vec_all_eq (vector bool char, vector bool char); 14163int vec_all_eq (vector bool char, vector unsigned char); 14164int vec_all_eq (vector bool char, vector signed char); 14165int vec_all_eq (vector signed short, vector bool short); 14166int vec_all_eq (vector signed short, vector signed short); 14167int vec_all_eq (vector unsigned short, vector bool short); 14168int vec_all_eq (vector unsigned short, vector unsigned short); 14169int vec_all_eq (vector bool short, vector bool short); 14170int vec_all_eq (vector bool short, vector unsigned short); 14171int vec_all_eq (vector bool short, vector signed short); 14172int vec_all_eq (vector pixel, vector pixel); 14173int vec_all_eq (vector signed int, vector bool int); 14174int vec_all_eq (vector signed int, vector signed int); 14175int vec_all_eq (vector unsigned int, vector bool int); 14176int vec_all_eq (vector unsigned int, vector unsigned int); 14177int vec_all_eq (vector bool int, vector bool int); 14178int vec_all_eq (vector bool int, vector unsigned int); 14179int vec_all_eq (vector bool int, vector signed int); 14180int vec_all_eq (vector float, vector float); 14181 14182int vec_all_ge (vector bool char, vector unsigned char); 14183int vec_all_ge (vector unsigned char, vector bool char); 14184int vec_all_ge (vector unsigned char, vector unsigned char); 14185int vec_all_ge (vector bool char, vector signed char); 14186int vec_all_ge (vector signed char, vector bool char); 14187int vec_all_ge (vector signed char, vector signed char); 14188int vec_all_ge (vector bool short, vector unsigned short); 14189int vec_all_ge (vector unsigned short, vector bool short); 14190int vec_all_ge (vector unsigned short, vector unsigned short); 14191int vec_all_ge (vector signed short, vector signed short); 14192int vec_all_ge (vector bool short, vector signed short); 14193int vec_all_ge (vector signed short, vector bool short); 14194int vec_all_ge (vector bool int, vector unsigned int); 14195int vec_all_ge (vector unsigned int, vector bool int); 14196int vec_all_ge (vector unsigned int, vector unsigned int); 14197int vec_all_ge (vector bool int, vector signed int); 14198int vec_all_ge (vector signed int, vector bool int); 14199int vec_all_ge (vector signed int, vector signed int); 14200int vec_all_ge (vector float, vector float); 14201 14202int vec_all_gt (vector bool char, vector unsigned char); 14203int vec_all_gt (vector unsigned char, vector bool char); 14204int vec_all_gt (vector unsigned char, vector unsigned char); 14205int vec_all_gt (vector bool char, vector signed char); 14206int vec_all_gt (vector signed char, vector bool char); 14207int vec_all_gt (vector signed char, vector signed char); 14208int vec_all_gt (vector bool short, vector unsigned short); 14209int vec_all_gt (vector unsigned short, vector bool short); 14210int vec_all_gt (vector unsigned short, vector unsigned short); 14211int vec_all_gt (vector bool short, vector signed short); 14212int vec_all_gt (vector signed short, vector bool short); 14213int vec_all_gt (vector signed short, vector signed short); 14214int vec_all_gt (vector bool int, vector unsigned int); 14215int vec_all_gt (vector unsigned int, vector bool int); 14216int vec_all_gt (vector unsigned int, vector unsigned int); 14217int vec_all_gt (vector bool int, vector signed int); 14218int vec_all_gt (vector signed int, vector bool int); 14219int vec_all_gt (vector signed int, vector signed int); 14220int vec_all_gt (vector float, vector float); 14221 14222int vec_all_in (vector float, vector float); 14223 14224int vec_all_le (vector bool char, vector unsigned char); 14225int vec_all_le (vector unsigned char, vector bool char); 14226int vec_all_le (vector unsigned char, vector unsigned char); 14227int vec_all_le (vector bool char, vector signed char); 14228int vec_all_le (vector signed char, vector bool char); 14229int vec_all_le (vector signed char, vector signed char); 14230int vec_all_le (vector bool short, vector unsigned short); 14231int vec_all_le (vector unsigned short, vector bool short); 14232int vec_all_le (vector unsigned short, vector unsigned short); 14233int vec_all_le (vector bool short, vector signed short); 14234int vec_all_le (vector signed short, vector bool short); 14235int vec_all_le (vector signed short, vector signed short); 14236int vec_all_le (vector bool int, vector unsigned int); 14237int vec_all_le (vector unsigned int, vector bool int); 14238int vec_all_le (vector unsigned int, vector unsigned int); 14239int vec_all_le (vector bool int, vector signed int); 14240int vec_all_le (vector signed int, vector bool int); 14241int vec_all_le (vector signed int, vector signed int); 14242int vec_all_le (vector float, vector float); 14243 14244int vec_all_lt (vector bool char, vector unsigned char); 14245int vec_all_lt (vector unsigned char, vector bool char); 14246int vec_all_lt (vector unsigned char, vector unsigned char); 14247int vec_all_lt (vector bool char, vector signed char); 14248int vec_all_lt (vector signed char, vector bool char); 14249int vec_all_lt (vector signed char, vector signed char); 14250int vec_all_lt (vector bool short, vector unsigned short); 14251int vec_all_lt (vector unsigned short, vector bool short); 14252int vec_all_lt (vector unsigned short, vector unsigned short); 14253int vec_all_lt (vector bool short, vector signed short); 14254int vec_all_lt (vector signed short, vector bool short); 14255int vec_all_lt (vector signed short, vector signed short); 14256int vec_all_lt (vector bool int, vector unsigned int); 14257int vec_all_lt (vector unsigned int, vector bool int); 14258int vec_all_lt (vector unsigned int, vector unsigned int); 14259int vec_all_lt (vector bool int, vector signed int); 14260int vec_all_lt (vector signed int, vector bool int); 14261int vec_all_lt (vector signed int, vector signed int); 14262int vec_all_lt (vector float, vector float); 14263 14264int vec_all_nan (vector float); 14265 14266int vec_all_ne (vector signed char, vector bool char); 14267int vec_all_ne (vector signed char, vector signed char); 14268int vec_all_ne (vector unsigned char, vector bool char); 14269int vec_all_ne (vector unsigned char, vector unsigned char); 14270int vec_all_ne (vector bool char, vector bool char); 14271int vec_all_ne (vector bool char, vector unsigned char); 14272int vec_all_ne (vector bool char, vector signed char); 14273int vec_all_ne (vector signed short, vector bool short); 14274int vec_all_ne (vector signed short, vector signed short); 14275int vec_all_ne (vector unsigned short, vector bool short); 14276int vec_all_ne (vector unsigned short, vector unsigned short); 14277int vec_all_ne (vector bool short, vector bool short); 14278int vec_all_ne (vector bool short, vector unsigned short); 14279int vec_all_ne (vector bool short, vector signed short); 14280int vec_all_ne (vector pixel, vector pixel); 14281int vec_all_ne (vector signed int, vector bool int); 14282int vec_all_ne (vector signed int, vector signed int); 14283int vec_all_ne (vector unsigned int, vector bool int); 14284int vec_all_ne (vector unsigned int, vector unsigned int); 14285int vec_all_ne (vector bool int, vector bool int); 14286int vec_all_ne (vector bool int, vector unsigned int); 14287int vec_all_ne (vector bool int, vector signed int); 14288int vec_all_ne (vector float, vector float); 14289 14290int vec_all_nge (vector float, vector float); 14291 14292int vec_all_ngt (vector float, vector float); 14293 14294int vec_all_nle (vector float, vector float); 14295 14296int vec_all_nlt (vector float, vector float); 14297 14298int vec_all_numeric (vector float); 14299 14300int vec_any_eq (vector signed char, vector bool char); 14301int vec_any_eq (vector signed char, vector signed char); 14302int vec_any_eq (vector unsigned char, vector bool char); 14303int vec_any_eq (vector unsigned char, vector unsigned char); 14304int vec_any_eq (vector bool char, vector bool char); 14305int vec_any_eq (vector bool char, vector unsigned char); 14306int vec_any_eq (vector bool char, vector signed char); 14307int vec_any_eq (vector signed short, vector bool short); 14308int vec_any_eq (vector signed short, vector signed short); 14309int vec_any_eq (vector unsigned short, vector bool short); 14310int vec_any_eq (vector unsigned short, vector unsigned short); 14311int vec_any_eq (vector bool short, vector bool short); 14312int vec_any_eq (vector bool short, vector unsigned short); 14313int vec_any_eq (vector bool short, vector signed short); 14314int vec_any_eq (vector pixel, vector pixel); 14315int vec_any_eq (vector signed int, vector bool int); 14316int vec_any_eq (vector signed int, vector signed int); 14317int vec_any_eq (vector unsigned int, vector bool int); 14318int vec_any_eq (vector unsigned int, vector unsigned int); 14319int vec_any_eq (vector bool int, vector bool int); 14320int vec_any_eq (vector bool int, vector unsigned int); 14321int vec_any_eq (vector bool int, vector signed int); 14322int vec_any_eq (vector float, vector float); 14323 14324int vec_any_ge (vector signed char, vector bool char); 14325int vec_any_ge (vector unsigned char, vector bool char); 14326int vec_any_ge (vector unsigned char, vector unsigned char); 14327int vec_any_ge (vector signed char, vector signed char); 14328int vec_any_ge (vector bool char, vector unsigned char); 14329int vec_any_ge (vector bool char, vector signed char); 14330int vec_any_ge (vector unsigned short, vector bool short); 14331int vec_any_ge (vector unsigned short, vector unsigned short); 14332int vec_any_ge (vector signed short, vector signed short); 14333int vec_any_ge (vector signed short, vector bool short); 14334int vec_any_ge (vector bool short, vector unsigned short); 14335int vec_any_ge (vector bool short, vector signed short); 14336int vec_any_ge (vector signed int, vector bool int); 14337int vec_any_ge (vector unsigned int, vector bool int); 14338int vec_any_ge (vector unsigned int, vector unsigned int); 14339int vec_any_ge (vector signed int, vector signed int); 14340int vec_any_ge (vector bool int, vector unsigned int); 14341int vec_any_ge (vector bool int, vector signed int); 14342int vec_any_ge (vector float, vector float); 14343 14344int vec_any_gt (vector bool char, vector unsigned char); 14345int vec_any_gt (vector unsigned char, vector bool char); 14346int vec_any_gt (vector unsigned char, vector unsigned char); 14347int vec_any_gt (vector bool char, vector signed char); 14348int vec_any_gt (vector signed char, vector bool char); 14349int vec_any_gt (vector signed char, vector signed char); 14350int vec_any_gt (vector bool short, vector unsigned short); 14351int vec_any_gt (vector unsigned short, vector bool short); 14352int vec_any_gt (vector unsigned short, vector unsigned short); 14353int vec_any_gt (vector bool short, vector signed short); 14354int vec_any_gt (vector signed short, vector bool short); 14355int vec_any_gt (vector signed short, vector signed short); 14356int vec_any_gt (vector bool int, vector unsigned int); 14357int vec_any_gt (vector unsigned int, vector bool int); 14358int vec_any_gt (vector unsigned int, vector unsigned int); 14359int vec_any_gt (vector bool int, vector signed int); 14360int vec_any_gt (vector signed int, vector bool int); 14361int vec_any_gt (vector signed int, vector signed int); 14362int vec_any_gt (vector float, vector float); 14363 14364int vec_any_le (vector bool char, vector unsigned char); 14365int vec_any_le (vector unsigned char, vector bool char); 14366int vec_any_le (vector unsigned char, vector unsigned char); 14367int vec_any_le (vector bool char, vector signed char); 14368int vec_any_le (vector signed char, vector bool char); 14369int vec_any_le (vector signed char, vector signed char); 14370int vec_any_le (vector bool short, vector unsigned short); 14371int vec_any_le (vector unsigned short, vector bool short); 14372int vec_any_le (vector unsigned short, vector unsigned short); 14373int vec_any_le (vector bool short, vector signed short); 14374int vec_any_le (vector signed short, vector bool short); 14375int vec_any_le (vector signed short, vector signed short); 14376int vec_any_le (vector bool int, vector unsigned int); 14377int vec_any_le (vector unsigned int, vector bool int); 14378int vec_any_le (vector unsigned int, vector unsigned int); 14379int vec_any_le (vector bool int, vector signed int); 14380int vec_any_le (vector signed int, vector bool int); 14381int vec_any_le (vector signed int, vector signed int); 14382int vec_any_le (vector float, vector float); 14383 14384int vec_any_lt (vector bool char, vector unsigned char); 14385int vec_any_lt (vector unsigned char, vector bool char); 14386int vec_any_lt (vector unsigned char, vector unsigned char); 14387int vec_any_lt (vector bool char, vector signed char); 14388int vec_any_lt (vector signed char, vector bool char); 14389int vec_any_lt (vector signed char, vector signed char); 14390int vec_any_lt (vector bool short, vector unsigned short); 14391int vec_any_lt (vector unsigned short, vector bool short); 14392int vec_any_lt (vector unsigned short, vector unsigned short); 14393int vec_any_lt (vector bool short, vector signed short); 14394int vec_any_lt (vector signed short, vector bool short); 14395int vec_any_lt (vector signed short, vector signed short); 14396int vec_any_lt (vector bool int, vector unsigned int); 14397int vec_any_lt (vector unsigned int, vector bool int); 14398int vec_any_lt (vector unsigned int, vector unsigned int); 14399int vec_any_lt (vector bool int, vector signed int); 14400int vec_any_lt (vector signed int, vector bool int); 14401int vec_any_lt (vector signed int, vector signed int); 14402int vec_any_lt (vector float, vector float); 14403 14404int vec_any_nan (vector float); 14405 14406int vec_any_ne (vector signed char, vector bool char); 14407int vec_any_ne (vector signed char, vector signed char); 14408int vec_any_ne (vector unsigned char, vector bool char); 14409int vec_any_ne (vector unsigned char, vector unsigned char); 14410int vec_any_ne (vector bool char, vector bool char); 14411int vec_any_ne (vector bool char, vector unsigned char); 14412int vec_any_ne (vector bool char, vector signed char); 14413int vec_any_ne (vector signed short, vector bool short); 14414int vec_any_ne (vector signed short, vector signed short); 14415int vec_any_ne (vector unsigned short, vector bool short); 14416int vec_any_ne (vector unsigned short, vector unsigned short); 14417int vec_any_ne (vector bool short, vector bool short); 14418int vec_any_ne (vector bool short, vector unsigned short); 14419int vec_any_ne (vector bool short, vector signed short); 14420int vec_any_ne (vector pixel, vector pixel); 14421int vec_any_ne (vector signed int, vector bool int); 14422int vec_any_ne (vector signed int, vector signed int); 14423int vec_any_ne (vector unsigned int, vector bool int); 14424int vec_any_ne (vector unsigned int, vector unsigned int); 14425int vec_any_ne (vector bool int, vector bool int); 14426int vec_any_ne (vector bool int, vector unsigned int); 14427int vec_any_ne (vector bool int, vector signed int); 14428int vec_any_ne (vector float, vector float); 14429 14430int vec_any_nge (vector float, vector float); 14431 14432int vec_any_ngt (vector float, vector float); 14433 14434int vec_any_nle (vector float, vector float); 14435 14436int vec_any_nlt (vector float, vector float); 14437 14438int vec_any_numeric (vector float); 14439 14440int vec_any_out (vector float, vector float); 14441@end smallexample 14442 14443If the vector/scalar (VSX) instruction set is available, the following 14444additional functions are available: 14445 14446@smallexample 14447vector double vec_abs (vector double); 14448vector double vec_add (vector double, vector double); 14449vector double vec_and (vector double, vector double); 14450vector double vec_and (vector double, vector bool long); 14451vector double vec_and (vector bool long, vector double); 14452vector long vec_and (vector long, vector long); 14453vector long vec_and (vector long, vector bool long); 14454vector long vec_and (vector bool long, vector long); 14455vector unsigned long vec_and (vector unsigned long, vector unsigned long); 14456vector unsigned long vec_and (vector unsigned long, vector bool long); 14457vector unsigned long vec_and (vector bool long, vector unsigned long); 14458vector double vec_andc (vector double, vector double); 14459vector double vec_andc (vector double, vector bool long); 14460vector double vec_andc (vector bool long, vector double); 14461vector long vec_andc (vector long, vector long); 14462vector long vec_andc (vector long, vector bool long); 14463vector long vec_andc (vector bool long, vector long); 14464vector unsigned long vec_andc (vector unsigned long, vector unsigned long); 14465vector unsigned long vec_andc (vector unsigned long, vector bool long); 14466vector unsigned long vec_andc (vector bool long, vector unsigned long); 14467vector double vec_ceil (vector double); 14468vector bool long vec_cmpeq (vector double, vector double); 14469vector bool long vec_cmpge (vector double, vector double); 14470vector bool long vec_cmpgt (vector double, vector double); 14471vector bool long vec_cmple (vector double, vector double); 14472vector bool long vec_cmplt (vector double, vector double); 14473vector double vec_cpsgn (vector double, vector double); 14474vector float vec_div (vector float, vector float); 14475vector double vec_div (vector double, vector double); 14476vector long vec_div (vector long, vector long); 14477vector unsigned long vec_div (vector unsigned long, vector unsigned long); 14478vector double vec_floor (vector double); 14479vector double vec_ld (int, const vector double *); 14480vector double vec_ld (int, const double *); 14481vector double vec_ldl (int, const vector double *); 14482vector double vec_ldl (int, const double *); 14483vector unsigned char vec_lvsl (int, const volatile double *); 14484vector unsigned char vec_lvsr (int, const volatile double *); 14485vector double vec_madd (vector double, vector double, vector double); 14486vector double vec_max (vector double, vector double); 14487vector signed long vec_mergeh (vector signed long, vector signed long); 14488vector signed long vec_mergeh (vector signed long, vector bool long); 14489vector signed long vec_mergeh (vector bool long, vector signed long); 14490vector unsigned long vec_mergeh (vector unsigned long, vector unsigned long); 14491vector unsigned long vec_mergeh (vector unsigned long, vector bool long); 14492vector unsigned long vec_mergeh (vector bool long, vector unsigned long); 14493vector signed long vec_mergel (vector signed long, vector signed long); 14494vector signed long vec_mergel (vector signed long, vector bool long); 14495vector signed long vec_mergel (vector bool long, vector signed long); 14496vector unsigned long vec_mergel (vector unsigned long, vector unsigned long); 14497vector unsigned long vec_mergel (vector unsigned long, vector bool long); 14498vector unsigned long vec_mergel (vector bool long, vector unsigned long); 14499vector double vec_min (vector double, vector double); 14500vector float vec_msub (vector float, vector float, vector float); 14501vector double vec_msub (vector double, vector double, vector double); 14502vector float vec_mul (vector float, vector float); 14503vector double vec_mul (vector double, vector double); 14504vector long vec_mul (vector long, vector long); 14505vector unsigned long vec_mul (vector unsigned long, vector unsigned long); 14506vector float vec_nearbyint (vector float); 14507vector double vec_nearbyint (vector double); 14508vector float vec_nmadd (vector float, vector float, vector float); 14509vector double vec_nmadd (vector double, vector double, vector double); 14510vector double vec_nmsub (vector double, vector double, vector double); 14511vector double vec_nor (vector double, vector double); 14512vector long vec_nor (vector long, vector long); 14513vector long vec_nor (vector long, vector bool long); 14514vector long vec_nor (vector bool long, vector long); 14515vector unsigned long vec_nor (vector unsigned long, vector unsigned long); 14516vector unsigned long vec_nor (vector unsigned long, vector bool long); 14517vector unsigned long vec_nor (vector bool long, vector unsigned long); 14518vector double vec_or (vector double, vector double); 14519vector double vec_or (vector double, vector bool long); 14520vector double vec_or (vector bool long, vector double); 14521vector long vec_or (vector long, vector long); 14522vector long vec_or (vector long, vector bool long); 14523vector long vec_or (vector bool long, vector long); 14524vector unsigned long vec_or (vector unsigned long, vector unsigned long); 14525vector unsigned long vec_or (vector unsigned long, vector bool long); 14526vector unsigned long vec_or (vector bool long, vector unsigned long); 14527vector double vec_perm (vector double, vector double, vector unsigned char); 14528vector long vec_perm (vector long, vector long, vector unsigned char); 14529vector unsigned long vec_perm (vector unsigned long, vector unsigned long, 14530 vector unsigned char); 14531vector double vec_rint (vector double); 14532vector double vec_recip (vector double, vector double); 14533vector double vec_rsqrt (vector double); 14534vector double vec_rsqrte (vector double); 14535vector double vec_sel (vector double, vector double, vector bool long); 14536vector double vec_sel (vector double, vector double, vector unsigned long); 14537vector long vec_sel (vector long, vector long, vector long); 14538vector long vec_sel (vector long, vector long, vector unsigned long); 14539vector long vec_sel (vector long, vector long, vector bool long); 14540vector unsigned long vec_sel (vector unsigned long, vector unsigned long, 14541 vector long); 14542vector unsigned long vec_sel (vector unsigned long, vector unsigned long, 14543 vector unsigned long); 14544vector unsigned long vec_sel (vector unsigned long, vector unsigned long, 14545 vector bool long); 14546vector double vec_splats (double); 14547vector signed long vec_splats (signed long); 14548vector unsigned long vec_splats (unsigned long); 14549vector float vec_sqrt (vector float); 14550vector double vec_sqrt (vector double); 14551void vec_st (vector double, int, vector double *); 14552void vec_st (vector double, int, double *); 14553vector double vec_sub (vector double, vector double); 14554vector double vec_trunc (vector double); 14555vector double vec_xor (vector double, vector double); 14556vector double vec_xor (vector double, vector bool long); 14557vector double vec_xor (vector bool long, vector double); 14558vector long vec_xor (vector long, vector long); 14559vector long vec_xor (vector long, vector bool long); 14560vector long vec_xor (vector bool long, vector long); 14561vector unsigned long vec_xor (vector unsigned long, vector unsigned long); 14562vector unsigned long vec_xor (vector unsigned long, vector bool long); 14563vector unsigned long vec_xor (vector bool long, vector unsigned long); 14564int vec_all_eq (vector double, vector double); 14565int vec_all_ge (vector double, vector double); 14566int vec_all_gt (vector double, vector double); 14567int vec_all_le (vector double, vector double); 14568int vec_all_lt (vector double, vector double); 14569int vec_all_nan (vector double); 14570int vec_all_ne (vector double, vector double); 14571int vec_all_nge (vector double, vector double); 14572int vec_all_ngt (vector double, vector double); 14573int vec_all_nle (vector double, vector double); 14574int vec_all_nlt (vector double, vector double); 14575int vec_all_numeric (vector double); 14576int vec_any_eq (vector double, vector double); 14577int vec_any_ge (vector double, vector double); 14578int vec_any_gt (vector double, vector double); 14579int vec_any_le (vector double, vector double); 14580int vec_any_lt (vector double, vector double); 14581int vec_any_nan (vector double); 14582int vec_any_ne (vector double, vector double); 14583int vec_any_nge (vector double, vector double); 14584int vec_any_ngt (vector double, vector double); 14585int vec_any_nle (vector double, vector double); 14586int vec_any_nlt (vector double, vector double); 14587int vec_any_numeric (vector double); 14588 14589vector double vec_vsx_ld (int, const vector double *); 14590vector double vec_vsx_ld (int, const double *); 14591vector float vec_vsx_ld (int, const vector float *); 14592vector float vec_vsx_ld (int, const float *); 14593vector bool int vec_vsx_ld (int, const vector bool int *); 14594vector signed int vec_vsx_ld (int, const vector signed int *); 14595vector signed int vec_vsx_ld (int, const int *); 14596vector signed int vec_vsx_ld (int, const long *); 14597vector unsigned int vec_vsx_ld (int, const vector unsigned int *); 14598vector unsigned int vec_vsx_ld (int, const unsigned int *); 14599vector unsigned int vec_vsx_ld (int, const unsigned long *); 14600vector bool short vec_vsx_ld (int, const vector bool short *); 14601vector pixel vec_vsx_ld (int, const vector pixel *); 14602vector signed short vec_vsx_ld (int, const vector signed short *); 14603vector signed short vec_vsx_ld (int, const short *); 14604vector unsigned short vec_vsx_ld (int, const vector unsigned short *); 14605vector unsigned short vec_vsx_ld (int, const unsigned short *); 14606vector bool char vec_vsx_ld (int, const vector bool char *); 14607vector signed char vec_vsx_ld (int, const vector signed char *); 14608vector signed char vec_vsx_ld (int, const signed char *); 14609vector unsigned char vec_vsx_ld (int, const vector unsigned char *); 14610vector unsigned char vec_vsx_ld (int, const unsigned char *); 14611 14612void vec_vsx_st (vector double, int, vector double *); 14613void vec_vsx_st (vector double, int, double *); 14614void vec_vsx_st (vector float, int, vector float *); 14615void vec_vsx_st (vector float, int, float *); 14616void vec_vsx_st (vector signed int, int, vector signed int *); 14617void vec_vsx_st (vector signed int, int, int *); 14618void vec_vsx_st (vector unsigned int, int, vector unsigned int *); 14619void vec_vsx_st (vector unsigned int, int, unsigned int *); 14620void vec_vsx_st (vector bool int, int, vector bool int *); 14621void vec_vsx_st (vector bool int, int, unsigned int *); 14622void vec_vsx_st (vector bool int, int, int *); 14623void vec_vsx_st (vector signed short, int, vector signed short *); 14624void vec_vsx_st (vector signed short, int, short *); 14625void vec_vsx_st (vector unsigned short, int, vector unsigned short *); 14626void vec_vsx_st (vector unsigned short, int, unsigned short *); 14627void vec_vsx_st (vector bool short, int, vector bool short *); 14628void vec_vsx_st (vector bool short, int, unsigned short *); 14629void vec_vsx_st (vector pixel, int, vector pixel *); 14630void vec_vsx_st (vector pixel, int, unsigned short *); 14631void vec_vsx_st (vector pixel, int, short *); 14632void vec_vsx_st (vector bool short, int, short *); 14633void vec_vsx_st (vector signed char, int, vector signed char *); 14634void vec_vsx_st (vector signed char, int, signed char *); 14635void vec_vsx_st (vector unsigned char, int, vector unsigned char *); 14636void vec_vsx_st (vector unsigned char, int, unsigned char *); 14637void vec_vsx_st (vector bool char, int, vector bool char *); 14638void vec_vsx_st (vector bool char, int, unsigned char *); 14639void vec_vsx_st (vector bool char, int, signed char *); 14640 14641vector double vec_xxpermdi (vector double, vector double, int); 14642vector float vec_xxpermdi (vector float, vector float, int); 14643vector long long vec_xxpermdi (vector long long, vector long long, int); 14644vector unsigned long long vec_xxpermdi (vector unsigned long long, 14645 vector unsigned long long, int); 14646vector int vec_xxpermdi (vector int, vector int, int); 14647vector unsigned int vec_xxpermdi (vector unsigned int, 14648 vector unsigned int, int); 14649vector short vec_xxpermdi (vector short, vector short, int); 14650vector unsigned short vec_xxpermdi (vector unsigned short, 14651 vector unsigned short, int); 14652vector signed char vec_xxpermdi (vector signed char, vector signed char, int); 14653vector unsigned char vec_xxpermdi (vector unsigned char, 14654 vector unsigned char, int); 14655 14656vector double vec_xxsldi (vector double, vector double, int); 14657vector float vec_xxsldi (vector float, vector float, int); 14658vector long long vec_xxsldi (vector long long, vector long long, int); 14659vector unsigned long long vec_xxsldi (vector unsigned long long, 14660 vector unsigned long long, int); 14661vector int vec_xxsldi (vector int, vector int, int); 14662vector unsigned int vec_xxsldi (vector unsigned int, vector unsigned int, int); 14663vector short vec_xxsldi (vector short, vector short, int); 14664vector unsigned short vec_xxsldi (vector unsigned short, 14665 vector unsigned short, int); 14666vector signed char vec_xxsldi (vector signed char, vector signed char, int); 14667vector unsigned char vec_xxsldi (vector unsigned char, 14668 vector unsigned char, int); 14669@end smallexample 14670 14671Note that the @samp{vec_ld} and @samp{vec_st} built-in functions always 14672generate the AltiVec @samp{LVX} and @samp{STVX} instructions even 14673if the VSX instruction set is available. The @samp{vec_vsx_ld} and 14674@samp{vec_vsx_st} built-in functions always generate the VSX @samp{LXVD2X}, 14675@samp{LXVW4X}, @samp{STXVD2X}, and @samp{STXVW4X} instructions. 14676 14677If the ISA 2.07 additions to the vector/scalar (power8-vector) 14678instruction set is available, the following additional functions are 14679available for both 32-bit and 64-bit targets. For 64-bit targets, you 14680can use @var{vector long} instead of @var{vector long long}, 14681@var{vector bool long} instead of @var{vector bool long long}, and 14682@var{vector unsigned long} instead of @var{vector unsigned long long}. 14683 14684@smallexample 14685vector long long vec_abs (vector long long); 14686 14687vector long long vec_add (vector long long, vector long long); 14688vector unsigned long long vec_add (vector unsigned long long, 14689 vector unsigned long long); 14690 14691int vec_all_eq (vector long long, vector long long); 14692int vec_all_eq (vector unsigned long long, vector unsigned long long); 14693int vec_all_ge (vector long long, vector long long); 14694int vec_all_ge (vector unsigned long long, vector unsigned long long); 14695int vec_all_gt (vector long long, vector long long); 14696int vec_all_gt (vector unsigned long long, vector unsigned long long); 14697int vec_all_le (vector long long, vector long long); 14698int vec_all_le (vector unsigned long long, vector unsigned long long); 14699int vec_all_lt (vector long long, vector long long); 14700int vec_all_lt (vector unsigned long long, vector unsigned long long); 14701int vec_all_ne (vector long long, vector long long); 14702int vec_all_ne (vector unsigned long long, vector unsigned long long); 14703 14704int vec_any_eq (vector long long, vector long long); 14705int vec_any_eq (vector unsigned long long, vector unsigned long long); 14706int vec_any_ge (vector long long, vector long long); 14707int vec_any_ge (vector unsigned long long, vector unsigned long long); 14708int vec_any_gt (vector long long, vector long long); 14709int vec_any_gt (vector unsigned long long, vector unsigned long long); 14710int vec_any_le (vector long long, vector long long); 14711int vec_any_le (vector unsigned long long, vector unsigned long long); 14712int vec_any_lt (vector long long, vector long long); 14713int vec_any_lt (vector unsigned long long, vector unsigned long long); 14714int vec_any_ne (vector long long, vector long long); 14715int vec_any_ne (vector unsigned long long, vector unsigned long long); 14716 14717vector long long vec_eqv (vector long long, vector long long); 14718vector long long vec_eqv (vector bool long long, vector long long); 14719vector long long vec_eqv (vector long long, vector bool long long); 14720vector unsigned long long vec_eqv (vector unsigned long long, 14721 vector unsigned long long); 14722vector unsigned long long vec_eqv (vector bool long long, 14723 vector unsigned long long); 14724vector unsigned long long vec_eqv (vector unsigned long long, 14725 vector bool long long); 14726vector int vec_eqv (vector int, vector int); 14727vector int vec_eqv (vector bool int, vector int); 14728vector int vec_eqv (vector int, vector bool int); 14729vector unsigned int vec_eqv (vector unsigned int, vector unsigned int); 14730vector unsigned int vec_eqv (vector bool unsigned int, 14731 vector unsigned int); 14732vector unsigned int vec_eqv (vector unsigned int, 14733 vector bool unsigned int); 14734vector short vec_eqv (vector short, vector short); 14735vector short vec_eqv (vector bool short, vector short); 14736vector short vec_eqv (vector short, vector bool short); 14737vector unsigned short vec_eqv (vector unsigned short, vector unsigned short); 14738vector unsigned short vec_eqv (vector bool unsigned short, 14739 vector unsigned short); 14740vector unsigned short vec_eqv (vector unsigned short, 14741 vector bool unsigned short); 14742vector signed char vec_eqv (vector signed char, vector signed char); 14743vector signed char vec_eqv (vector bool signed char, vector signed char); 14744vector signed char vec_eqv (vector signed char, vector bool signed char); 14745vector unsigned char vec_eqv (vector unsigned char, vector unsigned char); 14746vector unsigned char vec_eqv (vector bool unsigned char, vector unsigned char); 14747vector unsigned char vec_eqv (vector unsigned char, vector bool unsigned char); 14748 14749vector long long vec_max (vector long long, vector long long); 14750vector unsigned long long vec_max (vector unsigned long long, 14751 vector unsigned long long); 14752 14753vector signed int vec_mergee (vector signed int, vector signed int); 14754vector unsigned int vec_mergee (vector unsigned int, vector unsigned int); 14755vector bool int vec_mergee (vector bool int, vector bool int); 14756 14757vector signed int vec_mergeo (vector signed int, vector signed int); 14758vector unsigned int vec_mergeo (vector unsigned int, vector unsigned int); 14759vector bool int vec_mergeo (vector bool int, vector bool int); 14760 14761vector long long vec_min (vector long long, vector long long); 14762vector unsigned long long vec_min (vector unsigned long long, 14763 vector unsigned long long); 14764 14765vector long long vec_nand (vector long long, vector long long); 14766vector long long vec_nand (vector bool long long, vector long long); 14767vector long long vec_nand (vector long long, vector bool long long); 14768vector unsigned long long vec_nand (vector unsigned long long, 14769 vector unsigned long long); 14770vector unsigned long long vec_nand (vector bool long long, 14771 vector unsigned long long); 14772vector unsigned long long vec_nand (vector unsigned long long, 14773 vector bool long long); 14774vector int vec_nand (vector int, vector int); 14775vector int vec_nand (vector bool int, vector int); 14776vector int vec_nand (vector int, vector bool int); 14777vector unsigned int vec_nand (vector unsigned int, vector unsigned int); 14778vector unsigned int vec_nand (vector bool unsigned int, 14779 vector unsigned int); 14780vector unsigned int vec_nand (vector unsigned int, 14781 vector bool unsigned int); 14782vector short vec_nand (vector short, vector short); 14783vector short vec_nand (vector bool short, vector short); 14784vector short vec_nand (vector short, vector bool short); 14785vector unsigned short vec_nand (vector unsigned short, vector unsigned short); 14786vector unsigned short vec_nand (vector bool unsigned short, 14787 vector unsigned short); 14788vector unsigned short vec_nand (vector unsigned short, 14789 vector bool unsigned short); 14790vector signed char vec_nand (vector signed char, vector signed char); 14791vector signed char vec_nand (vector bool signed char, vector signed char); 14792vector signed char vec_nand (vector signed char, vector bool signed char); 14793vector unsigned char vec_nand (vector unsigned char, vector unsigned char); 14794vector unsigned char vec_nand (vector bool unsigned char, vector unsigned char); 14795vector unsigned char vec_nand (vector unsigned char, vector bool unsigned char); 14796 14797vector long long vec_orc (vector long long, vector long long); 14798vector long long vec_orc (vector bool long long, vector long long); 14799vector long long vec_orc (vector long long, vector bool long long); 14800vector unsigned long long vec_orc (vector unsigned long long, 14801 vector unsigned long long); 14802vector unsigned long long vec_orc (vector bool long long, 14803 vector unsigned long long); 14804vector unsigned long long vec_orc (vector unsigned long long, 14805 vector bool long long); 14806vector int vec_orc (vector int, vector int); 14807vector int vec_orc (vector bool int, vector int); 14808vector int vec_orc (vector int, vector bool int); 14809vector unsigned int vec_orc (vector unsigned int, vector unsigned int); 14810vector unsigned int vec_orc (vector bool unsigned int, 14811 vector unsigned int); 14812vector unsigned int vec_orc (vector unsigned int, 14813 vector bool unsigned int); 14814vector short vec_orc (vector short, vector short); 14815vector short vec_orc (vector bool short, vector short); 14816vector short vec_orc (vector short, vector bool short); 14817vector unsigned short vec_orc (vector unsigned short, vector unsigned short); 14818vector unsigned short vec_orc (vector bool unsigned short, 14819 vector unsigned short); 14820vector unsigned short vec_orc (vector unsigned short, 14821 vector bool unsigned short); 14822vector signed char vec_orc (vector signed char, vector signed char); 14823vector signed char vec_orc (vector bool signed char, vector signed char); 14824vector signed char vec_orc (vector signed char, vector bool signed char); 14825vector unsigned char vec_orc (vector unsigned char, vector unsigned char); 14826vector unsigned char vec_orc (vector bool unsigned char, vector unsigned char); 14827vector unsigned char vec_orc (vector unsigned char, vector bool unsigned char); 14828 14829vector int vec_pack (vector long long, vector long long); 14830vector unsigned int vec_pack (vector unsigned long long, 14831 vector unsigned long long); 14832vector bool int vec_pack (vector bool long long, vector bool long long); 14833 14834vector int vec_packs (vector long long, vector long long); 14835vector unsigned int vec_packs (vector unsigned long long, 14836 vector unsigned long long); 14837 14838vector unsigned int vec_packsu (vector long long, vector long long); 14839vector unsigned int vec_packsu (vector unsigned long long, 14840 vector unsigned long long); 14841 14842vector long long vec_rl (vector long long, 14843 vector unsigned long long); 14844vector long long vec_rl (vector unsigned long long, 14845 vector unsigned long long); 14846 14847vector long long vec_sl (vector long long, vector unsigned long long); 14848vector long long vec_sl (vector unsigned long long, 14849 vector unsigned long long); 14850 14851vector long long vec_sr (vector long long, vector unsigned long long); 14852vector unsigned long long char vec_sr (vector unsigned long long, 14853 vector unsigned long long); 14854 14855vector long long vec_sra (vector long long, vector unsigned long long); 14856vector unsigned long long vec_sra (vector unsigned long long, 14857 vector unsigned long long); 14858 14859vector long long vec_sub (vector long long, vector long long); 14860vector unsigned long long vec_sub (vector unsigned long long, 14861 vector unsigned long long); 14862 14863vector long long vec_unpackh (vector int); 14864vector unsigned long long vec_unpackh (vector unsigned int); 14865 14866vector long long vec_unpackl (vector int); 14867vector unsigned long long vec_unpackl (vector unsigned int); 14868 14869vector long long vec_vaddudm (vector long long, vector long long); 14870vector long long vec_vaddudm (vector bool long long, vector long long); 14871vector long long vec_vaddudm (vector long long, vector bool long long); 14872vector unsigned long long vec_vaddudm (vector unsigned long long, 14873 vector unsigned long long); 14874vector unsigned long long vec_vaddudm (vector bool unsigned long long, 14875 vector unsigned long long); 14876vector unsigned long long vec_vaddudm (vector unsigned long long, 14877 vector bool unsigned long long); 14878 14879vector long long vec_vbpermq (vector signed char, vector signed char); 14880vector long long vec_vbpermq (vector unsigned char, vector unsigned char); 14881 14882vector long long vec_cntlz (vector long long); 14883vector unsigned long long vec_cntlz (vector unsigned long long); 14884vector int vec_cntlz (vector int); 14885vector unsigned int vec_cntlz (vector int); 14886vector short vec_cntlz (vector short); 14887vector unsigned short vec_cntlz (vector unsigned short); 14888vector signed char vec_cntlz (vector signed char); 14889vector unsigned char vec_cntlz (vector unsigned char); 14890 14891vector long long vec_vclz (vector long long); 14892vector unsigned long long vec_vclz (vector unsigned long long); 14893vector int vec_vclz (vector int); 14894vector unsigned int vec_vclz (vector int); 14895vector short vec_vclz (vector short); 14896vector unsigned short vec_vclz (vector unsigned short); 14897vector signed char vec_vclz (vector signed char); 14898vector unsigned char vec_vclz (vector unsigned char); 14899 14900vector signed char vec_vclzb (vector signed char); 14901vector unsigned char vec_vclzb (vector unsigned char); 14902 14903vector long long vec_vclzd (vector long long); 14904vector unsigned long long vec_vclzd (vector unsigned long long); 14905 14906vector short vec_vclzh (vector short); 14907vector unsigned short vec_vclzh (vector unsigned short); 14908 14909vector int vec_vclzw (vector int); 14910vector unsigned int vec_vclzw (vector int); 14911 14912vector signed char vec_vgbbd (vector signed char); 14913vector unsigned char vec_vgbbd (vector unsigned char); 14914 14915vector long long vec_vmaxsd (vector long long, vector long long); 14916 14917vector unsigned long long vec_vmaxud (vector unsigned long long, 14918 unsigned vector long long); 14919 14920vector long long vec_vminsd (vector long long, vector long long); 14921 14922vector unsigned long long vec_vminud (vector long long, 14923 vector long long); 14924 14925vector int vec_vpksdss (vector long long, vector long long); 14926vector unsigned int vec_vpksdss (vector long long, vector long long); 14927 14928vector unsigned int vec_vpkudus (vector unsigned long long, 14929 vector unsigned long long); 14930 14931vector int vec_vpkudum (vector long long, vector long long); 14932vector unsigned int vec_vpkudum (vector unsigned long long, 14933 vector unsigned long long); 14934vector bool int vec_vpkudum (vector bool long long, vector bool long long); 14935 14936vector long long vec_vpopcnt (vector long long); 14937vector unsigned long long vec_vpopcnt (vector unsigned long long); 14938vector int vec_vpopcnt (vector int); 14939vector unsigned int vec_vpopcnt (vector int); 14940vector short vec_vpopcnt (vector short); 14941vector unsigned short vec_vpopcnt (vector unsigned short); 14942vector signed char vec_vpopcnt (vector signed char); 14943vector unsigned char vec_vpopcnt (vector unsigned char); 14944 14945vector signed char vec_vpopcntb (vector signed char); 14946vector unsigned char vec_vpopcntb (vector unsigned char); 14947 14948vector long long vec_vpopcntd (vector long long); 14949vector unsigned long long vec_vpopcntd (vector unsigned long long); 14950 14951vector short vec_vpopcnth (vector short); 14952vector unsigned short vec_vpopcnth (vector unsigned short); 14953 14954vector int vec_vpopcntw (vector int); 14955vector unsigned int vec_vpopcntw (vector int); 14956 14957vector long long vec_vrld (vector long long, vector unsigned long long); 14958vector unsigned long long vec_vrld (vector unsigned long long, 14959 vector unsigned long long); 14960 14961vector long long vec_vsld (vector long long, vector unsigned long long); 14962vector long long vec_vsld (vector unsigned long long, 14963 vector unsigned long long); 14964 14965vector long long vec_vsrad (vector long long, vector unsigned long long); 14966vector unsigned long long vec_vsrad (vector unsigned long long, 14967 vector unsigned long long); 14968 14969vector long long vec_vsrd (vector long long, vector unsigned long long); 14970vector unsigned long long char vec_vsrd (vector unsigned long long, 14971 vector unsigned long long); 14972 14973vector long long vec_vsubudm (vector long long, vector long long); 14974vector long long vec_vsubudm (vector bool long long, vector long long); 14975vector long long vec_vsubudm (vector long long, vector bool long long); 14976vector unsigned long long vec_vsubudm (vector unsigned long long, 14977 vector unsigned long long); 14978vector unsigned long long vec_vsubudm (vector bool long long, 14979 vector unsigned long long); 14980vector unsigned long long vec_vsubudm (vector unsigned long long, 14981 vector bool long long); 14982 14983vector long long vec_vupkhsw (vector int); 14984vector unsigned long long vec_vupkhsw (vector unsigned int); 14985 14986vector long long vec_vupklsw (vector int); 14987vector unsigned long long vec_vupklsw (vector int); 14988@end smallexample 14989 14990If the ISA 2.07 additions to the vector/scalar (power8-vector) 14991instruction set is available, the following additional functions are 14992available for 64-bit targets. New vector types 14993(@var{vector __int128_t} and @var{vector __uint128_t}) are available 14994to hold the @var{__int128_t} and @var{__uint128_t} types to use these 14995builtins. 14996 14997The normal vector extract, and set operations work on 14998@var{vector __int128_t} and @var{vector __uint128_t} types, 14999but the index value must be 0. 15000 15001@smallexample 15002vector __int128_t vec_vaddcuq (vector __int128_t, vector __int128_t); 15003vector __uint128_t vec_vaddcuq (vector __uint128_t, vector __uint128_t); 15004 15005vector __int128_t vec_vadduqm (vector __int128_t, vector __int128_t); 15006vector __uint128_t vec_vadduqm (vector __uint128_t, vector __uint128_t); 15007 15008vector __int128_t vec_vaddecuq (vector __int128_t, vector __int128_t, 15009 vector __int128_t); 15010vector __uint128_t vec_vaddecuq (vector __uint128_t, vector __uint128_t, 15011 vector __uint128_t); 15012 15013vector __int128_t vec_vaddeuqm (vector __int128_t, vector __int128_t, 15014 vector __int128_t); 15015vector __uint128_t vec_vaddeuqm (vector __uint128_t, vector __uint128_t, 15016 vector __uint128_t); 15017 15018vector __int128_t vec_vsubecuq (vector __int128_t, vector __int128_t, 15019 vector __int128_t); 15020vector __uint128_t vec_vsubecuq (vector __uint128_t, vector __uint128_t, 15021 vector __uint128_t); 15022 15023vector __int128_t vec_vsubeuqm (vector __int128_t, vector __int128_t, 15024 vector __int128_t); 15025vector __uint128_t vec_vsubeuqm (vector __uint128_t, vector __uint128_t, 15026 vector __uint128_t); 15027 15028vector __int128_t vec_vsubcuq (vector __int128_t, vector __int128_t); 15029vector __uint128_t vec_vsubcuq (vector __uint128_t, vector __uint128_t); 15030 15031__int128_t vec_vsubuqm (__int128_t, __int128_t); 15032__uint128_t vec_vsubuqm (__uint128_t, __uint128_t); 15033 15034vector __int128_t __builtin_bcdadd (vector __int128_t, vector__int128_t); 15035int __builtin_bcdadd_lt (vector __int128_t, vector__int128_t); 15036int __builtin_bcdadd_eq (vector __int128_t, vector__int128_t); 15037int __builtin_bcdadd_gt (vector __int128_t, vector__int128_t); 15038int __builtin_bcdadd_ov (vector __int128_t, vector__int128_t); 15039vector __int128_t bcdsub (vector __int128_t, vector__int128_t); 15040int __builtin_bcdsub_lt (vector __int128_t, vector__int128_t); 15041int __builtin_bcdsub_eq (vector __int128_t, vector__int128_t); 15042int __builtin_bcdsub_gt (vector __int128_t, vector__int128_t); 15043int __builtin_bcdsub_ov (vector __int128_t, vector__int128_t); 15044@end smallexample 15045 15046If the cryptographic instructions are enabled (@option{-mcrypto} or 15047@option{-mcpu=power8}), the following builtins are enabled. 15048 15049@smallexample 15050vector unsigned long long __builtin_crypto_vsbox (vector unsigned long long); 15051 15052vector unsigned long long __builtin_crypto_vcipher (vector unsigned long long, 15053 vector unsigned long long); 15054 15055vector unsigned long long __builtin_crypto_vcipherlast 15056 (vector unsigned long long, 15057 vector unsigned long long); 15058 15059vector unsigned long long __builtin_crypto_vncipher (vector unsigned long long, 15060 vector unsigned long long); 15061 15062vector unsigned long long __builtin_crypto_vncipherlast 15063 (vector unsigned long long, 15064 vector unsigned long long); 15065 15066vector unsigned char __builtin_crypto_vpermxor (vector unsigned char, 15067 vector unsigned char, 15068 vector unsigned char); 15069 15070vector unsigned short __builtin_crypto_vpermxor (vector unsigned short, 15071 vector unsigned short, 15072 vector unsigned short); 15073 15074vector unsigned int __builtin_crypto_vpermxor (vector unsigned int, 15075 vector unsigned int, 15076 vector unsigned int); 15077 15078vector unsigned long long __builtin_crypto_vpermxor (vector unsigned long long, 15079 vector unsigned long long, 15080 vector unsigned long long); 15081 15082vector unsigned char __builtin_crypto_vpmsumb (vector unsigned char, 15083 vector unsigned char); 15084 15085vector unsigned short __builtin_crypto_vpmsumb (vector unsigned short, 15086 vector unsigned short); 15087 15088vector unsigned int __builtin_crypto_vpmsumb (vector unsigned int, 15089 vector unsigned int); 15090 15091vector unsigned long long __builtin_crypto_vpmsumb (vector unsigned long long, 15092 vector unsigned long long); 15093 15094vector unsigned long long __builtin_crypto_vshasigmad 15095 (vector unsigned long long, int, int); 15096 15097vector unsigned int __builtin_crypto_vshasigmaw (vector unsigned int, 15098 int, int); 15099@end smallexample 15100 15101The second argument to the @var{__builtin_crypto_vshasigmad} and 15102@var{__builtin_crypto_vshasigmaw} builtin functions must be a constant 15103integer that is 0 or 1. The third argument to these builtin functions 15104must be a constant integer in the range of 0 to 15. 15105 15106@node PowerPC Hardware Transactional Memory Built-in Functions 15107@subsection PowerPC Hardware Transactional Memory Built-in Functions 15108GCC provides two interfaces for accessing the Hardware Transactional 15109Memory (HTM) instructions available on some of the PowerPC family 15110of processors (eg, POWER8). The two interfaces come in a low level 15111interface, consisting of built-in functions specific to PowerPC and a 15112higher level interface consisting of inline functions that are common 15113between PowerPC and S/390. 15114 15115@subsubsection PowerPC HTM Low Level Built-in Functions 15116 15117The following low level built-in functions are available with 15118@option{-mhtm} or @option{-mcpu=CPU} where CPU is `power8' or later. 15119They all generate the machine instruction that is part of the name. 15120 15121The HTM builtins (with the exception of @code{__builtin_tbegin}) return 15122the full 4-bit condition register value set by their associated hardware 15123instruction. The header file @code{htmintrin.h} defines some macros that can 15124be used to decipher the return value. The @code{__builtin_tbegin} builtin 15125returns a simple true or false value depending on whether a transaction was 15126successfully started or not. The arguments of the builtins match exactly the 15127type and order of the associated hardware instruction's operands, except for 15128the @code{__builtin_tcheck} builtin, which does not take any input arguments. 15129Refer to the ISA manual for a description of each instruction's operands. 15130 15131@smallexample 15132unsigned int __builtin_tbegin (unsigned int) 15133unsigned int __builtin_tend (unsigned int) 15134 15135unsigned int __builtin_tabort (unsigned int) 15136unsigned int __builtin_tabortdc (unsigned int, unsigned int, unsigned int) 15137unsigned int __builtin_tabortdci (unsigned int, unsigned int, int) 15138unsigned int __builtin_tabortwc (unsigned int, unsigned int, unsigned int) 15139unsigned int __builtin_tabortwci (unsigned int, unsigned int, int) 15140 15141unsigned int __builtin_tcheck (void) 15142unsigned int __builtin_treclaim (unsigned int) 15143unsigned int __builtin_trechkpt (void) 15144unsigned int __builtin_tsr (unsigned int) 15145@end smallexample 15146 15147In addition to the above HTM built-ins, we have added built-ins for 15148some common extended mnemonics of the HTM instructions: 15149 15150@smallexample 15151unsigned int __builtin_tendall (void) 15152unsigned int __builtin_tresume (void) 15153unsigned int __builtin_tsuspend (void) 15154@end smallexample 15155 15156Note that the semantics of the above HTM builtins are required to mimic 15157the locking semantics used for critical sections. Builtins that are used 15158to create a new transaction or restart a suspended transaction must have 15159lock acquisition like semantics while those builtins that end or suspend a 15160transaction must have lock release like semantics. Specifically, this must 15161mimic lock semantics as specified by C++11, for example: Lock acquisition is 15162as-if an execution of __atomic_exchange_n(&globallock,1,__ATOMIC_ACQUIRE) 15163that returns 0, and lock release is as-if an execution of 15164__atomic_store(&globallock,0,__ATOMIC_RELEASE), with globallock being an 15165implicit implementation-defined lock used for all transactions. The HTM 15166instructions associated with with the builtins inherently provide the 15167correct acquisition and release hardware barriers required. However, 15168the compiler must also be prohibited from moving loads and stores across 15169the builtins in a way that would violate their semantics. This has been 15170accomplished by adding memory barriers to the associated HTM instructions 15171(which is a conservative approach to provide acquire and release semantics). 15172Earlier versions of the compiler did not treat the HTM instructions as 15173memory barriers. A @code{__TM_FENCE__} macro has been added, which can 15174be used to determine whether the current compiler treats HTM instructions 15175as memory barriers or not. This allows the user to explicitly add memory 15176barriers to their code when using an older version of the compiler. 15177 15178The following set of built-in functions are available to gain access 15179to the HTM specific special purpose registers. 15180 15181@smallexample 15182unsigned long __builtin_get_texasr (void) 15183unsigned long __builtin_get_texasru (void) 15184unsigned long __builtin_get_tfhar (void) 15185unsigned long __builtin_get_tfiar (void) 15186 15187void __builtin_set_texasr (unsigned long); 15188void __builtin_set_texasru (unsigned long); 15189void __builtin_set_tfhar (unsigned long); 15190void __builtin_set_tfiar (unsigned long); 15191@end smallexample 15192 15193Example usage of these low level built-in functions may look like: 15194 15195@smallexample 15196#include <htmintrin.h> 15197 15198int num_retries = 10; 15199 15200while (1) 15201 @{ 15202 if (__builtin_tbegin (0)) 15203 @{ 15204 /* Transaction State Initiated. */ 15205 if (is_locked (lock)) 15206 __builtin_tabort (0); 15207 ... transaction code... 15208 __builtin_tend (0); 15209 break; 15210 @} 15211 else 15212 @{ 15213 /* Transaction State Failed. Use locks if the transaction 15214 failure is "persistent" or we've tried too many times. */ 15215 if (num_retries-- <= 0 15216 || _TEXASRU_FAILURE_PERSISTENT (__builtin_get_texasru ())) 15217 @{ 15218 acquire_lock (lock); 15219 ... non transactional fallback path... 15220 release_lock (lock); 15221 break; 15222 @} 15223 @} 15224 @} 15225@end smallexample 15226 15227One final built-in function has been added that returns the value of 15228the 2-bit Transaction State field of the Machine Status Register (MSR) 15229as stored in @code{CR0}. 15230 15231@smallexample 15232unsigned long __builtin_ttest (void) 15233@end smallexample 15234 15235This built-in can be used to determine the current transaction state 15236using the following code example: 15237 15238@smallexample 15239#include <htmintrin.h> 15240 15241unsigned char tx_state = _HTM_STATE (__builtin_ttest ()); 15242 15243if (tx_state == _HTM_TRANSACTIONAL) 15244 @{ 15245 /* Code to use in transactional state. */ 15246 @} 15247else if (tx_state == _HTM_NONTRANSACTIONAL) 15248 @{ 15249 /* Code to use in non-transactional state. */ 15250 @} 15251else if (tx_state == _HTM_SUSPENDED) 15252 @{ 15253 /* Code to use in transaction suspended state. */ 15254 @} 15255@end smallexample 15256 15257@subsubsection PowerPC HTM High Level Inline Functions 15258 15259The following high level HTM interface is made available by including 15260@code{<htmxlintrin.h>} and using @option{-mhtm} or @option{-mcpu=CPU} 15261where CPU is `power8' or later. This interface is common between PowerPC 15262and S/390, allowing users to write one HTM source implementation that 15263can be compiled and executed on either system. 15264 15265@smallexample 15266long __TM_simple_begin (void) 15267long __TM_begin (void* const TM_buff) 15268long __TM_end (void) 15269void __TM_abort (void) 15270void __TM_named_abort (unsigned char const code) 15271void __TM_resume (void) 15272void __TM_suspend (void) 15273 15274long __TM_is_user_abort (void* const TM_buff) 15275long __TM_is_named_user_abort (void* const TM_buff, unsigned char *code) 15276long __TM_is_illegal (void* const TM_buff) 15277long __TM_is_footprint_exceeded (void* const TM_buff) 15278long __TM_nesting_depth (void* const TM_buff) 15279long __TM_is_nested_too_deep(void* const TM_buff) 15280long __TM_is_conflict(void* const TM_buff) 15281long __TM_is_failure_persistent(void* const TM_buff) 15282long __TM_failure_address(void* const TM_buff) 15283long long __TM_failure_code(void* const TM_buff) 15284@end smallexample 15285 15286Using these common set of HTM inline functions, we can create 15287a more portable version of the HTM example in the previous 15288section that will work on either PowerPC or S/390: 15289 15290@smallexample 15291#include <htmxlintrin.h> 15292 15293int num_retries = 10; 15294TM_buff_type TM_buff; 15295 15296while (1) 15297 @{ 15298 if (__TM_begin (TM_buff) == _HTM_TBEGIN_STARTED) 15299 @{ 15300 /* Transaction State Initiated. */ 15301 if (is_locked (lock)) 15302 __TM_abort (); 15303 ... transaction code... 15304 __TM_end (); 15305 break; 15306 @} 15307 else 15308 @{ 15309 /* Transaction State Failed. Use locks if the transaction 15310 failure is "persistent" or we've tried too many times. */ 15311 if (num_retries-- <= 0 15312 || __TM_is_failure_persistent (TM_buff)) 15313 @{ 15314 acquire_lock (lock); 15315 ... non transactional fallback path... 15316 release_lock (lock); 15317 break; 15318 @} 15319 @} 15320 @} 15321@end smallexample 15322 15323@node RX Built-in Functions 15324@subsection RX Built-in Functions 15325GCC supports some of the RX instructions which cannot be expressed in 15326the C programming language via the use of built-in functions. The 15327following functions are supported: 15328 15329@deftypefn {Built-in Function} void __builtin_rx_brk (void) 15330Generates the @code{brk} machine instruction. 15331@end deftypefn 15332 15333@deftypefn {Built-in Function} void __builtin_rx_clrpsw (int) 15334Generates the @code{clrpsw} machine instruction to clear the specified 15335bit in the processor status word. 15336@end deftypefn 15337 15338@deftypefn {Built-in Function} void __builtin_rx_int (int) 15339Generates the @code{int} machine instruction to generate an interrupt 15340with the specified value. 15341@end deftypefn 15342 15343@deftypefn {Built-in Function} void __builtin_rx_machi (int, int) 15344Generates the @code{machi} machine instruction to add the result of 15345multiplying the top 16 bits of the two arguments into the 15346accumulator. 15347@end deftypefn 15348 15349@deftypefn {Built-in Function} void __builtin_rx_maclo (int, int) 15350Generates the @code{maclo} machine instruction to add the result of 15351multiplying the bottom 16 bits of the two arguments into the 15352accumulator. 15353@end deftypefn 15354 15355@deftypefn {Built-in Function} void __builtin_rx_mulhi (int, int) 15356Generates the @code{mulhi} machine instruction to place the result of 15357multiplying the top 16 bits of the two arguments into the 15358accumulator. 15359@end deftypefn 15360 15361@deftypefn {Built-in Function} void __builtin_rx_mullo (int, int) 15362Generates the @code{mullo} machine instruction to place the result of 15363multiplying the bottom 16 bits of the two arguments into the 15364accumulator. 15365@end deftypefn 15366 15367@deftypefn {Built-in Function} int __builtin_rx_mvfachi (void) 15368Generates the @code{mvfachi} machine instruction to read the top 1536932 bits of the accumulator. 15370@end deftypefn 15371 15372@deftypefn {Built-in Function} int __builtin_rx_mvfacmi (void) 15373Generates the @code{mvfacmi} machine instruction to read the middle 1537432 bits of the accumulator. 15375@end deftypefn 15376 15377@deftypefn {Built-in Function} int __builtin_rx_mvfc (int) 15378Generates the @code{mvfc} machine instruction which reads the control 15379register specified in its argument and returns its value. 15380@end deftypefn 15381 15382@deftypefn {Built-in Function} void __builtin_rx_mvtachi (int) 15383Generates the @code{mvtachi} machine instruction to set the top 1538432 bits of the accumulator. 15385@end deftypefn 15386 15387@deftypefn {Built-in Function} void __builtin_rx_mvtaclo (int) 15388Generates the @code{mvtaclo} machine instruction to set the bottom 1538932 bits of the accumulator. 15390@end deftypefn 15391 15392@deftypefn {Built-in Function} void __builtin_rx_mvtc (int reg, int val) 15393Generates the @code{mvtc} machine instruction which sets control 15394register number @code{reg} to @code{val}. 15395@end deftypefn 15396 15397@deftypefn {Built-in Function} void __builtin_rx_mvtipl (int) 15398Generates the @code{mvtipl} machine instruction set the interrupt 15399priority level. 15400@end deftypefn 15401 15402@deftypefn {Built-in Function} void __builtin_rx_racw (int) 15403Generates the @code{racw} machine instruction to round the accumulator 15404according to the specified mode. 15405@end deftypefn 15406 15407@deftypefn {Built-in Function} int __builtin_rx_revw (int) 15408Generates the @code{revw} machine instruction which swaps the bytes in 15409the argument so that bits 0--7 now occupy bits 8--15 and vice versa, 15410and also bits 16--23 occupy bits 24--31 and vice versa. 15411@end deftypefn 15412 15413@deftypefn {Built-in Function} void __builtin_rx_rmpa (void) 15414Generates the @code{rmpa} machine instruction which initiates a 15415repeated multiply and accumulate sequence. 15416@end deftypefn 15417 15418@deftypefn {Built-in Function} void __builtin_rx_round (float) 15419Generates the @code{round} machine instruction which returns the 15420floating-point argument rounded according to the current rounding mode 15421set in the floating-point status word register. 15422@end deftypefn 15423 15424@deftypefn {Built-in Function} int __builtin_rx_sat (int) 15425Generates the @code{sat} machine instruction which returns the 15426saturated value of the argument. 15427@end deftypefn 15428 15429@deftypefn {Built-in Function} void __builtin_rx_setpsw (int) 15430Generates the @code{setpsw} machine instruction to set the specified 15431bit in the processor status word. 15432@end deftypefn 15433 15434@deftypefn {Built-in Function} void __builtin_rx_wait (void) 15435Generates the @code{wait} machine instruction. 15436@end deftypefn 15437 15438@node S/390 System z Built-in Functions 15439@subsection S/390 System z Built-in Functions 15440@deftypefn {Built-in Function} int __builtin_tbegin (void*) 15441Generates the @code{tbegin} machine instruction starting a 15442non-constraint hardware transaction. If the parameter is non-NULL the 15443memory area is used to store the transaction diagnostic buffer and 15444will be passed as first operand to @code{tbegin}. This buffer can be 15445defined using the @code{struct __htm_tdb} C struct defined in 15446@code{htmintrin.h} and must reside on a double-word boundary. The 15447second tbegin operand is set to @code{0xff0c}. This enables 15448save/restore of all GPRs and disables aborts for FPR and AR 15449manipulations inside the transaction body. The condition code set by 15450the tbegin instruction is returned as integer value. The tbegin 15451instruction by definition overwrites the content of all FPRs. The 15452compiler will generate code which saves and restores the FPRs. For 15453soft-float code it is recommended to used the @code{*_nofloat} 15454variant. In order to prevent a TDB from being written it is required 15455to pass an constant zero value as parameter. Passing the zero value 15456through a variable is not sufficient. Although modifications of 15457access registers inside the transaction will not trigger an 15458transaction abort it is not supported to actually modify them. Access 15459registers do not get saved when entering a transaction. They will have 15460undefined state when reaching the abort code. 15461@end deftypefn 15462 15463Macros for the possible return codes of tbegin are defined in the 15464@code{htmintrin.h} header file: 15465 15466@table @code 15467@item _HTM_TBEGIN_STARTED 15468@code{tbegin} has been executed as part of normal processing. The 15469transaction body is supposed to be executed. 15470@item _HTM_TBEGIN_INDETERMINATE 15471The transaction was aborted due to an indeterminate condition which 15472might be persistent. 15473@item _HTM_TBEGIN_TRANSIENT 15474The transaction aborted due to a transient failure. The transaction 15475should be re-executed in that case. 15476@item _HTM_TBEGIN_PERSISTENT 15477The transaction aborted due to a persistent failure. Re-execution 15478under same circumstances will not be productive. 15479@end table 15480 15481@defmac _HTM_FIRST_USER_ABORT_CODE 15482The @code{_HTM_FIRST_USER_ABORT_CODE} defined in @code{htmintrin.h} 15483specifies the first abort code which can be used for 15484@code{__builtin_tabort}. Values below this threshold are reserved for 15485machine use. 15486@end defmac 15487 15488@deftp {Data type} {struct __htm_tdb} 15489The @code{struct __htm_tdb} defined in @code{htmintrin.h} describes 15490the structure of the transaction diagnostic block as specified in the 15491Principles of Operation manual chapter 5-91. 15492@end deftp 15493 15494@deftypefn {Built-in Function} int __builtin_tbegin_nofloat (void*) 15495Same as @code{__builtin_tbegin} but without FPR saves and restores. 15496Using this variant in code making use of FPRs will leave the FPRs in 15497undefined state when entering the transaction abort handler code. 15498@end deftypefn 15499 15500@deftypefn {Built-in Function} int __builtin_tbegin_retry (void*, int) 15501In addition to @code{__builtin_tbegin} a loop for transient failures 15502is generated. If tbegin returns a condition code of 2 the transaction 15503will be retried as often as specified in the second argument. The 15504perform processor assist instruction is used to tell the CPU about the 15505number of fails so far. 15506@end deftypefn 15507 15508@deftypefn {Built-in Function} int __builtin_tbegin_retry_nofloat (void*, int) 15509Same as @code{__builtin_tbegin_retry} but without FPR saves and 15510restores. Using this variant in code making use of FPRs will leave 15511the FPRs in undefined state when entering the transaction abort 15512handler code. 15513@end deftypefn 15514 15515@deftypefn {Built-in Function} void __builtin_tbeginc (void) 15516Generates the @code{tbeginc} machine instruction starting a constraint 15517hardware transaction. The second operand is set to @code{0xff08}. 15518@end deftypefn 15519 15520@deftypefn {Built-in Function} int __builtin_tend (void) 15521Generates the @code{tend} machine instruction finishing a transaction 15522and making the changes visible to other threads. The condition code 15523generated by tend is returned as integer value. 15524@end deftypefn 15525 15526@deftypefn {Built-in Function} void __builtin_tabort (int) 15527Generates the @code{tabort} machine instruction with the specified 15528abort code. Abort codes from 0 through 255 are reserved and will 15529result in an error message. 15530@end deftypefn 15531 15532@deftypefn {Built-in Function} void __builtin_tx_assist (int) 15533Generates the @code{ppa rX,rY,1} machine instruction. Where the 15534integer parameter is loaded into rX and a value of zero is loaded into 15535rY. The integer parameter specifies the number of times the 15536transaction repeatedly aborted. 15537@end deftypefn 15538 15539@deftypefn {Built-in Function} int __builtin_tx_nesting_depth (void) 15540Generates the @code{etnd} machine instruction. The current nesting 15541depth is returned as integer value. For a nesting depth of 0 the code 15542is not executed as part of an transaction. 15543@end deftypefn 15544 15545@deftypefn {Built-in Function} void __builtin_non_tx_store (uint64_t *, uint64_t) 15546 15547Generates the @code{ntstg} machine instruction. The second argument 15548is written to the first arguments location. The store operation will 15549not be rolled-back in case of an transaction abort. 15550@end deftypefn 15551 15552@node SH Built-in Functions 15553@subsection SH Built-in Functions 15554The following built-in functions are supported on the SH1, SH2, SH3 and SH4 15555families of processors: 15556 15557@deftypefn {Built-in Function} {void} __builtin_set_thread_pointer (void *@var{ptr}) 15558Sets the @samp{GBR} register to the specified value @var{ptr}. This is usually 15559used by system code that manages threads and execution contexts. The compiler 15560normally does not generate code that modifies the contents of @samp{GBR} and 15561thus the value is preserved across function calls. Changing the @samp{GBR} 15562value in user code must be done with caution, since the compiler might use 15563@samp{GBR} in order to access thread local variables. 15564 15565@end deftypefn 15566 15567@deftypefn {Built-in Function} {void *} __builtin_thread_pointer (void) 15568Returns the value that is currently set in the @samp{GBR} register. 15569Memory loads and stores that use the thread pointer as a base address are 15570turned into @samp{GBR} based displacement loads and stores, if possible. 15571For example: 15572@smallexample 15573struct my_tcb 15574@{ 15575 int a, b, c, d, e; 15576@}; 15577 15578int get_tcb_value (void) 15579@{ 15580 // Generate @samp{mov.l @@(8,gbr),r0} instruction 15581 return ((my_tcb*)__builtin_thread_pointer ())->c; 15582@} 15583 15584@end smallexample 15585@end deftypefn 15586 15587@deftypefn {Built-in Function} {unsigned int} __builtin_sh_get_fpscr (void) 15588Returns the value that is currently set in the @samp{FPSCR} register. 15589@end deftypefn 15590 15591@deftypefn {Built-in Function} {void} __builtin_sh_set_fpscr (unsigned int @var{val}) 15592Sets the @samp{FPSCR} register to the specified value @var{val}, while 15593preserving the current values of the FR, SZ and PR bits. 15594@end deftypefn 15595 15596@node SPARC VIS Built-in Functions 15597@subsection SPARC VIS Built-in Functions 15598 15599GCC supports SIMD operations on the SPARC using both the generic vector 15600extensions (@pxref{Vector Extensions}) as well as built-in functions for 15601the SPARC Visual Instruction Set (VIS). When you use the @option{-mvis} 15602switch, the VIS extension is exposed as the following built-in functions: 15603 15604@smallexample 15605typedef int v1si __attribute__ ((vector_size (4))); 15606typedef int v2si __attribute__ ((vector_size (8))); 15607typedef short v4hi __attribute__ ((vector_size (8))); 15608typedef short v2hi __attribute__ ((vector_size (4))); 15609typedef unsigned char v8qi __attribute__ ((vector_size (8))); 15610typedef unsigned char v4qi __attribute__ ((vector_size (4))); 15611 15612void __builtin_vis_write_gsr (int64_t); 15613int64_t __builtin_vis_read_gsr (void); 15614 15615void * __builtin_vis_alignaddr (void *, long); 15616void * __builtin_vis_alignaddrl (void *, long); 15617int64_t __builtin_vis_faligndatadi (int64_t, int64_t); 15618v2si __builtin_vis_faligndatav2si (v2si, v2si); 15619v4hi __builtin_vis_faligndatav4hi (v4si, v4si); 15620v8qi __builtin_vis_faligndatav8qi (v8qi, v8qi); 15621 15622v4hi __builtin_vis_fexpand (v4qi); 15623 15624v4hi __builtin_vis_fmul8x16 (v4qi, v4hi); 15625v4hi __builtin_vis_fmul8x16au (v4qi, v2hi); 15626v4hi __builtin_vis_fmul8x16al (v4qi, v2hi); 15627v4hi __builtin_vis_fmul8sux16 (v8qi, v4hi); 15628v4hi __builtin_vis_fmul8ulx16 (v8qi, v4hi); 15629v2si __builtin_vis_fmuld8sux16 (v4qi, v2hi); 15630v2si __builtin_vis_fmuld8ulx16 (v4qi, v2hi); 15631 15632v4qi __builtin_vis_fpack16 (v4hi); 15633v8qi __builtin_vis_fpack32 (v2si, v8qi); 15634v2hi __builtin_vis_fpackfix (v2si); 15635v8qi __builtin_vis_fpmerge (v4qi, v4qi); 15636 15637int64_t __builtin_vis_pdist (v8qi, v8qi, int64_t); 15638 15639long __builtin_vis_edge8 (void *, void *); 15640long __builtin_vis_edge8l (void *, void *); 15641long __builtin_vis_edge16 (void *, void *); 15642long __builtin_vis_edge16l (void *, void *); 15643long __builtin_vis_edge32 (void *, void *); 15644long __builtin_vis_edge32l (void *, void *); 15645 15646long __builtin_vis_fcmple16 (v4hi, v4hi); 15647long __builtin_vis_fcmple32 (v2si, v2si); 15648long __builtin_vis_fcmpne16 (v4hi, v4hi); 15649long __builtin_vis_fcmpne32 (v2si, v2si); 15650long __builtin_vis_fcmpgt16 (v4hi, v4hi); 15651long __builtin_vis_fcmpgt32 (v2si, v2si); 15652long __builtin_vis_fcmpeq16 (v4hi, v4hi); 15653long __builtin_vis_fcmpeq32 (v2si, v2si); 15654 15655v4hi __builtin_vis_fpadd16 (v4hi, v4hi); 15656v2hi __builtin_vis_fpadd16s (v2hi, v2hi); 15657v2si __builtin_vis_fpadd32 (v2si, v2si); 15658v1si __builtin_vis_fpadd32s (v1si, v1si); 15659v4hi __builtin_vis_fpsub16 (v4hi, v4hi); 15660v2hi __builtin_vis_fpsub16s (v2hi, v2hi); 15661v2si __builtin_vis_fpsub32 (v2si, v2si); 15662v1si __builtin_vis_fpsub32s (v1si, v1si); 15663 15664long __builtin_vis_array8 (long, long); 15665long __builtin_vis_array16 (long, long); 15666long __builtin_vis_array32 (long, long); 15667@end smallexample 15668 15669When you use the @option{-mvis2} switch, the VIS version 2.0 built-in 15670functions also become available: 15671 15672@smallexample 15673long __builtin_vis_bmask (long, long); 15674int64_t __builtin_vis_bshuffledi (int64_t, int64_t); 15675v2si __builtin_vis_bshufflev2si (v2si, v2si); 15676v4hi __builtin_vis_bshufflev2si (v4hi, v4hi); 15677v8qi __builtin_vis_bshufflev2si (v8qi, v8qi); 15678 15679long __builtin_vis_edge8n (void *, void *); 15680long __builtin_vis_edge8ln (void *, void *); 15681long __builtin_vis_edge16n (void *, void *); 15682long __builtin_vis_edge16ln (void *, void *); 15683long __builtin_vis_edge32n (void *, void *); 15684long __builtin_vis_edge32ln (void *, void *); 15685@end smallexample 15686 15687When you use the @option{-mvis3} switch, the VIS version 3.0 built-in 15688functions also become available: 15689 15690@smallexample 15691void __builtin_vis_cmask8 (long); 15692void __builtin_vis_cmask16 (long); 15693void __builtin_vis_cmask32 (long); 15694 15695v4hi __builtin_vis_fchksm16 (v4hi, v4hi); 15696 15697v4hi __builtin_vis_fsll16 (v4hi, v4hi); 15698v4hi __builtin_vis_fslas16 (v4hi, v4hi); 15699v4hi __builtin_vis_fsrl16 (v4hi, v4hi); 15700v4hi __builtin_vis_fsra16 (v4hi, v4hi); 15701v2si __builtin_vis_fsll16 (v2si, v2si); 15702v2si __builtin_vis_fslas16 (v2si, v2si); 15703v2si __builtin_vis_fsrl16 (v2si, v2si); 15704v2si __builtin_vis_fsra16 (v2si, v2si); 15705 15706long __builtin_vis_pdistn (v8qi, v8qi); 15707 15708v4hi __builtin_vis_fmean16 (v4hi, v4hi); 15709 15710int64_t __builtin_vis_fpadd64 (int64_t, int64_t); 15711int64_t __builtin_vis_fpsub64 (int64_t, int64_t); 15712 15713v4hi __builtin_vis_fpadds16 (v4hi, v4hi); 15714v2hi __builtin_vis_fpadds16s (v2hi, v2hi); 15715v4hi __builtin_vis_fpsubs16 (v4hi, v4hi); 15716v2hi __builtin_vis_fpsubs16s (v2hi, v2hi); 15717v2si __builtin_vis_fpadds32 (v2si, v2si); 15718v1si __builtin_vis_fpadds32s (v1si, v1si); 15719v2si __builtin_vis_fpsubs32 (v2si, v2si); 15720v1si __builtin_vis_fpsubs32s (v1si, v1si); 15721 15722long __builtin_vis_fucmple8 (v8qi, v8qi); 15723long __builtin_vis_fucmpne8 (v8qi, v8qi); 15724long __builtin_vis_fucmpgt8 (v8qi, v8qi); 15725long __builtin_vis_fucmpeq8 (v8qi, v8qi); 15726 15727float __builtin_vis_fhadds (float, float); 15728double __builtin_vis_fhaddd (double, double); 15729float __builtin_vis_fhsubs (float, float); 15730double __builtin_vis_fhsubd (double, double); 15731float __builtin_vis_fnhadds (float, float); 15732double __builtin_vis_fnhaddd (double, double); 15733 15734int64_t __builtin_vis_umulxhi (int64_t, int64_t); 15735int64_t __builtin_vis_xmulx (int64_t, int64_t); 15736int64_t __builtin_vis_xmulxhi (int64_t, int64_t); 15737@end smallexample 15738 15739@node SPU Built-in Functions 15740@subsection SPU Built-in Functions 15741 15742GCC provides extensions for the SPU processor as described in the 15743Sony/Toshiba/IBM SPU Language Extensions Specification, which can be 15744found at @uref{http://cell.scei.co.jp/} or 15745@uref{http://www.ibm.com/developerworks/power/cell/}. GCC's 15746implementation differs in several ways. 15747 15748@itemize @bullet 15749 15750@item 15751The optional extension of specifying vector constants in parentheses is 15752not supported. 15753 15754@item 15755A vector initializer requires no cast if the vector constant is of the 15756same type as the variable it is initializing. 15757 15758@item 15759If @code{signed} or @code{unsigned} is omitted, the signedness of the 15760vector type is the default signedness of the base type. The default 15761varies depending on the operating system, so a portable program should 15762always specify the signedness. 15763 15764@item 15765By default, the keyword @code{__vector} is added. The macro 15766@code{vector} is defined in @code{<spu_intrinsics.h>} and can be 15767undefined. 15768 15769@item 15770GCC allows using a @code{typedef} name as the type specifier for a 15771vector type. 15772 15773@item 15774For C, overloaded functions are implemented with macros so the following 15775does not work: 15776 15777@smallexample 15778 spu_add ((vector signed int)@{1, 2, 3, 4@}, foo); 15779@end smallexample 15780 15781@noindent 15782Since @code{spu_add} is a macro, the vector constant in the example 15783is treated as four separate arguments. Wrap the entire argument in 15784parentheses for this to work. 15785 15786@item 15787The extended version of @code{__builtin_expect} is not supported. 15788 15789@end itemize 15790 15791@emph{Note:} Only the interface described in the aforementioned 15792specification is supported. Internally, GCC uses built-in functions to 15793implement the required functionality, but these are not supported and 15794are subject to change without notice. 15795 15796@node TI C6X Built-in Functions 15797@subsection TI C6X Built-in Functions 15798 15799GCC provides intrinsics to access certain instructions of the TI C6X 15800processors. These intrinsics, listed below, are available after 15801inclusion of the @code{c6x_intrinsics.h} header file. They map directly 15802to C6X instructions. 15803 15804@smallexample 15805 15806int _sadd (int, int) 15807int _ssub (int, int) 15808int _sadd2 (int, int) 15809int _ssub2 (int, int) 15810long long _mpy2 (int, int) 15811long long _smpy2 (int, int) 15812int _add4 (int, int) 15813int _sub4 (int, int) 15814int _saddu4 (int, int) 15815 15816int _smpy (int, int) 15817int _smpyh (int, int) 15818int _smpyhl (int, int) 15819int _smpylh (int, int) 15820 15821int _sshl (int, int) 15822int _subc (int, int) 15823 15824int _avg2 (int, int) 15825int _avgu4 (int, int) 15826 15827int _clrr (int, int) 15828int _extr (int, int) 15829int _extru (int, int) 15830int _abs (int) 15831int _abs2 (int) 15832 15833@end smallexample 15834 15835@node TILE-Gx Built-in Functions 15836@subsection TILE-Gx Built-in Functions 15837 15838GCC provides intrinsics to access every instruction of the TILE-Gx 15839processor. The intrinsics are of the form: 15840 15841@smallexample 15842 15843unsigned long long __insn_@var{op} (...) 15844 15845@end smallexample 15846 15847Where @var{op} is the name of the instruction. Refer to the ISA manual 15848for the complete list of instructions. 15849 15850GCC also provides intrinsics to directly access the network registers. 15851The intrinsics are: 15852 15853@smallexample 15854 15855unsigned long long __tile_idn0_receive (void) 15856unsigned long long __tile_idn1_receive (void) 15857unsigned long long __tile_udn0_receive (void) 15858unsigned long long __tile_udn1_receive (void) 15859unsigned long long __tile_udn2_receive (void) 15860unsigned long long __tile_udn3_receive (void) 15861void __tile_idn_send (unsigned long long) 15862void __tile_udn_send (unsigned long long) 15863 15864@end smallexample 15865 15866The intrinsic @code{void __tile_network_barrier (void)} is used to 15867guarantee that no network operations before it are reordered with 15868those after it. 15869 15870@node TILEPro Built-in Functions 15871@subsection TILEPro Built-in Functions 15872 15873GCC provides intrinsics to access every instruction of the TILEPro 15874processor. The intrinsics are of the form: 15875 15876@smallexample 15877 15878unsigned __insn_@var{op} (...) 15879 15880@end smallexample 15881 15882@noindent 15883where @var{op} is the name of the instruction. Refer to the ISA manual 15884for the complete list of instructions. 15885 15886GCC also provides intrinsics to directly access the network registers. 15887The intrinsics are: 15888 15889@smallexample 15890 15891unsigned __tile_idn0_receive (void) 15892unsigned __tile_idn1_receive (void) 15893unsigned __tile_sn_receive (void) 15894unsigned __tile_udn0_receive (void) 15895unsigned __tile_udn1_receive (void) 15896unsigned __tile_udn2_receive (void) 15897unsigned __tile_udn3_receive (void) 15898void __tile_idn_send (unsigned) 15899void __tile_sn_send (unsigned) 15900void __tile_udn_send (unsigned) 15901 15902@end smallexample 15903 15904The intrinsic @code{void __tile_network_barrier (void)} is used to 15905guarantee that no network operations before it are reordered with 15906those after it. 15907 15908@node x86 Built-in Functions 15909@subsection x86 Built-in Functions 15910 15911These built-in functions are available for the x86-32 and x86-64 family 15912of computers, depending on the command-line switches used. 15913 15914If you specify command-line switches such as @option{-msse}, 15915the compiler could use the extended instruction sets even if the built-ins 15916are not used explicitly in the program. For this reason, applications 15917that perform run-time CPU detection must compile separate files for each 15918supported architecture, using the appropriate flags. In particular, 15919the file containing the CPU detection code should be compiled without 15920these options. 15921 15922The following machine modes are available for use with MMX built-in functions 15923(@pxref{Vector Extensions}): @code{V2SI} for a vector of two 32-bit integers, 15924@code{V4HI} for a vector of four 16-bit integers, and @code{V8QI} for a 15925vector of eight 8-bit integers. Some of the built-in functions operate on 15926MMX registers as a whole 64-bit entity, these use @code{V1DI} as their mode. 15927 15928If 3DNow!@: extensions are enabled, @code{V2SF} is used as a mode for a vector 15929of two 32-bit floating-point values. 15930 15931If SSE extensions are enabled, @code{V4SF} is used for a vector of four 32-bit 15932floating-point values. Some instructions use a vector of four 32-bit 15933integers, these use @code{V4SI}. Finally, some instructions operate on an 15934entire vector register, interpreting it as a 128-bit integer, these use mode 15935@code{TI}. 15936 15937In 64-bit mode, the x86-64 family of processors uses additional built-in 15938functions for efficient use of @code{TF} (@code{__float128}) 128-bit 15939floating point and @code{TC} 128-bit complex floating-point values. 15940 15941The following floating-point built-in functions are available in 64-bit 15942mode. All of them implement the function that is part of the name. 15943 15944@smallexample 15945__float128 __builtin_fabsq (__float128) 15946__float128 __builtin_copysignq (__float128, __float128) 15947@end smallexample 15948 15949The following built-in function is always available. 15950 15951@table @code 15952@item void __builtin_ia32_pause (void) 15953Generates the @code{pause} machine instruction with a compiler memory 15954barrier. 15955@end table 15956 15957The following floating-point built-in functions are made available in the 1595864-bit mode. 15959 15960@table @code 15961@item __float128 __builtin_infq (void) 15962Similar to @code{__builtin_inf}, except the return type is @code{__float128}. 15963@findex __builtin_infq 15964 15965@item __float128 __builtin_huge_valq (void) 15966Similar to @code{__builtin_huge_val}, except the return type is @code{__float128}. 15967@findex __builtin_huge_valq 15968@end table 15969 15970The following built-in functions are always available and can be used to 15971check the target platform type. 15972 15973@deftypefn {Built-in Function} void __builtin_cpu_init (void) 15974This function runs the CPU detection code to check the type of CPU and the 15975features supported. This built-in function needs to be invoked along with the built-in functions 15976to check CPU type and features, @code{__builtin_cpu_is} and 15977@code{__builtin_cpu_supports}, only when used in a function that is 15978executed before any constructors are called. The CPU detection code is 15979automatically executed in a very high priority constructor. 15980 15981For example, this function has to be used in @code{ifunc} resolvers that 15982check for CPU type using the built-in functions @code{__builtin_cpu_is} 15983and @code{__builtin_cpu_supports}, or in constructors on targets that 15984don't support constructor priority. 15985@smallexample 15986 15987static void (*resolve_memcpy (void)) (void) 15988@{ 15989 // ifunc resolvers fire before constructors, explicitly call the init 15990 // function. 15991 __builtin_cpu_init (); 15992 if (__builtin_cpu_supports ("ssse3")) 15993 return ssse3_memcpy; // super fast memcpy with ssse3 instructions. 15994 else 15995 return default_memcpy; 15996@} 15997 15998void *memcpy (void *, const void *, size_t) 15999 __attribute__ ((ifunc ("resolve_memcpy"))); 16000@end smallexample 16001 16002@end deftypefn 16003 16004@deftypefn {Built-in Function} int __builtin_cpu_is (const char *@var{cpuname}) 16005This function returns a positive integer if the run-time CPU 16006is of type @var{cpuname} 16007and returns @code{0} otherwise. The following CPU names can be detected: 16008 16009@table @samp 16010@item intel 16011Intel CPU. 16012 16013@item atom 16014Intel Atom CPU. 16015 16016@item core2 16017Intel Core 2 CPU. 16018 16019@item corei7 16020Intel Core i7 CPU. 16021 16022@item nehalem 16023Intel Core i7 Nehalem CPU. 16024 16025@item westmere 16026Intel Core i7 Westmere CPU. 16027 16028@item sandybridge 16029Intel Core i7 Sandy Bridge CPU. 16030 16031@item amd 16032AMD CPU. 16033 16034@item amdfam10h 16035AMD Family 10h CPU. 16036 16037@item barcelona 16038AMD Family 10h Barcelona CPU. 16039 16040@item shanghai 16041AMD Family 10h Shanghai CPU. 16042 16043@item istanbul 16044AMD Family 10h Istanbul CPU. 16045 16046@item btver1 16047AMD Family 14h CPU. 16048 16049@item amdfam15h 16050AMD Family 15h CPU. 16051 16052@item bdver1 16053AMD Family 15h Bulldozer version 1. 16054 16055@item bdver2 16056AMD Family 15h Bulldozer version 2. 16057 16058@item bdver3 16059AMD Family 15h Bulldozer version 3. 16060 16061@item bdver4 16062AMD Family 15h Bulldozer version 4. 16063 16064@item btver2 16065AMD Family 16h CPU. 16066@end table 16067 16068Here is an example: 16069@smallexample 16070if (__builtin_cpu_is ("corei7")) 16071 @{ 16072 do_corei7 (); // Core i7 specific implementation. 16073 @} 16074else 16075 @{ 16076 do_generic (); // Generic implementation. 16077 @} 16078@end smallexample 16079@end deftypefn 16080 16081@deftypefn {Built-in Function} int __builtin_cpu_supports (const char *@var{feature}) 16082This function returns a positive integer if the run-time CPU 16083supports @var{feature} 16084and returns @code{0} otherwise. The following features can be detected: 16085 16086@table @samp 16087@item cmov 16088CMOV instruction. 16089@item mmx 16090MMX instructions. 16091@item popcnt 16092POPCNT instruction. 16093@item sse 16094SSE instructions. 16095@item sse2 16096SSE2 instructions. 16097@item sse3 16098SSE3 instructions. 16099@item ssse3 16100SSSE3 instructions. 16101@item sse4.1 16102SSE4.1 instructions. 16103@item sse4.2 16104SSE4.2 instructions. 16105@item avx 16106AVX instructions. 16107@item avx2 16108AVX2 instructions. 16109@item avx512f 16110AVX512F instructions. 16111@end table 16112 16113Here is an example: 16114@smallexample 16115if (__builtin_cpu_supports ("popcnt")) 16116 @{ 16117 asm("popcnt %1,%0" : "=r"(count) : "rm"(n) : "cc"); 16118 @} 16119else 16120 @{ 16121 count = generic_countbits (n); //generic implementation. 16122 @} 16123@end smallexample 16124@end deftypefn 16125 16126 16127The following built-in functions are made available by @option{-mmmx}. 16128All of them generate the machine instruction that is part of the name. 16129 16130@smallexample 16131v8qi __builtin_ia32_paddb (v8qi, v8qi) 16132v4hi __builtin_ia32_paddw (v4hi, v4hi) 16133v2si __builtin_ia32_paddd (v2si, v2si) 16134v8qi __builtin_ia32_psubb (v8qi, v8qi) 16135v4hi __builtin_ia32_psubw (v4hi, v4hi) 16136v2si __builtin_ia32_psubd (v2si, v2si) 16137v8qi __builtin_ia32_paddsb (v8qi, v8qi) 16138v4hi __builtin_ia32_paddsw (v4hi, v4hi) 16139v8qi __builtin_ia32_psubsb (v8qi, v8qi) 16140v4hi __builtin_ia32_psubsw (v4hi, v4hi) 16141v8qi __builtin_ia32_paddusb (v8qi, v8qi) 16142v4hi __builtin_ia32_paddusw (v4hi, v4hi) 16143v8qi __builtin_ia32_psubusb (v8qi, v8qi) 16144v4hi __builtin_ia32_psubusw (v4hi, v4hi) 16145v4hi __builtin_ia32_pmullw (v4hi, v4hi) 16146v4hi __builtin_ia32_pmulhw (v4hi, v4hi) 16147di __builtin_ia32_pand (di, di) 16148di __builtin_ia32_pandn (di,di) 16149di __builtin_ia32_por (di, di) 16150di __builtin_ia32_pxor (di, di) 16151v8qi __builtin_ia32_pcmpeqb (v8qi, v8qi) 16152v4hi __builtin_ia32_pcmpeqw (v4hi, v4hi) 16153v2si __builtin_ia32_pcmpeqd (v2si, v2si) 16154v8qi __builtin_ia32_pcmpgtb (v8qi, v8qi) 16155v4hi __builtin_ia32_pcmpgtw (v4hi, v4hi) 16156v2si __builtin_ia32_pcmpgtd (v2si, v2si) 16157v8qi __builtin_ia32_punpckhbw (v8qi, v8qi) 16158v4hi __builtin_ia32_punpckhwd (v4hi, v4hi) 16159v2si __builtin_ia32_punpckhdq (v2si, v2si) 16160v8qi __builtin_ia32_punpcklbw (v8qi, v8qi) 16161v4hi __builtin_ia32_punpcklwd (v4hi, v4hi) 16162v2si __builtin_ia32_punpckldq (v2si, v2si) 16163v8qi __builtin_ia32_packsswb (v4hi, v4hi) 16164v4hi __builtin_ia32_packssdw (v2si, v2si) 16165v8qi __builtin_ia32_packuswb (v4hi, v4hi) 16166 16167v4hi __builtin_ia32_psllw (v4hi, v4hi) 16168v2si __builtin_ia32_pslld (v2si, v2si) 16169v1di __builtin_ia32_psllq (v1di, v1di) 16170v4hi __builtin_ia32_psrlw (v4hi, v4hi) 16171v2si __builtin_ia32_psrld (v2si, v2si) 16172v1di __builtin_ia32_psrlq (v1di, v1di) 16173v4hi __builtin_ia32_psraw (v4hi, v4hi) 16174v2si __builtin_ia32_psrad (v2si, v2si) 16175v4hi __builtin_ia32_psllwi (v4hi, int) 16176v2si __builtin_ia32_pslldi (v2si, int) 16177v1di __builtin_ia32_psllqi (v1di, int) 16178v4hi __builtin_ia32_psrlwi (v4hi, int) 16179v2si __builtin_ia32_psrldi (v2si, int) 16180v1di __builtin_ia32_psrlqi (v1di, int) 16181v4hi __builtin_ia32_psrawi (v4hi, int) 16182v2si __builtin_ia32_psradi (v2si, int) 16183 16184@end smallexample 16185 16186The following built-in functions are made available either with 16187@option{-msse}, or with a combination of @option{-m3dnow} and 16188@option{-march=athlon}. All of them generate the machine 16189instruction that is part of the name. 16190 16191@smallexample 16192v4hi __builtin_ia32_pmulhuw (v4hi, v4hi) 16193v8qi __builtin_ia32_pavgb (v8qi, v8qi) 16194v4hi __builtin_ia32_pavgw (v4hi, v4hi) 16195v1di __builtin_ia32_psadbw (v8qi, v8qi) 16196v8qi __builtin_ia32_pmaxub (v8qi, v8qi) 16197v4hi __builtin_ia32_pmaxsw (v4hi, v4hi) 16198v8qi __builtin_ia32_pminub (v8qi, v8qi) 16199v4hi __builtin_ia32_pminsw (v4hi, v4hi) 16200int __builtin_ia32_pmovmskb (v8qi) 16201void __builtin_ia32_maskmovq (v8qi, v8qi, char *) 16202void __builtin_ia32_movntq (di *, di) 16203void __builtin_ia32_sfence (void) 16204@end smallexample 16205 16206The following built-in functions are available when @option{-msse} is used. 16207All of them generate the machine instruction that is part of the name. 16208 16209@smallexample 16210int __builtin_ia32_comieq (v4sf, v4sf) 16211int __builtin_ia32_comineq (v4sf, v4sf) 16212int __builtin_ia32_comilt (v4sf, v4sf) 16213int __builtin_ia32_comile (v4sf, v4sf) 16214int __builtin_ia32_comigt (v4sf, v4sf) 16215int __builtin_ia32_comige (v4sf, v4sf) 16216int __builtin_ia32_ucomieq (v4sf, v4sf) 16217int __builtin_ia32_ucomineq (v4sf, v4sf) 16218int __builtin_ia32_ucomilt (v4sf, v4sf) 16219int __builtin_ia32_ucomile (v4sf, v4sf) 16220int __builtin_ia32_ucomigt (v4sf, v4sf) 16221int __builtin_ia32_ucomige (v4sf, v4sf) 16222v4sf __builtin_ia32_addps (v4sf, v4sf) 16223v4sf __builtin_ia32_subps (v4sf, v4sf) 16224v4sf __builtin_ia32_mulps (v4sf, v4sf) 16225v4sf __builtin_ia32_divps (v4sf, v4sf) 16226v4sf __builtin_ia32_addss (v4sf, v4sf) 16227v4sf __builtin_ia32_subss (v4sf, v4sf) 16228v4sf __builtin_ia32_mulss (v4sf, v4sf) 16229v4sf __builtin_ia32_divss (v4sf, v4sf) 16230v4sf __builtin_ia32_cmpeqps (v4sf, v4sf) 16231v4sf __builtin_ia32_cmpltps (v4sf, v4sf) 16232v4sf __builtin_ia32_cmpleps (v4sf, v4sf) 16233v4sf __builtin_ia32_cmpgtps (v4sf, v4sf) 16234v4sf __builtin_ia32_cmpgeps (v4sf, v4sf) 16235v4sf __builtin_ia32_cmpunordps (v4sf, v4sf) 16236v4sf __builtin_ia32_cmpneqps (v4sf, v4sf) 16237v4sf __builtin_ia32_cmpnltps (v4sf, v4sf) 16238v4sf __builtin_ia32_cmpnleps (v4sf, v4sf) 16239v4sf __builtin_ia32_cmpngtps (v4sf, v4sf) 16240v4sf __builtin_ia32_cmpngeps (v4sf, v4sf) 16241v4sf __builtin_ia32_cmpordps (v4sf, v4sf) 16242v4sf __builtin_ia32_cmpeqss (v4sf, v4sf) 16243v4sf __builtin_ia32_cmpltss (v4sf, v4sf) 16244v4sf __builtin_ia32_cmpless (v4sf, v4sf) 16245v4sf __builtin_ia32_cmpunordss (v4sf, v4sf) 16246v4sf __builtin_ia32_cmpneqss (v4sf, v4sf) 16247v4sf __builtin_ia32_cmpnltss (v4sf, v4sf) 16248v4sf __builtin_ia32_cmpnless (v4sf, v4sf) 16249v4sf __builtin_ia32_cmpordss (v4sf, v4sf) 16250v4sf __builtin_ia32_maxps (v4sf, v4sf) 16251v4sf __builtin_ia32_maxss (v4sf, v4sf) 16252v4sf __builtin_ia32_minps (v4sf, v4sf) 16253v4sf __builtin_ia32_minss (v4sf, v4sf) 16254v4sf __builtin_ia32_andps (v4sf, v4sf) 16255v4sf __builtin_ia32_andnps (v4sf, v4sf) 16256v4sf __builtin_ia32_orps (v4sf, v4sf) 16257v4sf __builtin_ia32_xorps (v4sf, v4sf) 16258v4sf __builtin_ia32_movss (v4sf, v4sf) 16259v4sf __builtin_ia32_movhlps (v4sf, v4sf) 16260v4sf __builtin_ia32_movlhps (v4sf, v4sf) 16261v4sf __builtin_ia32_unpckhps (v4sf, v4sf) 16262v4sf __builtin_ia32_unpcklps (v4sf, v4sf) 16263v4sf __builtin_ia32_cvtpi2ps (v4sf, v2si) 16264v4sf __builtin_ia32_cvtsi2ss (v4sf, int) 16265v2si __builtin_ia32_cvtps2pi (v4sf) 16266int __builtin_ia32_cvtss2si (v4sf) 16267v2si __builtin_ia32_cvttps2pi (v4sf) 16268int __builtin_ia32_cvttss2si (v4sf) 16269v4sf __builtin_ia32_rcpps (v4sf) 16270v4sf __builtin_ia32_rsqrtps (v4sf) 16271v4sf __builtin_ia32_sqrtps (v4sf) 16272v4sf __builtin_ia32_rcpss (v4sf) 16273v4sf __builtin_ia32_rsqrtss (v4sf) 16274v4sf __builtin_ia32_sqrtss (v4sf) 16275v4sf __builtin_ia32_shufps (v4sf, v4sf, int) 16276void __builtin_ia32_movntps (float *, v4sf) 16277int __builtin_ia32_movmskps (v4sf) 16278@end smallexample 16279 16280The following built-in functions are available when @option{-msse} is used. 16281 16282@table @code 16283@item v4sf __builtin_ia32_loadups (float *) 16284Generates the @code{movups} machine instruction as a load from memory. 16285@item void __builtin_ia32_storeups (float *, v4sf) 16286Generates the @code{movups} machine instruction as a store to memory. 16287@item v4sf __builtin_ia32_loadss (float *) 16288Generates the @code{movss} machine instruction as a load from memory. 16289@item v4sf __builtin_ia32_loadhps (v4sf, const v2sf *) 16290Generates the @code{movhps} machine instruction as a load from memory. 16291@item v4sf __builtin_ia32_loadlps (v4sf, const v2sf *) 16292Generates the @code{movlps} machine instruction as a load from memory 16293@item void __builtin_ia32_storehps (v2sf *, v4sf) 16294Generates the @code{movhps} machine instruction as a store to memory. 16295@item void __builtin_ia32_storelps (v2sf *, v4sf) 16296Generates the @code{movlps} machine instruction as a store to memory. 16297@end table 16298 16299The following built-in functions are available when @option{-msse2} is used. 16300All of them generate the machine instruction that is part of the name. 16301 16302@smallexample 16303int __builtin_ia32_comisdeq (v2df, v2df) 16304int __builtin_ia32_comisdlt (v2df, v2df) 16305int __builtin_ia32_comisdle (v2df, v2df) 16306int __builtin_ia32_comisdgt (v2df, v2df) 16307int __builtin_ia32_comisdge (v2df, v2df) 16308int __builtin_ia32_comisdneq (v2df, v2df) 16309int __builtin_ia32_ucomisdeq (v2df, v2df) 16310int __builtin_ia32_ucomisdlt (v2df, v2df) 16311int __builtin_ia32_ucomisdle (v2df, v2df) 16312int __builtin_ia32_ucomisdgt (v2df, v2df) 16313int __builtin_ia32_ucomisdge (v2df, v2df) 16314int __builtin_ia32_ucomisdneq (v2df, v2df) 16315v2df __builtin_ia32_cmpeqpd (v2df, v2df) 16316v2df __builtin_ia32_cmpltpd (v2df, v2df) 16317v2df __builtin_ia32_cmplepd (v2df, v2df) 16318v2df __builtin_ia32_cmpgtpd (v2df, v2df) 16319v2df __builtin_ia32_cmpgepd (v2df, v2df) 16320v2df __builtin_ia32_cmpunordpd (v2df, v2df) 16321v2df __builtin_ia32_cmpneqpd (v2df, v2df) 16322v2df __builtin_ia32_cmpnltpd (v2df, v2df) 16323v2df __builtin_ia32_cmpnlepd (v2df, v2df) 16324v2df __builtin_ia32_cmpngtpd (v2df, v2df) 16325v2df __builtin_ia32_cmpngepd (v2df, v2df) 16326v2df __builtin_ia32_cmpordpd (v2df, v2df) 16327v2df __builtin_ia32_cmpeqsd (v2df, v2df) 16328v2df __builtin_ia32_cmpltsd (v2df, v2df) 16329v2df __builtin_ia32_cmplesd (v2df, v2df) 16330v2df __builtin_ia32_cmpunordsd (v2df, v2df) 16331v2df __builtin_ia32_cmpneqsd (v2df, v2df) 16332v2df __builtin_ia32_cmpnltsd (v2df, v2df) 16333v2df __builtin_ia32_cmpnlesd (v2df, v2df) 16334v2df __builtin_ia32_cmpordsd (v2df, v2df) 16335v2di __builtin_ia32_paddq (v2di, v2di) 16336v2di __builtin_ia32_psubq (v2di, v2di) 16337v2df __builtin_ia32_addpd (v2df, v2df) 16338v2df __builtin_ia32_subpd (v2df, v2df) 16339v2df __builtin_ia32_mulpd (v2df, v2df) 16340v2df __builtin_ia32_divpd (v2df, v2df) 16341v2df __builtin_ia32_addsd (v2df, v2df) 16342v2df __builtin_ia32_subsd (v2df, v2df) 16343v2df __builtin_ia32_mulsd (v2df, v2df) 16344v2df __builtin_ia32_divsd (v2df, v2df) 16345v2df __builtin_ia32_minpd (v2df, v2df) 16346v2df __builtin_ia32_maxpd (v2df, v2df) 16347v2df __builtin_ia32_minsd (v2df, v2df) 16348v2df __builtin_ia32_maxsd (v2df, v2df) 16349v2df __builtin_ia32_andpd (v2df, v2df) 16350v2df __builtin_ia32_andnpd (v2df, v2df) 16351v2df __builtin_ia32_orpd (v2df, v2df) 16352v2df __builtin_ia32_xorpd (v2df, v2df) 16353v2df __builtin_ia32_movsd (v2df, v2df) 16354v2df __builtin_ia32_unpckhpd (v2df, v2df) 16355v2df __builtin_ia32_unpcklpd (v2df, v2df) 16356v16qi __builtin_ia32_paddb128 (v16qi, v16qi) 16357v8hi __builtin_ia32_paddw128 (v8hi, v8hi) 16358v4si __builtin_ia32_paddd128 (v4si, v4si) 16359v2di __builtin_ia32_paddq128 (v2di, v2di) 16360v16qi __builtin_ia32_psubb128 (v16qi, v16qi) 16361v8hi __builtin_ia32_psubw128 (v8hi, v8hi) 16362v4si __builtin_ia32_psubd128 (v4si, v4si) 16363v2di __builtin_ia32_psubq128 (v2di, v2di) 16364v8hi __builtin_ia32_pmullw128 (v8hi, v8hi) 16365v8hi __builtin_ia32_pmulhw128 (v8hi, v8hi) 16366v2di __builtin_ia32_pand128 (v2di, v2di) 16367v2di __builtin_ia32_pandn128 (v2di, v2di) 16368v2di __builtin_ia32_por128 (v2di, v2di) 16369v2di __builtin_ia32_pxor128 (v2di, v2di) 16370v16qi __builtin_ia32_pavgb128 (v16qi, v16qi) 16371v8hi __builtin_ia32_pavgw128 (v8hi, v8hi) 16372v16qi __builtin_ia32_pcmpeqb128 (v16qi, v16qi) 16373v8hi __builtin_ia32_pcmpeqw128 (v8hi, v8hi) 16374v4si __builtin_ia32_pcmpeqd128 (v4si, v4si) 16375v16qi __builtin_ia32_pcmpgtb128 (v16qi, v16qi) 16376v8hi __builtin_ia32_pcmpgtw128 (v8hi, v8hi) 16377v4si __builtin_ia32_pcmpgtd128 (v4si, v4si) 16378v16qi __builtin_ia32_pmaxub128 (v16qi, v16qi) 16379v8hi __builtin_ia32_pmaxsw128 (v8hi, v8hi) 16380v16qi __builtin_ia32_pminub128 (v16qi, v16qi) 16381v8hi __builtin_ia32_pminsw128 (v8hi, v8hi) 16382v16qi __builtin_ia32_punpckhbw128 (v16qi, v16qi) 16383v8hi __builtin_ia32_punpckhwd128 (v8hi, v8hi) 16384v4si __builtin_ia32_punpckhdq128 (v4si, v4si) 16385v2di __builtin_ia32_punpckhqdq128 (v2di, v2di) 16386v16qi __builtin_ia32_punpcklbw128 (v16qi, v16qi) 16387v8hi __builtin_ia32_punpcklwd128 (v8hi, v8hi) 16388v4si __builtin_ia32_punpckldq128 (v4si, v4si) 16389v2di __builtin_ia32_punpcklqdq128 (v2di, v2di) 16390v16qi __builtin_ia32_packsswb128 (v8hi, v8hi) 16391v8hi __builtin_ia32_packssdw128 (v4si, v4si) 16392v16qi __builtin_ia32_packuswb128 (v8hi, v8hi) 16393v8hi __builtin_ia32_pmulhuw128 (v8hi, v8hi) 16394void __builtin_ia32_maskmovdqu (v16qi, v16qi) 16395v2df __builtin_ia32_loadupd (double *) 16396void __builtin_ia32_storeupd (double *, v2df) 16397v2df __builtin_ia32_loadhpd (v2df, double const *) 16398v2df __builtin_ia32_loadlpd (v2df, double const *) 16399int __builtin_ia32_movmskpd (v2df) 16400int __builtin_ia32_pmovmskb128 (v16qi) 16401void __builtin_ia32_movnti (int *, int) 16402void __builtin_ia32_movnti64 (long long int *, long long int) 16403void __builtin_ia32_movntpd (double *, v2df) 16404void __builtin_ia32_movntdq (v2df *, v2df) 16405v4si __builtin_ia32_pshufd (v4si, int) 16406v8hi __builtin_ia32_pshuflw (v8hi, int) 16407v8hi __builtin_ia32_pshufhw (v8hi, int) 16408v2di __builtin_ia32_psadbw128 (v16qi, v16qi) 16409v2df __builtin_ia32_sqrtpd (v2df) 16410v2df __builtin_ia32_sqrtsd (v2df) 16411v2df __builtin_ia32_shufpd (v2df, v2df, int) 16412v2df __builtin_ia32_cvtdq2pd (v4si) 16413v4sf __builtin_ia32_cvtdq2ps (v4si) 16414v4si __builtin_ia32_cvtpd2dq (v2df) 16415v2si __builtin_ia32_cvtpd2pi (v2df) 16416v4sf __builtin_ia32_cvtpd2ps (v2df) 16417v4si __builtin_ia32_cvttpd2dq (v2df) 16418v2si __builtin_ia32_cvttpd2pi (v2df) 16419v2df __builtin_ia32_cvtpi2pd (v2si) 16420int __builtin_ia32_cvtsd2si (v2df) 16421int __builtin_ia32_cvttsd2si (v2df) 16422long long __builtin_ia32_cvtsd2si64 (v2df) 16423long long __builtin_ia32_cvttsd2si64 (v2df) 16424v4si __builtin_ia32_cvtps2dq (v4sf) 16425v2df __builtin_ia32_cvtps2pd (v4sf) 16426v4si __builtin_ia32_cvttps2dq (v4sf) 16427v2df __builtin_ia32_cvtsi2sd (v2df, int) 16428v2df __builtin_ia32_cvtsi642sd (v2df, long long) 16429v4sf __builtin_ia32_cvtsd2ss (v4sf, v2df) 16430v2df __builtin_ia32_cvtss2sd (v2df, v4sf) 16431void __builtin_ia32_clflush (const void *) 16432void __builtin_ia32_lfence (void) 16433void __builtin_ia32_mfence (void) 16434v16qi __builtin_ia32_loaddqu (const char *) 16435void __builtin_ia32_storedqu (char *, v16qi) 16436v1di __builtin_ia32_pmuludq (v2si, v2si) 16437v2di __builtin_ia32_pmuludq128 (v4si, v4si) 16438v8hi __builtin_ia32_psllw128 (v8hi, v8hi) 16439v4si __builtin_ia32_pslld128 (v4si, v4si) 16440v2di __builtin_ia32_psllq128 (v2di, v2di) 16441v8hi __builtin_ia32_psrlw128 (v8hi, v8hi) 16442v4si __builtin_ia32_psrld128 (v4si, v4si) 16443v2di __builtin_ia32_psrlq128 (v2di, v2di) 16444v8hi __builtin_ia32_psraw128 (v8hi, v8hi) 16445v4si __builtin_ia32_psrad128 (v4si, v4si) 16446v2di __builtin_ia32_pslldqi128 (v2di, int) 16447v8hi __builtin_ia32_psllwi128 (v8hi, int) 16448v4si __builtin_ia32_pslldi128 (v4si, int) 16449v2di __builtin_ia32_psllqi128 (v2di, int) 16450v2di __builtin_ia32_psrldqi128 (v2di, int) 16451v8hi __builtin_ia32_psrlwi128 (v8hi, int) 16452v4si __builtin_ia32_psrldi128 (v4si, int) 16453v2di __builtin_ia32_psrlqi128 (v2di, int) 16454v8hi __builtin_ia32_psrawi128 (v8hi, int) 16455v4si __builtin_ia32_psradi128 (v4si, int) 16456v4si __builtin_ia32_pmaddwd128 (v8hi, v8hi) 16457v2di __builtin_ia32_movq128 (v2di) 16458@end smallexample 16459 16460The following built-in functions are available when @option{-msse3} is used. 16461All of them generate the machine instruction that is part of the name. 16462 16463@smallexample 16464v2df __builtin_ia32_addsubpd (v2df, v2df) 16465v4sf __builtin_ia32_addsubps (v4sf, v4sf) 16466v2df __builtin_ia32_haddpd (v2df, v2df) 16467v4sf __builtin_ia32_haddps (v4sf, v4sf) 16468v2df __builtin_ia32_hsubpd (v2df, v2df) 16469v4sf __builtin_ia32_hsubps (v4sf, v4sf) 16470v16qi __builtin_ia32_lddqu (char const *) 16471void __builtin_ia32_monitor (void *, unsigned int, unsigned int) 16472v4sf __builtin_ia32_movshdup (v4sf) 16473v4sf __builtin_ia32_movsldup (v4sf) 16474void __builtin_ia32_mwait (unsigned int, unsigned int) 16475@end smallexample 16476 16477The following built-in functions are available when @option{-mssse3} is used. 16478All of them generate the machine instruction that is part of the name. 16479 16480@smallexample 16481v2si __builtin_ia32_phaddd (v2si, v2si) 16482v4hi __builtin_ia32_phaddw (v4hi, v4hi) 16483v4hi __builtin_ia32_phaddsw (v4hi, v4hi) 16484v2si __builtin_ia32_phsubd (v2si, v2si) 16485v4hi __builtin_ia32_phsubw (v4hi, v4hi) 16486v4hi __builtin_ia32_phsubsw (v4hi, v4hi) 16487v4hi __builtin_ia32_pmaddubsw (v8qi, v8qi) 16488v4hi __builtin_ia32_pmulhrsw (v4hi, v4hi) 16489v8qi __builtin_ia32_pshufb (v8qi, v8qi) 16490v8qi __builtin_ia32_psignb (v8qi, v8qi) 16491v2si __builtin_ia32_psignd (v2si, v2si) 16492v4hi __builtin_ia32_psignw (v4hi, v4hi) 16493v1di __builtin_ia32_palignr (v1di, v1di, int) 16494v8qi __builtin_ia32_pabsb (v8qi) 16495v2si __builtin_ia32_pabsd (v2si) 16496v4hi __builtin_ia32_pabsw (v4hi) 16497@end smallexample 16498 16499The following built-in functions are available when @option{-mssse3} is used. 16500All of them generate the machine instruction that is part of the name. 16501 16502@smallexample 16503v4si __builtin_ia32_phaddd128 (v4si, v4si) 16504v8hi __builtin_ia32_phaddw128 (v8hi, v8hi) 16505v8hi __builtin_ia32_phaddsw128 (v8hi, v8hi) 16506v4si __builtin_ia32_phsubd128 (v4si, v4si) 16507v8hi __builtin_ia32_phsubw128 (v8hi, v8hi) 16508v8hi __builtin_ia32_phsubsw128 (v8hi, v8hi) 16509v8hi __builtin_ia32_pmaddubsw128 (v16qi, v16qi) 16510v8hi __builtin_ia32_pmulhrsw128 (v8hi, v8hi) 16511v16qi __builtin_ia32_pshufb128 (v16qi, v16qi) 16512v16qi __builtin_ia32_psignb128 (v16qi, v16qi) 16513v4si __builtin_ia32_psignd128 (v4si, v4si) 16514v8hi __builtin_ia32_psignw128 (v8hi, v8hi) 16515v2di __builtin_ia32_palignr128 (v2di, v2di, int) 16516v16qi __builtin_ia32_pabsb128 (v16qi) 16517v4si __builtin_ia32_pabsd128 (v4si) 16518v8hi __builtin_ia32_pabsw128 (v8hi) 16519@end smallexample 16520 16521The following built-in functions are available when @option{-msse4.1} is 16522used. All of them generate the machine instruction that is part of the 16523name. 16524 16525@smallexample 16526v2df __builtin_ia32_blendpd (v2df, v2df, const int) 16527v4sf __builtin_ia32_blendps (v4sf, v4sf, const int) 16528v2df __builtin_ia32_blendvpd (v2df, v2df, v2df) 16529v4sf __builtin_ia32_blendvps (v4sf, v4sf, v4sf) 16530v2df __builtin_ia32_dppd (v2df, v2df, const int) 16531v4sf __builtin_ia32_dpps (v4sf, v4sf, const int) 16532v4sf __builtin_ia32_insertps128 (v4sf, v4sf, const int) 16533v2di __builtin_ia32_movntdqa (v2di *); 16534v16qi __builtin_ia32_mpsadbw128 (v16qi, v16qi, const int) 16535v8hi __builtin_ia32_packusdw128 (v4si, v4si) 16536v16qi __builtin_ia32_pblendvb128 (v16qi, v16qi, v16qi) 16537v8hi __builtin_ia32_pblendw128 (v8hi, v8hi, const int) 16538v2di __builtin_ia32_pcmpeqq (v2di, v2di) 16539v8hi __builtin_ia32_phminposuw128 (v8hi) 16540v16qi __builtin_ia32_pmaxsb128 (v16qi, v16qi) 16541v4si __builtin_ia32_pmaxsd128 (v4si, v4si) 16542v4si __builtin_ia32_pmaxud128 (v4si, v4si) 16543v8hi __builtin_ia32_pmaxuw128 (v8hi, v8hi) 16544v16qi __builtin_ia32_pminsb128 (v16qi, v16qi) 16545v4si __builtin_ia32_pminsd128 (v4si, v4si) 16546v4si __builtin_ia32_pminud128 (v4si, v4si) 16547v8hi __builtin_ia32_pminuw128 (v8hi, v8hi) 16548v4si __builtin_ia32_pmovsxbd128 (v16qi) 16549v2di __builtin_ia32_pmovsxbq128 (v16qi) 16550v8hi __builtin_ia32_pmovsxbw128 (v16qi) 16551v2di __builtin_ia32_pmovsxdq128 (v4si) 16552v4si __builtin_ia32_pmovsxwd128 (v8hi) 16553v2di __builtin_ia32_pmovsxwq128 (v8hi) 16554v4si __builtin_ia32_pmovzxbd128 (v16qi) 16555v2di __builtin_ia32_pmovzxbq128 (v16qi) 16556v8hi __builtin_ia32_pmovzxbw128 (v16qi) 16557v2di __builtin_ia32_pmovzxdq128 (v4si) 16558v4si __builtin_ia32_pmovzxwd128 (v8hi) 16559v2di __builtin_ia32_pmovzxwq128 (v8hi) 16560v2di __builtin_ia32_pmuldq128 (v4si, v4si) 16561v4si __builtin_ia32_pmulld128 (v4si, v4si) 16562int __builtin_ia32_ptestc128 (v2di, v2di) 16563int __builtin_ia32_ptestnzc128 (v2di, v2di) 16564int __builtin_ia32_ptestz128 (v2di, v2di) 16565v2df __builtin_ia32_roundpd (v2df, const int) 16566v4sf __builtin_ia32_roundps (v4sf, const int) 16567v2df __builtin_ia32_roundsd (v2df, v2df, const int) 16568v4sf __builtin_ia32_roundss (v4sf, v4sf, const int) 16569@end smallexample 16570 16571The following built-in functions are available when @option{-msse4.1} is 16572used. 16573 16574@table @code 16575@item v4sf __builtin_ia32_vec_set_v4sf (v4sf, float, const int) 16576Generates the @code{insertps} machine instruction. 16577@item int __builtin_ia32_vec_ext_v16qi (v16qi, const int) 16578Generates the @code{pextrb} machine instruction. 16579@item v16qi __builtin_ia32_vec_set_v16qi (v16qi, int, const int) 16580Generates the @code{pinsrb} machine instruction. 16581@item v4si __builtin_ia32_vec_set_v4si (v4si, int, const int) 16582Generates the @code{pinsrd} machine instruction. 16583@item v2di __builtin_ia32_vec_set_v2di (v2di, long long, const int) 16584Generates the @code{pinsrq} machine instruction in 64bit mode. 16585@end table 16586 16587The following built-in functions are changed to generate new SSE4.1 16588instructions when @option{-msse4.1} is used. 16589 16590@table @code 16591@item float __builtin_ia32_vec_ext_v4sf (v4sf, const int) 16592Generates the @code{extractps} machine instruction. 16593@item int __builtin_ia32_vec_ext_v4si (v4si, const int) 16594Generates the @code{pextrd} machine instruction. 16595@item long long __builtin_ia32_vec_ext_v2di (v2di, const int) 16596Generates the @code{pextrq} machine instruction in 64bit mode. 16597@end table 16598 16599The following built-in functions are available when @option{-msse4.2} is 16600used. All of them generate the machine instruction that is part of the 16601name. 16602 16603@smallexample 16604v16qi __builtin_ia32_pcmpestrm128 (v16qi, int, v16qi, int, const int) 16605int __builtin_ia32_pcmpestri128 (v16qi, int, v16qi, int, const int) 16606int __builtin_ia32_pcmpestria128 (v16qi, int, v16qi, int, const int) 16607int __builtin_ia32_pcmpestric128 (v16qi, int, v16qi, int, const int) 16608int __builtin_ia32_pcmpestrio128 (v16qi, int, v16qi, int, const int) 16609int __builtin_ia32_pcmpestris128 (v16qi, int, v16qi, int, const int) 16610int __builtin_ia32_pcmpestriz128 (v16qi, int, v16qi, int, const int) 16611v16qi __builtin_ia32_pcmpistrm128 (v16qi, v16qi, const int) 16612int __builtin_ia32_pcmpistri128 (v16qi, v16qi, const int) 16613int __builtin_ia32_pcmpistria128 (v16qi, v16qi, const int) 16614int __builtin_ia32_pcmpistric128 (v16qi, v16qi, const int) 16615int __builtin_ia32_pcmpistrio128 (v16qi, v16qi, const int) 16616int __builtin_ia32_pcmpistris128 (v16qi, v16qi, const int) 16617int __builtin_ia32_pcmpistriz128 (v16qi, v16qi, const int) 16618v2di __builtin_ia32_pcmpgtq (v2di, v2di) 16619@end smallexample 16620 16621The following built-in functions are available when @option{-msse4.2} is 16622used. 16623 16624@table @code 16625@item unsigned int __builtin_ia32_crc32qi (unsigned int, unsigned char) 16626Generates the @code{crc32b} machine instruction. 16627@item unsigned int __builtin_ia32_crc32hi (unsigned int, unsigned short) 16628Generates the @code{crc32w} machine instruction. 16629@item unsigned int __builtin_ia32_crc32si (unsigned int, unsigned int) 16630Generates the @code{crc32l} machine instruction. 16631@item unsigned long long __builtin_ia32_crc32di (unsigned long long, unsigned long long) 16632Generates the @code{crc32q} machine instruction. 16633@end table 16634 16635The following built-in functions are changed to generate new SSE4.2 16636instructions when @option{-msse4.2} is used. 16637 16638@table @code 16639@item int __builtin_popcount (unsigned int) 16640Generates the @code{popcntl} machine instruction. 16641@item int __builtin_popcountl (unsigned long) 16642Generates the @code{popcntl} or @code{popcntq} machine instruction, 16643depending on the size of @code{unsigned long}. 16644@item int __builtin_popcountll (unsigned long long) 16645Generates the @code{popcntq} machine instruction. 16646@end table 16647 16648The following built-in functions are available when @option{-mavx} is 16649used. All of them generate the machine instruction that is part of the 16650name. 16651 16652@smallexample 16653v4df __builtin_ia32_addpd256 (v4df,v4df) 16654v8sf __builtin_ia32_addps256 (v8sf,v8sf) 16655v4df __builtin_ia32_addsubpd256 (v4df,v4df) 16656v8sf __builtin_ia32_addsubps256 (v8sf,v8sf) 16657v4df __builtin_ia32_andnpd256 (v4df,v4df) 16658v8sf __builtin_ia32_andnps256 (v8sf,v8sf) 16659v4df __builtin_ia32_andpd256 (v4df,v4df) 16660v8sf __builtin_ia32_andps256 (v8sf,v8sf) 16661v4df __builtin_ia32_blendpd256 (v4df,v4df,int) 16662v8sf __builtin_ia32_blendps256 (v8sf,v8sf,int) 16663v4df __builtin_ia32_blendvpd256 (v4df,v4df,v4df) 16664v8sf __builtin_ia32_blendvps256 (v8sf,v8sf,v8sf) 16665v2df __builtin_ia32_cmppd (v2df,v2df,int) 16666v4df __builtin_ia32_cmppd256 (v4df,v4df,int) 16667v4sf __builtin_ia32_cmpps (v4sf,v4sf,int) 16668v8sf __builtin_ia32_cmpps256 (v8sf,v8sf,int) 16669v2df __builtin_ia32_cmpsd (v2df,v2df,int) 16670v4sf __builtin_ia32_cmpss (v4sf,v4sf,int) 16671v4df __builtin_ia32_cvtdq2pd256 (v4si) 16672v8sf __builtin_ia32_cvtdq2ps256 (v8si) 16673v4si __builtin_ia32_cvtpd2dq256 (v4df) 16674v4sf __builtin_ia32_cvtpd2ps256 (v4df) 16675v8si __builtin_ia32_cvtps2dq256 (v8sf) 16676v4df __builtin_ia32_cvtps2pd256 (v4sf) 16677v4si __builtin_ia32_cvttpd2dq256 (v4df) 16678v8si __builtin_ia32_cvttps2dq256 (v8sf) 16679v4df __builtin_ia32_divpd256 (v4df,v4df) 16680v8sf __builtin_ia32_divps256 (v8sf,v8sf) 16681v8sf __builtin_ia32_dpps256 (v8sf,v8sf,int) 16682v4df __builtin_ia32_haddpd256 (v4df,v4df) 16683v8sf __builtin_ia32_haddps256 (v8sf,v8sf) 16684v4df __builtin_ia32_hsubpd256 (v4df,v4df) 16685v8sf __builtin_ia32_hsubps256 (v8sf,v8sf) 16686v32qi __builtin_ia32_lddqu256 (pcchar) 16687v32qi __builtin_ia32_loaddqu256 (pcchar) 16688v4df __builtin_ia32_loadupd256 (pcdouble) 16689v8sf __builtin_ia32_loadups256 (pcfloat) 16690v2df __builtin_ia32_maskloadpd (pcv2df,v2df) 16691v4df __builtin_ia32_maskloadpd256 (pcv4df,v4df) 16692v4sf __builtin_ia32_maskloadps (pcv4sf,v4sf) 16693v8sf __builtin_ia32_maskloadps256 (pcv8sf,v8sf) 16694void __builtin_ia32_maskstorepd (pv2df,v2df,v2df) 16695void __builtin_ia32_maskstorepd256 (pv4df,v4df,v4df) 16696void __builtin_ia32_maskstoreps (pv4sf,v4sf,v4sf) 16697void __builtin_ia32_maskstoreps256 (pv8sf,v8sf,v8sf) 16698v4df __builtin_ia32_maxpd256 (v4df,v4df) 16699v8sf __builtin_ia32_maxps256 (v8sf,v8sf) 16700v4df __builtin_ia32_minpd256 (v4df,v4df) 16701v8sf __builtin_ia32_minps256 (v8sf,v8sf) 16702v4df __builtin_ia32_movddup256 (v4df) 16703int __builtin_ia32_movmskpd256 (v4df) 16704int __builtin_ia32_movmskps256 (v8sf) 16705v8sf __builtin_ia32_movshdup256 (v8sf) 16706v8sf __builtin_ia32_movsldup256 (v8sf) 16707v4df __builtin_ia32_mulpd256 (v4df,v4df) 16708v8sf __builtin_ia32_mulps256 (v8sf,v8sf) 16709v4df __builtin_ia32_orpd256 (v4df,v4df) 16710v8sf __builtin_ia32_orps256 (v8sf,v8sf) 16711v2df __builtin_ia32_pd_pd256 (v4df) 16712v4df __builtin_ia32_pd256_pd (v2df) 16713v4sf __builtin_ia32_ps_ps256 (v8sf) 16714v8sf __builtin_ia32_ps256_ps (v4sf) 16715int __builtin_ia32_ptestc256 (v4di,v4di,ptest) 16716int __builtin_ia32_ptestnzc256 (v4di,v4di,ptest) 16717int __builtin_ia32_ptestz256 (v4di,v4di,ptest) 16718v8sf __builtin_ia32_rcpps256 (v8sf) 16719v4df __builtin_ia32_roundpd256 (v4df,int) 16720v8sf __builtin_ia32_roundps256 (v8sf,int) 16721v8sf __builtin_ia32_rsqrtps_nr256 (v8sf) 16722v8sf __builtin_ia32_rsqrtps256 (v8sf) 16723v4df __builtin_ia32_shufpd256 (v4df,v4df,int) 16724v8sf __builtin_ia32_shufps256 (v8sf,v8sf,int) 16725v4si __builtin_ia32_si_si256 (v8si) 16726v8si __builtin_ia32_si256_si (v4si) 16727v4df __builtin_ia32_sqrtpd256 (v4df) 16728v8sf __builtin_ia32_sqrtps_nr256 (v8sf) 16729v8sf __builtin_ia32_sqrtps256 (v8sf) 16730void __builtin_ia32_storedqu256 (pchar,v32qi) 16731void __builtin_ia32_storeupd256 (pdouble,v4df) 16732void __builtin_ia32_storeups256 (pfloat,v8sf) 16733v4df __builtin_ia32_subpd256 (v4df,v4df) 16734v8sf __builtin_ia32_subps256 (v8sf,v8sf) 16735v4df __builtin_ia32_unpckhpd256 (v4df,v4df) 16736v8sf __builtin_ia32_unpckhps256 (v8sf,v8sf) 16737v4df __builtin_ia32_unpcklpd256 (v4df,v4df) 16738v8sf __builtin_ia32_unpcklps256 (v8sf,v8sf) 16739v4df __builtin_ia32_vbroadcastf128_pd256 (pcv2df) 16740v8sf __builtin_ia32_vbroadcastf128_ps256 (pcv4sf) 16741v4df __builtin_ia32_vbroadcastsd256 (pcdouble) 16742v4sf __builtin_ia32_vbroadcastss (pcfloat) 16743v8sf __builtin_ia32_vbroadcastss256 (pcfloat) 16744v2df __builtin_ia32_vextractf128_pd256 (v4df,int) 16745v4sf __builtin_ia32_vextractf128_ps256 (v8sf,int) 16746v4si __builtin_ia32_vextractf128_si256 (v8si,int) 16747v4df __builtin_ia32_vinsertf128_pd256 (v4df,v2df,int) 16748v8sf __builtin_ia32_vinsertf128_ps256 (v8sf,v4sf,int) 16749v8si __builtin_ia32_vinsertf128_si256 (v8si,v4si,int) 16750v4df __builtin_ia32_vperm2f128_pd256 (v4df,v4df,int) 16751v8sf __builtin_ia32_vperm2f128_ps256 (v8sf,v8sf,int) 16752v8si __builtin_ia32_vperm2f128_si256 (v8si,v8si,int) 16753v2df __builtin_ia32_vpermil2pd (v2df,v2df,v2di,int) 16754v4df __builtin_ia32_vpermil2pd256 (v4df,v4df,v4di,int) 16755v4sf __builtin_ia32_vpermil2ps (v4sf,v4sf,v4si,int) 16756v8sf __builtin_ia32_vpermil2ps256 (v8sf,v8sf,v8si,int) 16757v2df __builtin_ia32_vpermilpd (v2df,int) 16758v4df __builtin_ia32_vpermilpd256 (v4df,int) 16759v4sf __builtin_ia32_vpermilps (v4sf,int) 16760v8sf __builtin_ia32_vpermilps256 (v8sf,int) 16761v2df __builtin_ia32_vpermilvarpd (v2df,v2di) 16762v4df __builtin_ia32_vpermilvarpd256 (v4df,v4di) 16763v4sf __builtin_ia32_vpermilvarps (v4sf,v4si) 16764v8sf __builtin_ia32_vpermilvarps256 (v8sf,v8si) 16765int __builtin_ia32_vtestcpd (v2df,v2df,ptest) 16766int __builtin_ia32_vtestcpd256 (v4df,v4df,ptest) 16767int __builtin_ia32_vtestcps (v4sf,v4sf,ptest) 16768int __builtin_ia32_vtestcps256 (v8sf,v8sf,ptest) 16769int __builtin_ia32_vtestnzcpd (v2df,v2df,ptest) 16770int __builtin_ia32_vtestnzcpd256 (v4df,v4df,ptest) 16771int __builtin_ia32_vtestnzcps (v4sf,v4sf,ptest) 16772int __builtin_ia32_vtestnzcps256 (v8sf,v8sf,ptest) 16773int __builtin_ia32_vtestzpd (v2df,v2df,ptest) 16774int __builtin_ia32_vtestzpd256 (v4df,v4df,ptest) 16775int __builtin_ia32_vtestzps (v4sf,v4sf,ptest) 16776int __builtin_ia32_vtestzps256 (v8sf,v8sf,ptest) 16777void __builtin_ia32_vzeroall (void) 16778void __builtin_ia32_vzeroupper (void) 16779v4df __builtin_ia32_xorpd256 (v4df,v4df) 16780v8sf __builtin_ia32_xorps256 (v8sf,v8sf) 16781@end smallexample 16782 16783The following built-in functions are available when @option{-mavx2} is 16784used. All of them generate the machine instruction that is part of the 16785name. 16786 16787@smallexample 16788v32qi __builtin_ia32_mpsadbw256 (v32qi,v32qi,int) 16789v32qi __builtin_ia32_pabsb256 (v32qi) 16790v16hi __builtin_ia32_pabsw256 (v16hi) 16791v8si __builtin_ia32_pabsd256 (v8si) 16792v16hi __builtin_ia32_packssdw256 (v8si,v8si) 16793v32qi __builtin_ia32_packsswb256 (v16hi,v16hi) 16794v16hi __builtin_ia32_packusdw256 (v8si,v8si) 16795v32qi __builtin_ia32_packuswb256 (v16hi,v16hi) 16796v32qi __builtin_ia32_paddb256 (v32qi,v32qi) 16797v16hi __builtin_ia32_paddw256 (v16hi,v16hi) 16798v8si __builtin_ia32_paddd256 (v8si,v8si) 16799v4di __builtin_ia32_paddq256 (v4di,v4di) 16800v32qi __builtin_ia32_paddsb256 (v32qi,v32qi) 16801v16hi __builtin_ia32_paddsw256 (v16hi,v16hi) 16802v32qi __builtin_ia32_paddusb256 (v32qi,v32qi) 16803v16hi __builtin_ia32_paddusw256 (v16hi,v16hi) 16804v4di __builtin_ia32_palignr256 (v4di,v4di,int) 16805v4di __builtin_ia32_andsi256 (v4di,v4di) 16806v4di __builtin_ia32_andnotsi256 (v4di,v4di) 16807v32qi __builtin_ia32_pavgb256 (v32qi,v32qi) 16808v16hi __builtin_ia32_pavgw256 (v16hi,v16hi) 16809v32qi __builtin_ia32_pblendvb256 (v32qi,v32qi,v32qi) 16810v16hi __builtin_ia32_pblendw256 (v16hi,v16hi,int) 16811v32qi __builtin_ia32_pcmpeqb256 (v32qi,v32qi) 16812v16hi __builtin_ia32_pcmpeqw256 (v16hi,v16hi) 16813v8si __builtin_ia32_pcmpeqd256 (c8si,v8si) 16814v4di __builtin_ia32_pcmpeqq256 (v4di,v4di) 16815v32qi __builtin_ia32_pcmpgtb256 (v32qi,v32qi) 16816v16hi __builtin_ia32_pcmpgtw256 (16hi,v16hi) 16817v8si __builtin_ia32_pcmpgtd256 (v8si,v8si) 16818v4di __builtin_ia32_pcmpgtq256 (v4di,v4di) 16819v16hi __builtin_ia32_phaddw256 (v16hi,v16hi) 16820v8si __builtin_ia32_phaddd256 (v8si,v8si) 16821v16hi __builtin_ia32_phaddsw256 (v16hi,v16hi) 16822v16hi __builtin_ia32_phsubw256 (v16hi,v16hi) 16823v8si __builtin_ia32_phsubd256 (v8si,v8si) 16824v16hi __builtin_ia32_phsubsw256 (v16hi,v16hi) 16825v32qi __builtin_ia32_pmaddubsw256 (v32qi,v32qi) 16826v16hi __builtin_ia32_pmaddwd256 (v16hi,v16hi) 16827v32qi __builtin_ia32_pmaxsb256 (v32qi,v32qi) 16828v16hi __builtin_ia32_pmaxsw256 (v16hi,v16hi) 16829v8si __builtin_ia32_pmaxsd256 (v8si,v8si) 16830v32qi __builtin_ia32_pmaxub256 (v32qi,v32qi) 16831v16hi __builtin_ia32_pmaxuw256 (v16hi,v16hi) 16832v8si __builtin_ia32_pmaxud256 (v8si,v8si) 16833v32qi __builtin_ia32_pminsb256 (v32qi,v32qi) 16834v16hi __builtin_ia32_pminsw256 (v16hi,v16hi) 16835v8si __builtin_ia32_pminsd256 (v8si,v8si) 16836v32qi __builtin_ia32_pminub256 (v32qi,v32qi) 16837v16hi __builtin_ia32_pminuw256 (v16hi,v16hi) 16838v8si __builtin_ia32_pminud256 (v8si,v8si) 16839int __builtin_ia32_pmovmskb256 (v32qi) 16840v16hi __builtin_ia32_pmovsxbw256 (v16qi) 16841v8si __builtin_ia32_pmovsxbd256 (v16qi) 16842v4di __builtin_ia32_pmovsxbq256 (v16qi) 16843v8si __builtin_ia32_pmovsxwd256 (v8hi) 16844v4di __builtin_ia32_pmovsxwq256 (v8hi) 16845v4di __builtin_ia32_pmovsxdq256 (v4si) 16846v16hi __builtin_ia32_pmovzxbw256 (v16qi) 16847v8si __builtin_ia32_pmovzxbd256 (v16qi) 16848v4di __builtin_ia32_pmovzxbq256 (v16qi) 16849v8si __builtin_ia32_pmovzxwd256 (v8hi) 16850v4di __builtin_ia32_pmovzxwq256 (v8hi) 16851v4di __builtin_ia32_pmovzxdq256 (v4si) 16852v4di __builtin_ia32_pmuldq256 (v8si,v8si) 16853v16hi __builtin_ia32_pmulhrsw256 (v16hi, v16hi) 16854v16hi __builtin_ia32_pmulhuw256 (v16hi,v16hi) 16855v16hi __builtin_ia32_pmulhw256 (v16hi,v16hi) 16856v16hi __builtin_ia32_pmullw256 (v16hi,v16hi) 16857v8si __builtin_ia32_pmulld256 (v8si,v8si) 16858v4di __builtin_ia32_pmuludq256 (v8si,v8si) 16859v4di __builtin_ia32_por256 (v4di,v4di) 16860v16hi __builtin_ia32_psadbw256 (v32qi,v32qi) 16861v32qi __builtin_ia32_pshufb256 (v32qi,v32qi) 16862v8si __builtin_ia32_pshufd256 (v8si,int) 16863v16hi __builtin_ia32_pshufhw256 (v16hi,int) 16864v16hi __builtin_ia32_pshuflw256 (v16hi,int) 16865v32qi __builtin_ia32_psignb256 (v32qi,v32qi) 16866v16hi __builtin_ia32_psignw256 (v16hi,v16hi) 16867v8si __builtin_ia32_psignd256 (v8si,v8si) 16868v4di __builtin_ia32_pslldqi256 (v4di,int) 16869v16hi __builtin_ia32_psllwi256 (16hi,int) 16870v16hi __builtin_ia32_psllw256(v16hi,v8hi) 16871v8si __builtin_ia32_pslldi256 (v8si,int) 16872v8si __builtin_ia32_pslld256(v8si,v4si) 16873v4di __builtin_ia32_psllqi256 (v4di,int) 16874v4di __builtin_ia32_psllq256(v4di,v2di) 16875v16hi __builtin_ia32_psrawi256 (v16hi,int) 16876v16hi __builtin_ia32_psraw256 (v16hi,v8hi) 16877v8si __builtin_ia32_psradi256 (v8si,int) 16878v8si __builtin_ia32_psrad256 (v8si,v4si) 16879v4di __builtin_ia32_psrldqi256 (v4di, int) 16880v16hi __builtin_ia32_psrlwi256 (v16hi,int) 16881v16hi __builtin_ia32_psrlw256 (v16hi,v8hi) 16882v8si __builtin_ia32_psrldi256 (v8si,int) 16883v8si __builtin_ia32_psrld256 (v8si,v4si) 16884v4di __builtin_ia32_psrlqi256 (v4di,int) 16885v4di __builtin_ia32_psrlq256(v4di,v2di) 16886v32qi __builtin_ia32_psubb256 (v32qi,v32qi) 16887v32hi __builtin_ia32_psubw256 (v16hi,v16hi) 16888v8si __builtin_ia32_psubd256 (v8si,v8si) 16889v4di __builtin_ia32_psubq256 (v4di,v4di) 16890v32qi __builtin_ia32_psubsb256 (v32qi,v32qi) 16891v16hi __builtin_ia32_psubsw256 (v16hi,v16hi) 16892v32qi __builtin_ia32_psubusb256 (v32qi,v32qi) 16893v16hi __builtin_ia32_psubusw256 (v16hi,v16hi) 16894v32qi __builtin_ia32_punpckhbw256 (v32qi,v32qi) 16895v16hi __builtin_ia32_punpckhwd256 (v16hi,v16hi) 16896v8si __builtin_ia32_punpckhdq256 (v8si,v8si) 16897v4di __builtin_ia32_punpckhqdq256 (v4di,v4di) 16898v32qi __builtin_ia32_punpcklbw256 (v32qi,v32qi) 16899v16hi __builtin_ia32_punpcklwd256 (v16hi,v16hi) 16900v8si __builtin_ia32_punpckldq256 (v8si,v8si) 16901v4di __builtin_ia32_punpcklqdq256 (v4di,v4di) 16902v4di __builtin_ia32_pxor256 (v4di,v4di) 16903v4di __builtin_ia32_movntdqa256 (pv4di) 16904v4sf __builtin_ia32_vbroadcastss_ps (v4sf) 16905v8sf __builtin_ia32_vbroadcastss_ps256 (v4sf) 16906v4df __builtin_ia32_vbroadcastsd_pd256 (v2df) 16907v4di __builtin_ia32_vbroadcastsi256 (v2di) 16908v4si __builtin_ia32_pblendd128 (v4si,v4si) 16909v8si __builtin_ia32_pblendd256 (v8si,v8si) 16910v32qi __builtin_ia32_pbroadcastb256 (v16qi) 16911v16hi __builtin_ia32_pbroadcastw256 (v8hi) 16912v8si __builtin_ia32_pbroadcastd256 (v4si) 16913v4di __builtin_ia32_pbroadcastq256 (v2di) 16914v16qi __builtin_ia32_pbroadcastb128 (v16qi) 16915v8hi __builtin_ia32_pbroadcastw128 (v8hi) 16916v4si __builtin_ia32_pbroadcastd128 (v4si) 16917v2di __builtin_ia32_pbroadcastq128 (v2di) 16918v8si __builtin_ia32_permvarsi256 (v8si,v8si) 16919v4df __builtin_ia32_permdf256 (v4df,int) 16920v8sf __builtin_ia32_permvarsf256 (v8sf,v8sf) 16921v4di __builtin_ia32_permdi256 (v4di,int) 16922v4di __builtin_ia32_permti256 (v4di,v4di,int) 16923v4di __builtin_ia32_extract128i256 (v4di,int) 16924v4di __builtin_ia32_insert128i256 (v4di,v2di,int) 16925v8si __builtin_ia32_maskloadd256 (pcv8si,v8si) 16926v4di __builtin_ia32_maskloadq256 (pcv4di,v4di) 16927v4si __builtin_ia32_maskloadd (pcv4si,v4si) 16928v2di __builtin_ia32_maskloadq (pcv2di,v2di) 16929void __builtin_ia32_maskstored256 (pv8si,v8si,v8si) 16930void __builtin_ia32_maskstoreq256 (pv4di,v4di,v4di) 16931void __builtin_ia32_maskstored (pv4si,v4si,v4si) 16932void __builtin_ia32_maskstoreq (pv2di,v2di,v2di) 16933v8si __builtin_ia32_psllv8si (v8si,v8si) 16934v4si __builtin_ia32_psllv4si (v4si,v4si) 16935v4di __builtin_ia32_psllv4di (v4di,v4di) 16936v2di __builtin_ia32_psllv2di (v2di,v2di) 16937v8si __builtin_ia32_psrav8si (v8si,v8si) 16938v4si __builtin_ia32_psrav4si (v4si,v4si) 16939v8si __builtin_ia32_psrlv8si (v8si,v8si) 16940v4si __builtin_ia32_psrlv4si (v4si,v4si) 16941v4di __builtin_ia32_psrlv4di (v4di,v4di) 16942v2di __builtin_ia32_psrlv2di (v2di,v2di) 16943v2df __builtin_ia32_gathersiv2df (v2df, pcdouble,v4si,v2df,int) 16944v4df __builtin_ia32_gathersiv4df (v4df, pcdouble,v4si,v4df,int) 16945v2df __builtin_ia32_gatherdiv2df (v2df, pcdouble,v2di,v2df,int) 16946v4df __builtin_ia32_gatherdiv4df (v4df, pcdouble,v4di,v4df,int) 16947v4sf __builtin_ia32_gathersiv4sf (v4sf, pcfloat,v4si,v4sf,int) 16948v8sf __builtin_ia32_gathersiv8sf (v8sf, pcfloat,v8si,v8sf,int) 16949v4sf __builtin_ia32_gatherdiv4sf (v4sf, pcfloat,v2di,v4sf,int) 16950v4sf __builtin_ia32_gatherdiv4sf256 (v4sf, pcfloat,v4di,v4sf,int) 16951v2di __builtin_ia32_gathersiv2di (v2di, pcint64,v4si,v2di,int) 16952v4di __builtin_ia32_gathersiv4di (v4di, pcint64,v4si,v4di,int) 16953v2di __builtin_ia32_gatherdiv2di (v2di, pcint64,v2di,v2di,int) 16954v4di __builtin_ia32_gatherdiv4di (v4di, pcint64,v4di,v4di,int) 16955v4si __builtin_ia32_gathersiv4si (v4si, pcint,v4si,v4si,int) 16956v8si __builtin_ia32_gathersiv8si (v8si, pcint,v8si,v8si,int) 16957v4si __builtin_ia32_gatherdiv4si (v4si, pcint,v2di,v4si,int) 16958v4si __builtin_ia32_gatherdiv4si256 (v4si, pcint,v4di,v4si,int) 16959@end smallexample 16960 16961The following built-in functions are available when @option{-maes} is 16962used. All of them generate the machine instruction that is part of the 16963name. 16964 16965@smallexample 16966v2di __builtin_ia32_aesenc128 (v2di, v2di) 16967v2di __builtin_ia32_aesenclast128 (v2di, v2di) 16968v2di __builtin_ia32_aesdec128 (v2di, v2di) 16969v2di __builtin_ia32_aesdeclast128 (v2di, v2di) 16970v2di __builtin_ia32_aeskeygenassist128 (v2di, const int) 16971v2di __builtin_ia32_aesimc128 (v2di) 16972@end smallexample 16973 16974The following built-in function is available when @option{-mpclmul} is 16975used. 16976 16977@table @code 16978@item v2di __builtin_ia32_pclmulqdq128 (v2di, v2di, const int) 16979Generates the @code{pclmulqdq} machine instruction. 16980@end table 16981 16982The following built-in function is available when @option{-mfsgsbase} is 16983used. All of them generate the machine instruction that is part of the 16984name. 16985 16986@smallexample 16987unsigned int __builtin_ia32_rdfsbase32 (void) 16988unsigned long long __builtin_ia32_rdfsbase64 (void) 16989unsigned int __builtin_ia32_rdgsbase32 (void) 16990unsigned long long __builtin_ia32_rdgsbase64 (void) 16991void _writefsbase_u32 (unsigned int) 16992void _writefsbase_u64 (unsigned long long) 16993void _writegsbase_u32 (unsigned int) 16994void _writegsbase_u64 (unsigned long long) 16995@end smallexample 16996 16997The following built-in function is available when @option{-mrdrnd} is 16998used. All of them generate the machine instruction that is part of the 16999name. 17000 17001@smallexample 17002unsigned int __builtin_ia32_rdrand16_step (unsigned short *) 17003unsigned int __builtin_ia32_rdrand32_step (unsigned int *) 17004unsigned int __builtin_ia32_rdrand64_step (unsigned long long *) 17005@end smallexample 17006 17007The following built-in functions are available when @option{-msse4a} is used. 17008All of them generate the machine instruction that is part of the name. 17009 17010@smallexample 17011void __builtin_ia32_movntsd (double *, v2df) 17012void __builtin_ia32_movntss (float *, v4sf) 17013v2di __builtin_ia32_extrq (v2di, v16qi) 17014v2di __builtin_ia32_extrqi (v2di, const unsigned int, const unsigned int) 17015v2di __builtin_ia32_insertq (v2di, v2di) 17016v2di __builtin_ia32_insertqi (v2di, v2di, const unsigned int, const unsigned int) 17017@end smallexample 17018 17019The following built-in functions are available when @option{-mxop} is used. 17020@smallexample 17021v2df __builtin_ia32_vfrczpd (v2df) 17022v4sf __builtin_ia32_vfrczps (v4sf) 17023v2df __builtin_ia32_vfrczsd (v2df) 17024v4sf __builtin_ia32_vfrczss (v4sf) 17025v4df __builtin_ia32_vfrczpd256 (v4df) 17026v8sf __builtin_ia32_vfrczps256 (v8sf) 17027v2di __builtin_ia32_vpcmov (v2di, v2di, v2di) 17028v2di __builtin_ia32_vpcmov_v2di (v2di, v2di, v2di) 17029v4si __builtin_ia32_vpcmov_v4si (v4si, v4si, v4si) 17030v8hi __builtin_ia32_vpcmov_v8hi (v8hi, v8hi, v8hi) 17031v16qi __builtin_ia32_vpcmov_v16qi (v16qi, v16qi, v16qi) 17032v2df __builtin_ia32_vpcmov_v2df (v2df, v2df, v2df) 17033v4sf __builtin_ia32_vpcmov_v4sf (v4sf, v4sf, v4sf) 17034v4di __builtin_ia32_vpcmov_v4di256 (v4di, v4di, v4di) 17035v8si __builtin_ia32_vpcmov_v8si256 (v8si, v8si, v8si) 17036v16hi __builtin_ia32_vpcmov_v16hi256 (v16hi, v16hi, v16hi) 17037v32qi __builtin_ia32_vpcmov_v32qi256 (v32qi, v32qi, v32qi) 17038v4df __builtin_ia32_vpcmov_v4df256 (v4df, v4df, v4df) 17039v8sf __builtin_ia32_vpcmov_v8sf256 (v8sf, v8sf, v8sf) 17040v16qi __builtin_ia32_vpcomeqb (v16qi, v16qi) 17041v8hi __builtin_ia32_vpcomeqw (v8hi, v8hi) 17042v4si __builtin_ia32_vpcomeqd (v4si, v4si) 17043v2di __builtin_ia32_vpcomeqq (v2di, v2di) 17044v16qi __builtin_ia32_vpcomequb (v16qi, v16qi) 17045v4si __builtin_ia32_vpcomequd (v4si, v4si) 17046v2di __builtin_ia32_vpcomequq (v2di, v2di) 17047v8hi __builtin_ia32_vpcomequw (v8hi, v8hi) 17048v8hi __builtin_ia32_vpcomeqw (v8hi, v8hi) 17049v16qi __builtin_ia32_vpcomfalseb (v16qi, v16qi) 17050v4si __builtin_ia32_vpcomfalsed (v4si, v4si) 17051v2di __builtin_ia32_vpcomfalseq (v2di, v2di) 17052v16qi __builtin_ia32_vpcomfalseub (v16qi, v16qi) 17053v4si __builtin_ia32_vpcomfalseud (v4si, v4si) 17054v2di __builtin_ia32_vpcomfalseuq (v2di, v2di) 17055v8hi __builtin_ia32_vpcomfalseuw (v8hi, v8hi) 17056v8hi __builtin_ia32_vpcomfalsew (v8hi, v8hi) 17057v16qi __builtin_ia32_vpcomgeb (v16qi, v16qi) 17058v4si __builtin_ia32_vpcomged (v4si, v4si) 17059v2di __builtin_ia32_vpcomgeq (v2di, v2di) 17060v16qi __builtin_ia32_vpcomgeub (v16qi, v16qi) 17061v4si __builtin_ia32_vpcomgeud (v4si, v4si) 17062v2di __builtin_ia32_vpcomgeuq (v2di, v2di) 17063v8hi __builtin_ia32_vpcomgeuw (v8hi, v8hi) 17064v8hi __builtin_ia32_vpcomgew (v8hi, v8hi) 17065v16qi __builtin_ia32_vpcomgtb (v16qi, v16qi) 17066v4si __builtin_ia32_vpcomgtd (v4si, v4si) 17067v2di __builtin_ia32_vpcomgtq (v2di, v2di) 17068v16qi __builtin_ia32_vpcomgtub (v16qi, v16qi) 17069v4si __builtin_ia32_vpcomgtud (v4si, v4si) 17070v2di __builtin_ia32_vpcomgtuq (v2di, v2di) 17071v8hi __builtin_ia32_vpcomgtuw (v8hi, v8hi) 17072v8hi __builtin_ia32_vpcomgtw (v8hi, v8hi) 17073v16qi __builtin_ia32_vpcomleb (v16qi, v16qi) 17074v4si __builtin_ia32_vpcomled (v4si, v4si) 17075v2di __builtin_ia32_vpcomleq (v2di, v2di) 17076v16qi __builtin_ia32_vpcomleub (v16qi, v16qi) 17077v4si __builtin_ia32_vpcomleud (v4si, v4si) 17078v2di __builtin_ia32_vpcomleuq (v2di, v2di) 17079v8hi __builtin_ia32_vpcomleuw (v8hi, v8hi) 17080v8hi __builtin_ia32_vpcomlew (v8hi, v8hi) 17081v16qi __builtin_ia32_vpcomltb (v16qi, v16qi) 17082v4si __builtin_ia32_vpcomltd (v4si, v4si) 17083v2di __builtin_ia32_vpcomltq (v2di, v2di) 17084v16qi __builtin_ia32_vpcomltub (v16qi, v16qi) 17085v4si __builtin_ia32_vpcomltud (v4si, v4si) 17086v2di __builtin_ia32_vpcomltuq (v2di, v2di) 17087v8hi __builtin_ia32_vpcomltuw (v8hi, v8hi) 17088v8hi __builtin_ia32_vpcomltw (v8hi, v8hi) 17089v16qi __builtin_ia32_vpcomneb (v16qi, v16qi) 17090v4si __builtin_ia32_vpcomned (v4si, v4si) 17091v2di __builtin_ia32_vpcomneq (v2di, v2di) 17092v16qi __builtin_ia32_vpcomneub (v16qi, v16qi) 17093v4si __builtin_ia32_vpcomneud (v4si, v4si) 17094v2di __builtin_ia32_vpcomneuq (v2di, v2di) 17095v8hi __builtin_ia32_vpcomneuw (v8hi, v8hi) 17096v8hi __builtin_ia32_vpcomnew (v8hi, v8hi) 17097v16qi __builtin_ia32_vpcomtrueb (v16qi, v16qi) 17098v4si __builtin_ia32_vpcomtrued (v4si, v4si) 17099v2di __builtin_ia32_vpcomtrueq (v2di, v2di) 17100v16qi __builtin_ia32_vpcomtrueub (v16qi, v16qi) 17101v4si __builtin_ia32_vpcomtrueud (v4si, v4si) 17102v2di __builtin_ia32_vpcomtrueuq (v2di, v2di) 17103v8hi __builtin_ia32_vpcomtrueuw (v8hi, v8hi) 17104v8hi __builtin_ia32_vpcomtruew (v8hi, v8hi) 17105v4si __builtin_ia32_vphaddbd (v16qi) 17106v2di __builtin_ia32_vphaddbq (v16qi) 17107v8hi __builtin_ia32_vphaddbw (v16qi) 17108v2di __builtin_ia32_vphadddq (v4si) 17109v4si __builtin_ia32_vphaddubd (v16qi) 17110v2di __builtin_ia32_vphaddubq (v16qi) 17111v8hi __builtin_ia32_vphaddubw (v16qi) 17112v2di __builtin_ia32_vphaddudq (v4si) 17113v4si __builtin_ia32_vphadduwd (v8hi) 17114v2di __builtin_ia32_vphadduwq (v8hi) 17115v4si __builtin_ia32_vphaddwd (v8hi) 17116v2di __builtin_ia32_vphaddwq (v8hi) 17117v8hi __builtin_ia32_vphsubbw (v16qi) 17118v2di __builtin_ia32_vphsubdq (v4si) 17119v4si __builtin_ia32_vphsubwd (v8hi) 17120v4si __builtin_ia32_vpmacsdd (v4si, v4si, v4si) 17121v2di __builtin_ia32_vpmacsdqh (v4si, v4si, v2di) 17122v2di __builtin_ia32_vpmacsdql (v4si, v4si, v2di) 17123v4si __builtin_ia32_vpmacssdd (v4si, v4si, v4si) 17124v2di __builtin_ia32_vpmacssdqh (v4si, v4si, v2di) 17125v2di __builtin_ia32_vpmacssdql (v4si, v4si, v2di) 17126v4si __builtin_ia32_vpmacsswd (v8hi, v8hi, v4si) 17127v8hi __builtin_ia32_vpmacssww (v8hi, v8hi, v8hi) 17128v4si __builtin_ia32_vpmacswd (v8hi, v8hi, v4si) 17129v8hi __builtin_ia32_vpmacsww (v8hi, v8hi, v8hi) 17130v4si __builtin_ia32_vpmadcsswd (v8hi, v8hi, v4si) 17131v4si __builtin_ia32_vpmadcswd (v8hi, v8hi, v4si) 17132v16qi __builtin_ia32_vpperm (v16qi, v16qi, v16qi) 17133v16qi __builtin_ia32_vprotb (v16qi, v16qi) 17134v4si __builtin_ia32_vprotd (v4si, v4si) 17135v2di __builtin_ia32_vprotq (v2di, v2di) 17136v8hi __builtin_ia32_vprotw (v8hi, v8hi) 17137v16qi __builtin_ia32_vpshab (v16qi, v16qi) 17138v4si __builtin_ia32_vpshad (v4si, v4si) 17139v2di __builtin_ia32_vpshaq (v2di, v2di) 17140v8hi __builtin_ia32_vpshaw (v8hi, v8hi) 17141v16qi __builtin_ia32_vpshlb (v16qi, v16qi) 17142v4si __builtin_ia32_vpshld (v4si, v4si) 17143v2di __builtin_ia32_vpshlq (v2di, v2di) 17144v8hi __builtin_ia32_vpshlw (v8hi, v8hi) 17145@end smallexample 17146 17147The following built-in functions are available when @option{-mfma4} is used. 17148All of them generate the machine instruction that is part of the name. 17149 17150@smallexample 17151v2df __builtin_ia32_vfmaddpd (v2df, v2df, v2df) 17152v4sf __builtin_ia32_vfmaddps (v4sf, v4sf, v4sf) 17153v2df __builtin_ia32_vfmaddsd (v2df, v2df, v2df) 17154v4sf __builtin_ia32_vfmaddss (v4sf, v4sf, v4sf) 17155v2df __builtin_ia32_vfmsubpd (v2df, v2df, v2df) 17156v4sf __builtin_ia32_vfmsubps (v4sf, v4sf, v4sf) 17157v2df __builtin_ia32_vfmsubsd (v2df, v2df, v2df) 17158v4sf __builtin_ia32_vfmsubss (v4sf, v4sf, v4sf) 17159v2df __builtin_ia32_vfnmaddpd (v2df, v2df, v2df) 17160v4sf __builtin_ia32_vfnmaddps (v4sf, v4sf, v4sf) 17161v2df __builtin_ia32_vfnmaddsd (v2df, v2df, v2df) 17162v4sf __builtin_ia32_vfnmaddss (v4sf, v4sf, v4sf) 17163v2df __builtin_ia32_vfnmsubpd (v2df, v2df, v2df) 17164v4sf __builtin_ia32_vfnmsubps (v4sf, v4sf, v4sf) 17165v2df __builtin_ia32_vfnmsubsd (v2df, v2df, v2df) 17166v4sf __builtin_ia32_vfnmsubss (v4sf, v4sf, v4sf) 17167v2df __builtin_ia32_vfmaddsubpd (v2df, v2df, v2df) 17168v4sf __builtin_ia32_vfmaddsubps (v4sf, v4sf, v4sf) 17169v2df __builtin_ia32_vfmsubaddpd (v2df, v2df, v2df) 17170v4sf __builtin_ia32_vfmsubaddps (v4sf, v4sf, v4sf) 17171v4df __builtin_ia32_vfmaddpd256 (v4df, v4df, v4df) 17172v8sf __builtin_ia32_vfmaddps256 (v8sf, v8sf, v8sf) 17173v4df __builtin_ia32_vfmsubpd256 (v4df, v4df, v4df) 17174v8sf __builtin_ia32_vfmsubps256 (v8sf, v8sf, v8sf) 17175v4df __builtin_ia32_vfnmaddpd256 (v4df, v4df, v4df) 17176v8sf __builtin_ia32_vfnmaddps256 (v8sf, v8sf, v8sf) 17177v4df __builtin_ia32_vfnmsubpd256 (v4df, v4df, v4df) 17178v8sf __builtin_ia32_vfnmsubps256 (v8sf, v8sf, v8sf) 17179v4df __builtin_ia32_vfmaddsubpd256 (v4df, v4df, v4df) 17180v8sf __builtin_ia32_vfmaddsubps256 (v8sf, v8sf, v8sf) 17181v4df __builtin_ia32_vfmsubaddpd256 (v4df, v4df, v4df) 17182v8sf __builtin_ia32_vfmsubaddps256 (v8sf, v8sf, v8sf) 17183 17184@end smallexample 17185 17186The following built-in functions are available when @option{-mlwp} is used. 17187 17188@smallexample 17189void __builtin_ia32_llwpcb16 (void *); 17190void __builtin_ia32_llwpcb32 (void *); 17191void __builtin_ia32_llwpcb64 (void *); 17192void * __builtin_ia32_llwpcb16 (void); 17193void * __builtin_ia32_llwpcb32 (void); 17194void * __builtin_ia32_llwpcb64 (void); 17195void __builtin_ia32_lwpval16 (unsigned short, unsigned int, unsigned short) 17196void __builtin_ia32_lwpval32 (unsigned int, unsigned int, unsigned int) 17197void __builtin_ia32_lwpval64 (unsigned __int64, unsigned int, unsigned int) 17198unsigned char __builtin_ia32_lwpins16 (unsigned short, unsigned int, unsigned short) 17199unsigned char __builtin_ia32_lwpins32 (unsigned int, unsigned int, unsigned int) 17200unsigned char __builtin_ia32_lwpins64 (unsigned __int64, unsigned int, unsigned int) 17201@end smallexample 17202 17203The following built-in functions are available when @option{-mbmi} is used. 17204All of them generate the machine instruction that is part of the name. 17205@smallexample 17206unsigned int __builtin_ia32_bextr_u32(unsigned int, unsigned int); 17207unsigned long long __builtin_ia32_bextr_u64 (unsigned long long, unsigned long long); 17208@end smallexample 17209 17210The following built-in functions are available when @option{-mbmi2} is used. 17211All of them generate the machine instruction that is part of the name. 17212@smallexample 17213unsigned int _bzhi_u32 (unsigned int, unsigned int) 17214unsigned int _pdep_u32 (unsigned int, unsigned int) 17215unsigned int _pext_u32 (unsigned int, unsigned int) 17216unsigned long long _bzhi_u64 (unsigned long long, unsigned long long) 17217unsigned long long _pdep_u64 (unsigned long long, unsigned long long) 17218unsigned long long _pext_u64 (unsigned long long, unsigned long long) 17219@end smallexample 17220 17221The following built-in functions are available when @option{-mlzcnt} is used. 17222All of them generate the machine instruction that is part of the name. 17223@smallexample 17224unsigned short __builtin_ia32_lzcnt_16(unsigned short); 17225unsigned int __builtin_ia32_lzcnt_u32(unsigned int); 17226unsigned long long __builtin_ia32_lzcnt_u64 (unsigned long long); 17227@end smallexample 17228 17229The following built-in functions are available when @option{-mfxsr} is used. 17230All of them generate the machine instruction that is part of the name. 17231@smallexample 17232void __builtin_ia32_fxsave (void *) 17233void __builtin_ia32_fxrstor (void *) 17234void __builtin_ia32_fxsave64 (void *) 17235void __builtin_ia32_fxrstor64 (void *) 17236@end smallexample 17237 17238The following built-in functions are available when @option{-mxsave} is used. 17239All of them generate the machine instruction that is part of the name. 17240@smallexample 17241void __builtin_ia32_xsave (void *, long long) 17242void __builtin_ia32_xrstor (void *, long long) 17243void __builtin_ia32_xsave64 (void *, long long) 17244void __builtin_ia32_xrstor64 (void *, long long) 17245@end smallexample 17246 17247The following built-in functions are available when @option{-mxsaveopt} is used. 17248All of them generate the machine instruction that is part of the name. 17249@smallexample 17250void __builtin_ia32_xsaveopt (void *, long long) 17251void __builtin_ia32_xsaveopt64 (void *, long long) 17252@end smallexample 17253 17254The following built-in functions are available when @option{-mtbm} is used. 17255Both of them generate the immediate form of the bextr machine instruction. 17256@smallexample 17257unsigned int __builtin_ia32_bextri_u32 (unsigned int, const unsigned int); 17258unsigned long long __builtin_ia32_bextri_u64 (unsigned long long, const unsigned long long); 17259@end smallexample 17260 17261 17262The following built-in functions are available when @option{-m3dnow} is used. 17263All of them generate the machine instruction that is part of the name. 17264 17265@smallexample 17266void __builtin_ia32_femms (void) 17267v8qi __builtin_ia32_pavgusb (v8qi, v8qi) 17268v2si __builtin_ia32_pf2id (v2sf) 17269v2sf __builtin_ia32_pfacc (v2sf, v2sf) 17270v2sf __builtin_ia32_pfadd (v2sf, v2sf) 17271v2si __builtin_ia32_pfcmpeq (v2sf, v2sf) 17272v2si __builtin_ia32_pfcmpge (v2sf, v2sf) 17273v2si __builtin_ia32_pfcmpgt (v2sf, v2sf) 17274v2sf __builtin_ia32_pfmax (v2sf, v2sf) 17275v2sf __builtin_ia32_pfmin (v2sf, v2sf) 17276v2sf __builtin_ia32_pfmul (v2sf, v2sf) 17277v2sf __builtin_ia32_pfrcp (v2sf) 17278v2sf __builtin_ia32_pfrcpit1 (v2sf, v2sf) 17279v2sf __builtin_ia32_pfrcpit2 (v2sf, v2sf) 17280v2sf __builtin_ia32_pfrsqrt (v2sf) 17281v2sf __builtin_ia32_pfsub (v2sf, v2sf) 17282v2sf __builtin_ia32_pfsubr (v2sf, v2sf) 17283v2sf __builtin_ia32_pi2fd (v2si) 17284v4hi __builtin_ia32_pmulhrw (v4hi, v4hi) 17285@end smallexample 17286 17287The following built-in functions are available when both @option{-m3dnow} 17288and @option{-march=athlon} are used. All of them generate the machine 17289instruction that is part of the name. 17290 17291@smallexample 17292v2si __builtin_ia32_pf2iw (v2sf) 17293v2sf __builtin_ia32_pfnacc (v2sf, v2sf) 17294v2sf __builtin_ia32_pfpnacc (v2sf, v2sf) 17295v2sf __builtin_ia32_pi2fw (v2si) 17296v2sf __builtin_ia32_pswapdsf (v2sf) 17297v2si __builtin_ia32_pswapdsi (v2si) 17298@end smallexample 17299 17300The following built-in functions are available when @option{-mrtm} is used 17301They are used for restricted transactional memory. These are the internal 17302low level functions. Normally the functions in 17303@ref{x86 transactional memory intrinsics} should be used instead. 17304 17305@smallexample 17306int __builtin_ia32_xbegin () 17307void __builtin_ia32_xend () 17308void __builtin_ia32_xabort (status) 17309int __builtin_ia32_xtest () 17310@end smallexample 17311 17312The following built-in functions are available when @option{-mmwaitx} is used. 17313All of them generate the machine instruction that is part of the name. 17314@smallexample 17315void __builtin_ia32_monitorx (void *, unsigned int, unsigned int) 17316void __builtin_ia32_mwaitx (unsigned int, unsigned int, unsigned int) 17317@end smallexample 17318 17319@node x86 transactional memory intrinsics 17320@subsection x86 Transactional Memory Intrinsics 17321 17322These hardware transactional memory intrinsics for x86 allow you to use 17323memory transactions with RTM (Restricted Transactional Memory). 17324This support is enabled with the @option{-mrtm} option. 17325For using HLE (Hardware Lock Elision) see 17326@ref{x86 specific memory model extensions for transactional memory} instead. 17327 17328A memory transaction commits all changes to memory in an atomic way, 17329as visible to other threads. If the transaction fails it is rolled back 17330and all side effects discarded. 17331 17332Generally there is no guarantee that a memory transaction ever succeeds 17333and suitable fallback code always needs to be supplied. 17334 17335@deftypefn {RTM Function} {unsigned} _xbegin () 17336Start a RTM (Restricted Transactional Memory) transaction. 17337Returns @code{_XBEGIN_STARTED} when the transaction 17338started successfully (note this is not 0, so the constant has to be 17339explicitly tested). 17340 17341If the transaction aborts, all side-effects 17342are undone and an abort code encoded as a bit mask is returned. 17343The following macros are defined: 17344 17345@table @code 17346@item _XABORT_EXPLICIT 17347Transaction was explicitly aborted with @code{_xabort}. The parameter passed 17348to @code{_xabort} is available with @code{_XABORT_CODE(status)}. 17349@item _XABORT_RETRY 17350Transaction retry is possible. 17351@item _XABORT_CONFLICT 17352Transaction abort due to a memory conflict with another thread. 17353@item _XABORT_CAPACITY 17354Transaction abort due to the transaction using too much memory. 17355@item _XABORT_DEBUG 17356Transaction abort due to a debug trap. 17357@item _XABORT_NESTED 17358Transaction abort in an inner nested transaction. 17359@end table 17360 17361There is no guarantee 17362any transaction ever succeeds, so there always needs to be a valid 17363fallback path. 17364@end deftypefn 17365 17366@deftypefn {RTM Function} {void} _xend () 17367Commit the current transaction. When no transaction is active this faults. 17368All memory side-effects of the transaction become visible 17369to other threads in an atomic manner. 17370@end deftypefn 17371 17372@deftypefn {RTM Function} {int} _xtest () 17373Return a nonzero value if a transaction is currently active, otherwise 0. 17374@end deftypefn 17375 17376@deftypefn {RTM Function} {void} _xabort (status) 17377Abort the current transaction. When no transaction is active this is a no-op. 17378The @var{status} is an 8-bit constant; its value is encoded in the return 17379value from @code{_xbegin}. 17380@end deftypefn 17381 17382Here is an example showing handling for @code{_XABORT_RETRY} 17383and a fallback path for other failures: 17384 17385@smallexample 17386#include <immintrin.h> 17387 17388int n_tries, max_tries; 17389unsigned status = _XABORT_EXPLICIT; 17390... 17391 17392for (n_tries = 0; n_tries < max_tries; n_tries++) 17393 @{ 17394 status = _xbegin (); 17395 if (status == _XBEGIN_STARTED || !(status & _XABORT_RETRY)) 17396 break; 17397 @} 17398if (status == _XBEGIN_STARTED) 17399 @{ 17400 ... transaction code... 17401 _xend (); 17402 @} 17403else 17404 @{ 17405 ... non-transactional fallback path... 17406 @} 17407@end smallexample 17408 17409@noindent 17410Note that, in most cases, the transactional and non-transactional code 17411must synchronize together to ensure consistency. 17412 17413@node Target Format Checks 17414@section Format Checks Specific to Particular Target Machines 17415 17416For some target machines, GCC supports additional options to the 17417format attribute 17418(@pxref{Function Attributes,,Declaring Attributes of Functions}). 17419 17420@menu 17421* Solaris Format Checks:: 17422* Darwin Format Checks:: 17423@end menu 17424 17425@node Solaris Format Checks 17426@subsection Solaris Format Checks 17427 17428Solaris targets support the @code{cmn_err} (or @code{__cmn_err__}) format 17429check. @code{cmn_err} accepts a subset of the standard @code{printf} 17430conversions, and the two-argument @code{%b} conversion for displaying 17431bit-fields. See the Solaris man page for @code{cmn_err} for more information. 17432 17433@node Darwin Format Checks 17434@subsection Darwin Format Checks 17435 17436Darwin targets support the @code{CFString} (or @code{__CFString__}) in the format 17437attribute context. Declarations made with such attribution are parsed for correct syntax 17438and format argument types. However, parsing of the format string itself is currently undefined 17439and is not carried out by this version of the compiler. 17440 17441Additionally, @code{CFStringRefs} (defined by the @code{CoreFoundation} headers) may 17442also be used as format arguments. Note that the relevant headers are only likely to be 17443available on Darwin (OSX) installations. On such installations, the XCode and system 17444documentation provide descriptions of @code{CFString}, @code{CFStringRefs} and 17445associated functions. 17446 17447@node Pragmas 17448@section Pragmas Accepted by GCC 17449@cindex pragmas 17450@cindex @code{#pragma} 17451 17452GCC supports several types of pragmas, primarily in order to compile 17453code originally written for other compilers. Note that in general 17454we do not recommend the use of pragmas; @xref{Function Attributes}, 17455for further explanation. 17456 17457@menu 17458* ARM Pragmas:: 17459* M32C Pragmas:: 17460* MeP Pragmas:: 17461* RS/6000 and PowerPC Pragmas:: 17462* Darwin Pragmas:: 17463* Solaris Pragmas:: 17464* Symbol-Renaming Pragmas:: 17465* Structure-Packing Pragmas:: 17466* Weak Pragmas:: 17467* Diagnostic Pragmas:: 17468* Visibility Pragmas:: 17469* Push/Pop Macro Pragmas:: 17470* Function Specific Option Pragmas:: 17471* Loop-Specific Pragmas:: 17472@end menu 17473 17474@node ARM Pragmas 17475@subsection ARM Pragmas 17476 17477The ARM target defines pragmas for controlling the default addition of 17478@code{long_call} and @code{short_call} attributes to functions. 17479@xref{Function Attributes}, for information about the effects of these 17480attributes. 17481 17482@table @code 17483@item long_calls 17484@cindex pragma, long_calls 17485Set all subsequent functions to have the @code{long_call} attribute. 17486 17487@item no_long_calls 17488@cindex pragma, no_long_calls 17489Set all subsequent functions to have the @code{short_call} attribute. 17490 17491@item long_calls_off 17492@cindex pragma, long_calls_off 17493Do not affect the @code{long_call} or @code{short_call} attributes of 17494subsequent functions. 17495@end table 17496 17497@node M32C Pragmas 17498@subsection M32C Pragmas 17499 17500@table @code 17501@item GCC memregs @var{number} 17502@cindex pragma, memregs 17503Overrides the command-line option @code{-memregs=} for the current 17504file. Use with care! This pragma must be before any function in the 17505file, and mixing different memregs values in different objects may 17506make them incompatible. This pragma is useful when a 17507performance-critical function uses a memreg for temporary values, 17508as it may allow you to reduce the number of memregs used. 17509 17510@item ADDRESS @var{name} @var{address} 17511@cindex pragma, address 17512For any declared symbols matching @var{name}, this does three things 17513to that symbol: it forces the symbol to be located at the given 17514address (a number), it forces the symbol to be volatile, and it 17515changes the symbol's scope to be static. This pragma exists for 17516compatibility with other compilers, but note that the common 17517@code{1234H} numeric syntax is not supported (use @code{0x1234} 17518instead). Example: 17519 17520@smallexample 17521#pragma ADDRESS port3 0x103 17522char port3; 17523@end smallexample 17524 17525@end table 17526 17527@node MeP Pragmas 17528@subsection MeP Pragmas 17529 17530@table @code 17531 17532@item custom io_volatile (on|off) 17533@cindex pragma, custom io_volatile 17534Overrides the command-line option @code{-mio-volatile} for the current 17535file. Note that for compatibility with future GCC releases, this 17536option should only be used once before any @code{io} variables in each 17537file. 17538 17539@item GCC coprocessor available @var{registers} 17540@cindex pragma, coprocessor available 17541Specifies which coprocessor registers are available to the register 17542allocator. @var{registers} may be a single register, register range 17543separated by ellipses, or comma-separated list of those. Example: 17544 17545@smallexample 17546#pragma GCC coprocessor available $c0...$c10, $c28 17547@end smallexample 17548 17549@item GCC coprocessor call_saved @var{registers} 17550@cindex pragma, coprocessor call_saved 17551Specifies which coprocessor registers are to be saved and restored by 17552any function using them. @var{registers} may be a single register, 17553register range separated by ellipses, or comma-separated list of 17554those. Example: 17555 17556@smallexample 17557#pragma GCC coprocessor call_saved $c4...$c6, $c31 17558@end smallexample 17559 17560@item GCC coprocessor subclass '(A|B|C|D)' = @var{registers} 17561@cindex pragma, coprocessor subclass 17562Creates and defines a register class. These register classes can be 17563used by inline @code{asm} constructs. @var{registers} may be a single 17564register, register range separated by ellipses, or comma-separated 17565list of those. Example: 17566 17567@smallexample 17568#pragma GCC coprocessor subclass 'B' = $c2, $c4, $c6 17569 17570asm ("cpfoo %0" : "=B" (x)); 17571@end smallexample 17572 17573@item GCC disinterrupt @var{name} , @var{name} @dots{} 17574@cindex pragma, disinterrupt 17575For the named functions, the compiler adds code to disable interrupts 17576for the duration of those functions. If any functions so named 17577are not encountered in the source, a warning is emitted that the pragma is 17578not used. Examples: 17579 17580@smallexample 17581#pragma disinterrupt foo 17582#pragma disinterrupt bar, grill 17583int foo () @{ @dots{} @} 17584@end smallexample 17585 17586@item GCC call @var{name} , @var{name} @dots{} 17587@cindex pragma, call 17588For the named functions, the compiler always uses a register-indirect 17589call model when calling the named functions. Examples: 17590 17591@smallexample 17592extern int foo (); 17593#pragma call foo 17594@end smallexample 17595 17596@end table 17597 17598@node RS/6000 and PowerPC Pragmas 17599@subsection RS/6000 and PowerPC Pragmas 17600 17601The RS/6000 and PowerPC targets define one pragma for controlling 17602whether or not the @code{longcall} attribute is added to function 17603declarations by default. This pragma overrides the @option{-mlongcall} 17604option, but not the @code{longcall} and @code{shortcall} attributes. 17605@xref{RS/6000 and PowerPC Options}, for more information about when long 17606calls are and are not necessary. 17607 17608@table @code 17609@item longcall (1) 17610@cindex pragma, longcall 17611Apply the @code{longcall} attribute to all subsequent function 17612declarations. 17613 17614@item longcall (0) 17615Do not apply the @code{longcall} attribute to subsequent function 17616declarations. 17617@end table 17618 17619@c Describe h8300 pragmas here. 17620@c Describe sh pragmas here. 17621@c Describe v850 pragmas here. 17622 17623@node Darwin Pragmas 17624@subsection Darwin Pragmas 17625 17626The following pragmas are available for all architectures running the 17627Darwin operating system. These are useful for compatibility with other 17628Mac OS compilers. 17629 17630@table @code 17631@item mark @var{tokens}@dots{} 17632@cindex pragma, mark 17633This pragma is accepted, but has no effect. 17634 17635@item options align=@var{alignment} 17636@cindex pragma, options align 17637This pragma sets the alignment of fields in structures. The values of 17638@var{alignment} may be @code{mac68k}, to emulate m68k alignment, or 17639@code{power}, to emulate PowerPC alignment. Uses of this pragma nest 17640properly; to restore the previous setting, use @code{reset} for the 17641@var{alignment}. 17642 17643@item segment @var{tokens}@dots{} 17644@cindex pragma, segment 17645This pragma is accepted, but has no effect. 17646 17647@item unused (@var{var} [, @var{var}]@dots{}) 17648@cindex pragma, unused 17649This pragma declares variables to be possibly unused. GCC does not 17650produce warnings for the listed variables. The effect is similar to 17651that of the @code{unused} attribute, except that this pragma may appear 17652anywhere within the variables' scopes. 17653@end table 17654 17655@node Solaris Pragmas 17656@subsection Solaris Pragmas 17657 17658The Solaris target supports @code{#pragma redefine_extname} 17659(@pxref{Symbol-Renaming Pragmas}). It also supports additional 17660@code{#pragma} directives for compatibility with the system compiler. 17661 17662@table @code 17663@item align @var{alignment} (@var{variable} [, @var{variable}]...) 17664@cindex pragma, align 17665 17666Increase the minimum alignment of each @var{variable} to @var{alignment}. 17667This is the same as GCC's @code{aligned} attribute @pxref{Variable 17668Attributes}). Macro expansion occurs on the arguments to this pragma 17669when compiling C and Objective-C@. It does not currently occur when 17670compiling C++, but this is a bug which may be fixed in a future 17671release. 17672 17673@item fini (@var{function} [, @var{function}]...) 17674@cindex pragma, fini 17675 17676This pragma causes each listed @var{function} to be called after 17677main, or during shared module unloading, by adding a call to the 17678@code{.fini} section. 17679 17680@item init (@var{function} [, @var{function}]...) 17681@cindex pragma, init 17682 17683This pragma causes each listed @var{function} to be called during 17684initialization (before @code{main}) or during shared module loading, by 17685adding a call to the @code{.init} section. 17686 17687@end table 17688 17689@node Symbol-Renaming Pragmas 17690@subsection Symbol-Renaming Pragmas 17691 17692GCC supports a @code{#pragma} directive that changes the name used in 17693assembly for a given declaration. While this pragma is supported on all 17694platforms, it is intended primarily to provide compatibility with the 17695Solaris system headers. This effect can also be achieved using the asm 17696labels extension (@pxref{Asm Labels}). 17697 17698@table @code 17699@item redefine_extname @var{oldname} @var{newname} 17700@cindex pragma, redefine_extname 17701 17702This pragma gives the C function @var{oldname} the assembly symbol 17703@var{newname}. The preprocessor macro @code{__PRAGMA_REDEFINE_EXTNAME} 17704is defined if this pragma is available (currently on all platforms). 17705@end table 17706 17707This pragma and the asm labels extension interact in a complicated 17708manner. Here are some corner cases you may want to be aware of: 17709 17710@enumerate 17711@item This pragma silently applies only to declarations with external 17712linkage. Asm labels do not have this restriction. 17713 17714@item In C++, this pragma silently applies only to declarations with 17715``C'' linkage. Again, asm labels do not have this restriction. 17716 17717@item If either of the ways of changing the assembly name of a 17718declaration are applied to a declaration whose assembly name has 17719already been determined (either by a previous use of one of these 17720features, or because the compiler needed the assembly name in order to 17721generate code), and the new name is different, a warning issues and 17722the name does not change. 17723 17724@item The @var{oldname} used by @code{#pragma redefine_extname} is 17725always the C-language name. 17726@end enumerate 17727 17728@node Structure-Packing Pragmas 17729@subsection Structure-Packing Pragmas 17730 17731For compatibility with Microsoft Windows compilers, GCC supports a 17732set of @code{#pragma} directives that change the maximum alignment of 17733members of structures (other than zero-width bit-fields), unions, and 17734classes subsequently defined. The @var{n} value below always is required 17735to be a small power of two and specifies the new alignment in bytes. 17736 17737@enumerate 17738@item @code{#pragma pack(@var{n})} simply sets the new alignment. 17739@item @code{#pragma pack()} sets the alignment to the one that was in 17740effect when compilation started (see also command-line option 17741@option{-fpack-struct[=@var{n}]} @pxref{Code Gen Options}). 17742@item @code{#pragma pack(push[,@var{n}])} pushes the current alignment 17743setting on an internal stack and then optionally sets the new alignment. 17744@item @code{#pragma pack(pop)} restores the alignment setting to the one 17745saved at the top of the internal stack (and removes that stack entry). 17746Note that @code{#pragma pack([@var{n}])} does not influence this internal 17747stack; thus it is possible to have @code{#pragma pack(push)} followed by 17748multiple @code{#pragma pack(@var{n})} instances and finalized by a single 17749@code{#pragma pack(pop)}. 17750@end enumerate 17751 17752Some targets, e.g.@: x86 and PowerPC, support the @code{ms_struct} 17753@code{#pragma} which lays out a structure as the documented 17754@code{__attribute__ ((ms_struct))}. 17755@enumerate 17756@item @code{#pragma ms_struct on} turns on the layout for structures 17757declared. 17758@item @code{#pragma ms_struct off} turns off the layout for structures 17759declared. 17760@item @code{#pragma ms_struct reset} goes back to the default layout. 17761@end enumerate 17762 17763@node Weak Pragmas 17764@subsection Weak Pragmas 17765 17766For compatibility with SVR4, GCC supports a set of @code{#pragma} 17767directives for declaring symbols to be weak, and defining weak 17768aliases. 17769 17770@table @code 17771@item #pragma weak @var{symbol} 17772@cindex pragma, weak 17773This pragma declares @var{symbol} to be weak, as if the declaration 17774had the attribute of the same name. The pragma may appear before 17775or after the declaration of @var{symbol}. It is not an error for 17776@var{symbol} to never be defined at all. 17777 17778@item #pragma weak @var{symbol1} = @var{symbol2} 17779This pragma declares @var{symbol1} to be a weak alias of @var{symbol2}. 17780It is an error if @var{symbol2} is not defined in the current 17781translation unit. 17782@end table 17783 17784@node Diagnostic Pragmas 17785@subsection Diagnostic Pragmas 17786 17787GCC allows the user to selectively enable or disable certain types of 17788diagnostics, and change the kind of the diagnostic. For example, a 17789project's policy might require that all sources compile with 17790@option{-Werror} but certain files might have exceptions allowing 17791specific types of warnings. Or, a project might selectively enable 17792diagnostics and treat them as errors depending on which preprocessor 17793macros are defined. 17794 17795@table @code 17796@item #pragma GCC diagnostic @var{kind} @var{option} 17797@cindex pragma, diagnostic 17798 17799Modifies the disposition of a diagnostic. Note that not all 17800diagnostics are modifiable; at the moment only warnings (normally 17801controlled by @samp{-W@dots{}}) can be controlled, and not all of them. 17802Use @option{-fdiagnostics-show-option} to determine which diagnostics 17803are controllable and which option controls them. 17804 17805@var{kind} is @samp{error} to treat this diagnostic as an error, 17806@samp{warning} to treat it like a warning (even if @option{-Werror} is 17807in effect), or @samp{ignored} if the diagnostic is to be ignored. 17808@var{option} is a double quoted string that matches the command-line 17809option. 17810 17811@smallexample 17812#pragma GCC diagnostic warning "-Wformat" 17813#pragma GCC diagnostic error "-Wformat" 17814#pragma GCC diagnostic ignored "-Wformat" 17815@end smallexample 17816 17817Note that these pragmas override any command-line options. GCC keeps 17818track of the location of each pragma, and issues diagnostics according 17819to the state as of that point in the source file. Thus, pragmas occurring 17820after a line do not affect diagnostics caused by that line. 17821 17822@item #pragma GCC diagnostic push 17823@itemx #pragma GCC diagnostic pop 17824 17825Causes GCC to remember the state of the diagnostics as of each 17826@code{push}, and restore to that point at each @code{pop}. If a 17827@code{pop} has no matching @code{push}, the command-line options are 17828restored. 17829 17830@smallexample 17831#pragma GCC diagnostic error "-Wuninitialized" 17832 foo(a); /* error is given for this one */ 17833#pragma GCC diagnostic push 17834#pragma GCC diagnostic ignored "-Wuninitialized" 17835 foo(b); /* no diagnostic for this one */ 17836#pragma GCC diagnostic pop 17837 foo(c); /* error is given for this one */ 17838#pragma GCC diagnostic pop 17839 foo(d); /* depends on command-line options */ 17840@end smallexample 17841 17842@end table 17843 17844GCC also offers a simple mechanism for printing messages during 17845compilation. 17846 17847@table @code 17848@item #pragma message @var{string} 17849@cindex pragma, diagnostic 17850 17851Prints @var{string} as a compiler message on compilation. The message 17852is informational only, and is neither a compilation warning nor an error. 17853 17854@smallexample 17855#pragma message "Compiling " __FILE__ "..." 17856@end smallexample 17857 17858@var{string} may be parenthesized, and is printed with location 17859information. For example, 17860 17861@smallexample 17862#define DO_PRAGMA(x) _Pragma (#x) 17863#define TODO(x) DO_PRAGMA(message ("TODO - " #x)) 17864 17865TODO(Remember to fix this) 17866@end smallexample 17867 17868@noindent 17869prints @samp{/tmp/file.c:4: note: #pragma message: 17870TODO - Remember to fix this}. 17871 17872@end table 17873 17874@node Visibility Pragmas 17875@subsection Visibility Pragmas 17876 17877@table @code 17878@item #pragma GCC visibility push(@var{visibility}) 17879@itemx #pragma GCC visibility pop 17880@cindex pragma, visibility 17881 17882This pragma allows the user to set the visibility for multiple 17883declarations without having to give each a visibility attribute 17884(@pxref{Function Attributes}). 17885 17886In C++, @samp{#pragma GCC visibility} affects only namespace-scope 17887declarations. Class members and template specializations are not 17888affected; if you want to override the visibility for a particular 17889member or instantiation, you must use an attribute. 17890 17891@end table 17892 17893 17894@node Push/Pop Macro Pragmas 17895@subsection Push/Pop Macro Pragmas 17896 17897For compatibility with Microsoft Windows compilers, GCC supports 17898@samp{#pragma push_macro(@var{"macro_name"})} 17899and @samp{#pragma pop_macro(@var{"macro_name"})}. 17900 17901@table @code 17902@item #pragma push_macro(@var{"macro_name"}) 17903@cindex pragma, push_macro 17904This pragma saves the value of the macro named as @var{macro_name} to 17905the top of the stack for this macro. 17906 17907@item #pragma pop_macro(@var{"macro_name"}) 17908@cindex pragma, pop_macro 17909This pragma sets the value of the macro named as @var{macro_name} to 17910the value on top of the stack for this macro. If the stack for 17911@var{macro_name} is empty, the value of the macro remains unchanged. 17912@end table 17913 17914For example: 17915 17916@smallexample 17917#define X 1 17918#pragma push_macro("X") 17919#undef X 17920#define X -1 17921#pragma pop_macro("X") 17922int x [X]; 17923@end smallexample 17924 17925@noindent 17926In this example, the definition of X as 1 is saved by @code{#pragma 17927push_macro} and restored by @code{#pragma pop_macro}. 17928 17929@node Function Specific Option Pragmas 17930@subsection Function Specific Option Pragmas 17931 17932@table @code 17933@item #pragma GCC target (@var{"string"}...) 17934@cindex pragma GCC target 17935 17936This pragma allows you to set target specific options for functions 17937defined later in the source file. One or more strings can be 17938specified. Each function that is defined after this point is as 17939if @code{attribute((target("STRING")))} was specified for that 17940function. The parenthesis around the options is optional. 17941@xref{Function Attributes}, for more information about the 17942@code{target} attribute and the attribute syntax. 17943 17944The @code{#pragma GCC target} pragma is presently implemented for 17945x86, PowerPC, and Nios II targets only. 17946@end table 17947 17948@table @code 17949@item #pragma GCC optimize (@var{"string"}...) 17950@cindex pragma GCC optimize 17951 17952This pragma allows you to set global optimization options for functions 17953defined later in the source file. One or more strings can be 17954specified. Each function that is defined after this point is as 17955if @code{attribute((optimize("STRING")))} was specified for that 17956function. The parenthesis around the options is optional. 17957@xref{Function Attributes}, for more information about the 17958@code{optimize} attribute and the attribute syntax. 17959@end table 17960 17961@table @code 17962@item #pragma GCC push_options 17963@itemx #pragma GCC pop_options 17964@cindex pragma GCC push_options 17965@cindex pragma GCC pop_options 17966 17967These pragmas maintain a stack of the current target and optimization 17968options. It is intended for include files where you temporarily want 17969to switch to using a different @samp{#pragma GCC target} or 17970@samp{#pragma GCC optimize} and then to pop back to the previous 17971options. 17972@end table 17973 17974@table @code 17975@item #pragma GCC reset_options 17976@cindex pragma GCC reset_options 17977 17978This pragma clears the current @code{#pragma GCC target} and 17979@code{#pragma GCC optimize} to use the default switches as specified 17980on the command line. 17981@end table 17982 17983@node Loop-Specific Pragmas 17984@subsection Loop-Specific Pragmas 17985 17986@table @code 17987@item #pragma GCC ivdep 17988@cindex pragma GCC ivdep 17989@end table 17990 17991With this pragma, the programmer asserts that there are no loop-carried 17992dependencies which would prevent consecutive iterations of 17993the following loop from executing concurrently with SIMD 17994(single instruction multiple data) instructions. 17995 17996For example, the compiler can only unconditionally vectorize the following 17997loop with the pragma: 17998 17999@smallexample 18000void foo (int n, int *a, int *b, int *c) 18001@{ 18002 int i, j; 18003#pragma GCC ivdep 18004 for (i = 0; i < n; ++i) 18005 a[i] = b[i] + c[i]; 18006@} 18007@end smallexample 18008 18009@noindent 18010In this example, using the @code{restrict} qualifier had the same 18011effect. In the following example, that would not be possible. Assume 18012@math{k < -m} or @math{k >= m}. Only with the pragma, the compiler knows 18013that it can unconditionally vectorize the following loop: 18014 18015@smallexample 18016void ignore_vec_dep (int *a, int k, int c, int m) 18017@{ 18018#pragma GCC ivdep 18019 for (int i = 0; i < m; i++) 18020 a[i] = a[i + k] * c; 18021@} 18022@end smallexample 18023 18024 18025@node Unnamed Fields 18026@section Unnamed Structure and Union Fields 18027@cindex @code{struct} 18028@cindex @code{union} 18029 18030As permitted by ISO C11 and for compatibility with other compilers, 18031GCC allows you to define 18032a structure or union that contains, as fields, structures and unions 18033without names. For example: 18034 18035@smallexample 18036struct @{ 18037 int a; 18038 union @{ 18039 int b; 18040 float c; 18041 @}; 18042 int d; 18043@} foo; 18044@end smallexample 18045 18046@noindent 18047In this example, you are able to access members of the unnamed 18048union with code like @samp{foo.b}. Note that only unnamed structs and 18049unions are allowed, you may not have, for example, an unnamed 18050@code{int}. 18051 18052You must never create such structures that cause ambiguous field definitions. 18053For example, in this structure: 18054 18055@smallexample 18056struct @{ 18057 int a; 18058 struct @{ 18059 int a; 18060 @}; 18061@} foo; 18062@end smallexample 18063 18064@noindent 18065it is ambiguous which @code{a} is being referred to with @samp{foo.a}. 18066The compiler gives errors for such constructs. 18067 18068@opindex fms-extensions 18069Unless @option{-fms-extensions} is used, the unnamed field must be a 18070structure or union definition without a tag (for example, @samp{struct 18071@{ int a; @};}). If @option{-fms-extensions} is used, the field may 18072also be a definition with a tag such as @samp{struct foo @{ int a; 18073@};}, a reference to a previously defined structure or union such as 18074@samp{struct foo;}, or a reference to a @code{typedef} name for a 18075previously defined structure or union type. 18076 18077@opindex fplan9-extensions 18078The option @option{-fplan9-extensions} enables 18079@option{-fms-extensions} as well as two other extensions. First, a 18080pointer to a structure is automatically converted to a pointer to an 18081anonymous field for assignments and function calls. For example: 18082 18083@smallexample 18084struct s1 @{ int a; @}; 18085struct s2 @{ struct s1; @}; 18086extern void f1 (struct s1 *); 18087void f2 (struct s2 *p) @{ f1 (p); @} 18088@end smallexample 18089 18090@noindent 18091In the call to @code{f1} inside @code{f2}, the pointer @code{p} is 18092converted into a pointer to the anonymous field. 18093 18094Second, when the type of an anonymous field is a @code{typedef} for a 18095@code{struct} or @code{union}, code may refer to the field using the 18096name of the @code{typedef}. 18097 18098@smallexample 18099typedef struct @{ int a; @} s1; 18100struct s2 @{ s1; @}; 18101s1 f1 (struct s2 *p) @{ return p->s1; @} 18102@end smallexample 18103 18104These usages are only permitted when they are not ambiguous. 18105 18106@node Thread-Local 18107@section Thread-Local Storage 18108@cindex Thread-Local Storage 18109@cindex @acronym{TLS} 18110@cindex @code{__thread} 18111 18112Thread-local storage (@acronym{TLS}) is a mechanism by which variables 18113are allocated such that there is one instance of the variable per extant 18114thread. The runtime model GCC uses to implement this originates 18115in the IA-64 processor-specific ABI, but has since been migrated 18116to other processors as well. It requires significant support from 18117the linker (@command{ld}), dynamic linker (@command{ld.so}), and 18118system libraries (@file{libc.so} and @file{libpthread.so}), so it 18119is not available everywhere. 18120 18121At the user level, the extension is visible with a new storage 18122class keyword: @code{__thread}. For example: 18123 18124@smallexample 18125__thread int i; 18126extern __thread struct state s; 18127static __thread char *p; 18128@end smallexample 18129 18130The @code{__thread} specifier may be used alone, with the @code{extern} 18131or @code{static} specifiers, but with no other storage class specifier. 18132When used with @code{extern} or @code{static}, @code{__thread} must appear 18133immediately after the other storage class specifier. 18134 18135The @code{__thread} specifier may be applied to any global, file-scoped 18136static, function-scoped static, or static data member of a class. It may 18137not be applied to block-scoped automatic or non-static data member. 18138 18139When the address-of operator is applied to a thread-local variable, it is 18140evaluated at run time and returns the address of the current thread's 18141instance of that variable. An address so obtained may be used by any 18142thread. When a thread terminates, any pointers to thread-local variables 18143in that thread become invalid. 18144 18145No static initialization may refer to the address of a thread-local variable. 18146 18147In C++, if an initializer is present for a thread-local variable, it must 18148be a @var{constant-expression}, as defined in 5.19.2 of the ANSI/ISO C++ 18149standard. 18150 18151See @uref{http://www.akkadia.org/drepper/tls.pdf, 18152ELF Handling For Thread-Local Storage} for a detailed explanation of 18153the four thread-local storage addressing models, and how the runtime 18154is expected to function. 18155 18156@menu 18157* C99 Thread-Local Edits:: 18158* C++98 Thread-Local Edits:: 18159@end menu 18160 18161@node C99 Thread-Local Edits 18162@subsection ISO/IEC 9899:1999 Edits for Thread-Local Storage 18163 18164The following are a set of changes to ISO/IEC 9899:1999 (aka C99) 18165that document the exact semantics of the language extension. 18166 18167@itemize @bullet 18168@item 18169@cite{5.1.2 Execution environments} 18170 18171Add new text after paragraph 1 18172 18173@quotation 18174Within either execution environment, a @dfn{thread} is a flow of 18175control within a program. It is implementation defined whether 18176or not there may be more than one thread associated with a program. 18177It is implementation defined how threads beyond the first are 18178created, the name and type of the function called at thread 18179startup, and how threads may be terminated. However, objects 18180with thread storage duration shall be initialized before thread 18181startup. 18182@end quotation 18183 18184@item 18185@cite{6.2.4 Storage durations of objects} 18186 18187Add new text before paragraph 3 18188 18189@quotation 18190An object whose identifier is declared with the storage-class 18191specifier @w{@code{__thread}} has @dfn{thread storage duration}. 18192Its lifetime is the entire execution of the thread, and its 18193stored value is initialized only once, prior to thread startup. 18194@end quotation 18195 18196@item 18197@cite{6.4.1 Keywords} 18198 18199Add @code{__thread}. 18200 18201@item 18202@cite{6.7.1 Storage-class specifiers} 18203 18204Add @code{__thread} to the list of storage class specifiers in 18205paragraph 1. 18206 18207Change paragraph 2 to 18208 18209@quotation 18210With the exception of @code{__thread}, at most one storage-class 18211specifier may be given [@dots{}]. The @code{__thread} specifier may 18212be used alone, or immediately following @code{extern} or 18213@code{static}. 18214@end quotation 18215 18216Add new text after paragraph 6 18217 18218@quotation 18219The declaration of an identifier for a variable that has 18220block scope that specifies @code{__thread} shall also 18221specify either @code{extern} or @code{static}. 18222 18223The @code{__thread} specifier shall be used only with 18224variables. 18225@end quotation 18226@end itemize 18227 18228@node C++98 Thread-Local Edits 18229@subsection ISO/IEC 14882:1998 Edits for Thread-Local Storage 18230 18231The following are a set of changes to ISO/IEC 14882:1998 (aka C++98) 18232that document the exact semantics of the language extension. 18233 18234@itemize @bullet 18235@item 18236@b{[intro.execution]} 18237 18238New text after paragraph 4 18239 18240@quotation 18241A @dfn{thread} is a flow of control within the abstract machine. 18242It is implementation defined whether or not there may be more than 18243one thread. 18244@end quotation 18245 18246New text after paragraph 7 18247 18248@quotation 18249It is unspecified whether additional action must be taken to 18250ensure when and whether side effects are visible to other threads. 18251@end quotation 18252 18253@item 18254@b{[lex.key]} 18255 18256Add @code{__thread}. 18257 18258@item 18259@b{[basic.start.main]} 18260 18261Add after paragraph 5 18262 18263@quotation 18264The thread that begins execution at the @code{main} function is called 18265the @dfn{main thread}. It is implementation defined how functions 18266beginning threads other than the main thread are designated or typed. 18267A function so designated, as well as the @code{main} function, is called 18268a @dfn{thread startup function}. It is implementation defined what 18269happens if a thread startup function returns. It is implementation 18270defined what happens to other threads when any thread calls @code{exit}. 18271@end quotation 18272 18273@item 18274@b{[basic.start.init]} 18275 18276Add after paragraph 4 18277 18278@quotation 18279The storage for an object of thread storage duration shall be 18280statically initialized before the first statement of the thread startup 18281function. An object of thread storage duration shall not require 18282dynamic initialization. 18283@end quotation 18284 18285@item 18286@b{[basic.start.term]} 18287 18288Add after paragraph 3 18289 18290@quotation 18291The type of an object with thread storage duration shall not have a 18292non-trivial destructor, nor shall it be an array type whose elements 18293(directly or indirectly) have non-trivial destructors. 18294@end quotation 18295 18296@item 18297@b{[basic.stc]} 18298 18299Add ``thread storage duration'' to the list in paragraph 1. 18300 18301Change paragraph 2 18302 18303@quotation 18304Thread, static, and automatic storage durations are associated with 18305objects introduced by declarations [@dots{}]. 18306@end quotation 18307 18308Add @code{__thread} to the list of specifiers in paragraph 3. 18309 18310@item 18311@b{[basic.stc.thread]} 18312 18313New section before @b{[basic.stc.static]} 18314 18315@quotation 18316The keyword @code{__thread} applied to a non-local object gives the 18317object thread storage duration. 18318 18319A local variable or class data member declared both @code{static} 18320and @code{__thread} gives the variable or member thread storage 18321duration. 18322@end quotation 18323 18324@item 18325@b{[basic.stc.static]} 18326 18327Change paragraph 1 18328 18329@quotation 18330All objects that have neither thread storage duration, dynamic 18331storage duration nor are local [@dots{}]. 18332@end quotation 18333 18334@item 18335@b{[dcl.stc]} 18336 18337Add @code{__thread} to the list in paragraph 1. 18338 18339Change paragraph 1 18340 18341@quotation 18342With the exception of @code{__thread}, at most one 18343@var{storage-class-specifier} shall appear in a given 18344@var{decl-specifier-seq}. The @code{__thread} specifier may 18345be used alone, or immediately following the @code{extern} or 18346@code{static} specifiers. [@dots{}] 18347@end quotation 18348 18349Add after paragraph 5 18350 18351@quotation 18352The @code{__thread} specifier can be applied only to the names of objects 18353and to anonymous unions. 18354@end quotation 18355 18356@item 18357@b{[class.mem]} 18358 18359Add after paragraph 6 18360 18361@quotation 18362Non-@code{static} members shall not be @code{__thread}. 18363@end quotation 18364@end itemize 18365 18366@node Binary constants 18367@section Binary Constants using the @samp{0b} Prefix 18368@cindex Binary constants using the @samp{0b} prefix 18369 18370Integer constants can be written as binary constants, consisting of a 18371sequence of @samp{0} and @samp{1} digits, prefixed by @samp{0b} or 18372@samp{0B}. This is particularly useful in environments that operate a 18373lot on the bit level (like microcontrollers). 18374 18375The following statements are identical: 18376 18377@smallexample 18378i = 42; 18379i = 0x2a; 18380i = 052; 18381i = 0b101010; 18382@end smallexample 18383 18384The type of these constants follows the same rules as for octal or 18385hexadecimal integer constants, so suffixes like @samp{L} or @samp{UL} 18386can be applied. 18387 18388@node C++ Extensions 18389@chapter Extensions to the C++ Language 18390@cindex extensions, C++ language 18391@cindex C++ language extensions 18392 18393The GNU compiler provides these extensions to the C++ language (and you 18394can also use most of the C language extensions in your C++ programs). If you 18395want to write code that checks whether these features are available, you can 18396test for the GNU compiler the same way as for C programs: check for a 18397predefined macro @code{__GNUC__}. You can also use @code{__GNUG__} to 18398test specifically for GNU C++ (@pxref{Common Predefined Macros,, 18399Predefined Macros,cpp,The GNU C Preprocessor}). 18400 18401@menu 18402* C++ Volatiles:: What constitutes an access to a volatile object. 18403* Restricted Pointers:: C99 restricted pointers and references. 18404* Vague Linkage:: Where G++ puts inlines, vtables and such. 18405* C++ Interface:: You can use a single C++ header file for both 18406 declarations and definitions. 18407* Template Instantiation:: Methods for ensuring that exactly one copy of 18408 each needed template instantiation is emitted. 18409* Bound member functions:: You can extract a function pointer to the 18410 method denoted by a @samp{->*} or @samp{.*} expression. 18411* C++ Attributes:: Variable, function, and type attributes for C++ only. 18412* Function Multiversioning:: Declaring multiple function versions. 18413* Namespace Association:: Strong using-directives for namespace association. 18414* Type Traits:: Compiler support for type traits 18415* Java Exceptions:: Tweaking exception handling to work with Java. 18416* Deprecated Features:: Things will disappear from G++. 18417* Backwards Compatibility:: Compatibilities with earlier definitions of C++. 18418@end menu 18419 18420@node C++ Volatiles 18421@section When is a Volatile C++ Object Accessed? 18422@cindex accessing volatiles 18423@cindex volatile read 18424@cindex volatile write 18425@cindex volatile access 18426 18427The C++ standard differs from the C standard in its treatment of 18428volatile objects. It fails to specify what constitutes a volatile 18429access, except to say that C++ should behave in a similar manner to C 18430with respect to volatiles, where possible. However, the different 18431lvalueness of expressions between C and C++ complicate the behavior. 18432G++ behaves the same as GCC for volatile access, @xref{C 18433Extensions,,Volatiles}, for a description of GCC's behavior. 18434 18435The C and C++ language specifications differ when an object is 18436accessed in a void context: 18437 18438@smallexample 18439volatile int *src = @var{somevalue}; 18440*src; 18441@end smallexample 18442 18443The C++ standard specifies that such expressions do not undergo lvalue 18444to rvalue conversion, and that the type of the dereferenced object may 18445be incomplete. The C++ standard does not specify explicitly that it 18446is lvalue to rvalue conversion that is responsible for causing an 18447access. There is reason to believe that it is, because otherwise 18448certain simple expressions become undefined. However, because it 18449would surprise most programmers, G++ treats dereferencing a pointer to 18450volatile object of complete type as GCC would do for an equivalent 18451type in C@. When the object has incomplete type, G++ issues a 18452warning; if you wish to force an error, you must force a conversion to 18453rvalue with, for instance, a static cast. 18454 18455When using a reference to volatile, G++ does not treat equivalent 18456expressions as accesses to volatiles, but instead issues a warning that 18457no volatile is accessed. The rationale for this is that otherwise it 18458becomes difficult to determine where volatile access occur, and not 18459possible to ignore the return value from functions returning volatile 18460references. Again, if you wish to force a read, cast the reference to 18461an rvalue. 18462 18463G++ implements the same behavior as GCC does when assigning to a 18464volatile object---there is no reread of the assigned-to object, the 18465assigned rvalue is reused. Note that in C++ assignment expressions 18466are lvalues, and if used as an lvalue, the volatile object is 18467referred to. For instance, @var{vref} refers to @var{vobj}, as 18468expected, in the following example: 18469 18470@smallexample 18471volatile int vobj; 18472volatile int &vref = vobj = @var{something}; 18473@end smallexample 18474 18475@node Restricted Pointers 18476@section Restricting Pointer Aliasing 18477@cindex restricted pointers 18478@cindex restricted references 18479@cindex restricted this pointer 18480 18481As with the C front end, G++ understands the C99 feature of restricted pointers, 18482specified with the @code{__restrict__}, or @code{__restrict} type 18483qualifier. Because you cannot compile C++ by specifying the @option{-std=c99} 18484language flag, @code{restrict} is not a keyword in C++. 18485 18486In addition to allowing restricted pointers, you can specify restricted 18487references, which indicate that the reference is not aliased in the local 18488context. 18489 18490@smallexample 18491void fn (int *__restrict__ rptr, int &__restrict__ rref) 18492@{ 18493 /* @r{@dots{}} */ 18494@} 18495@end smallexample 18496 18497@noindent 18498In the body of @code{fn}, @var{rptr} points to an unaliased integer and 18499@var{rref} refers to a (different) unaliased integer. 18500 18501You may also specify whether a member function's @var{this} pointer is 18502unaliased by using @code{__restrict__} as a member function qualifier. 18503 18504@smallexample 18505void T::fn () __restrict__ 18506@{ 18507 /* @r{@dots{}} */ 18508@} 18509@end smallexample 18510 18511@noindent 18512Within the body of @code{T::fn}, @var{this} has the effective 18513definition @code{T *__restrict__ const this}. Notice that the 18514interpretation of a @code{__restrict__} member function qualifier is 18515different to that of @code{const} or @code{volatile} qualifier, in that it 18516is applied to the pointer rather than the object. This is consistent with 18517other compilers that implement restricted pointers. 18518 18519As with all outermost parameter qualifiers, @code{__restrict__} is 18520ignored in function definition matching. This means you only need to 18521specify @code{__restrict__} in a function definition, rather than 18522in a function prototype as well. 18523 18524@node Vague Linkage 18525@section Vague Linkage 18526@cindex vague linkage 18527 18528There are several constructs in C++ that require space in the object 18529file but are not clearly tied to a single translation unit. We say that 18530these constructs have ``vague linkage''. Typically such constructs are 18531emitted wherever they are needed, though sometimes we can be more 18532clever. 18533 18534@table @asis 18535@item Inline Functions 18536Inline functions are typically defined in a header file which can be 18537included in many different compilations. Hopefully they can usually be 18538inlined, but sometimes an out-of-line copy is necessary, if the address 18539of the function is taken or if inlining fails. In general, we emit an 18540out-of-line copy in all translation units where one is needed. As an 18541exception, we only emit inline virtual functions with the vtable, since 18542it always requires a copy. 18543 18544Local static variables and string constants used in an inline function 18545are also considered to have vague linkage, since they must be shared 18546between all inlined and out-of-line instances of the function. 18547 18548@item VTables 18549@cindex vtable 18550C++ virtual functions are implemented in most compilers using a lookup 18551table, known as a vtable. The vtable contains pointers to the virtual 18552functions provided by a class, and each object of the class contains a 18553pointer to its vtable (or vtables, in some multiple-inheritance 18554situations). If the class declares any non-inline, non-pure virtual 18555functions, the first one is chosen as the ``key method'' for the class, 18556and the vtable is only emitted in the translation unit where the key 18557method is defined. 18558 18559@emph{Note:} If the chosen key method is later defined as inline, the 18560vtable is still emitted in every translation unit that defines it. 18561Make sure that any inline virtuals are declared inline in the class 18562body, even if they are not defined there. 18563 18564@item @code{type_info} objects 18565@cindex @code{type_info} 18566@cindex RTTI 18567C++ requires information about types to be written out in order to 18568implement @samp{dynamic_cast}, @samp{typeid} and exception handling. 18569For polymorphic classes (classes with virtual functions), the @samp{type_info} 18570object is written out along with the vtable so that @samp{dynamic_cast} 18571can determine the dynamic type of a class object at run time. For all 18572other types, we write out the @samp{type_info} object when it is used: when 18573applying @samp{typeid} to an expression, throwing an object, or 18574referring to a type in a catch clause or exception specification. 18575 18576@item Template Instantiations 18577Most everything in this section also applies to template instantiations, 18578but there are other options as well. 18579@xref{Template Instantiation,,Where's the Template?}. 18580 18581@end table 18582 18583When used with GNU ld version 2.8 or later on an ELF system such as 18584GNU/Linux or Solaris 2, or on Microsoft Windows, duplicate copies of 18585these constructs will be discarded at link time. This is known as 18586COMDAT support. 18587 18588On targets that don't support COMDAT, but do support weak symbols, GCC 18589uses them. This way one copy overrides all the others, but 18590the unused copies still take up space in the executable. 18591 18592For targets that do not support either COMDAT or weak symbols, 18593most entities with vague linkage are emitted as local symbols to 18594avoid duplicate definition errors from the linker. This does not happen 18595for local statics in inlines, however, as having multiple copies 18596almost certainly breaks things. 18597 18598@xref{C++ Interface,,Declarations and Definitions in One Header}, for 18599another way to control placement of these constructs. 18600 18601@node C++ Interface 18602@section C++ Interface and Implementation Pragmas 18603 18604@cindex interface and implementation headers, C++ 18605@cindex C++ interface and implementation headers 18606@cindex pragmas, interface and implementation 18607 18608@code{#pragma interface} and @code{#pragma implementation} provide the 18609user with a way of explicitly directing the compiler to emit entities 18610with vague linkage (and debugging information) in a particular 18611translation unit. 18612 18613@emph{Note:} These @code{#pragma}s have been superceded as of GCC 2.7.2 18614by COMDAT support and the ``key method'' heuristic 18615mentioned in @ref{Vague Linkage}. Using them can actually cause your 18616program to grow due to unnecessary out-of-line copies of inline 18617functions. 18618 18619@table @code 18620@item #pragma interface 18621@itemx #pragma interface "@var{subdir}/@var{objects}.h" 18622@kindex #pragma interface 18623Use this directive in @emph{header files} that define object classes, to save 18624space in most of the object files that use those classes. Normally, 18625local copies of certain information (backup copies of inline member 18626functions, debugging information, and the internal tables that implement 18627virtual functions) must be kept in each object file that includes class 18628definitions. You can use this pragma to avoid such duplication. When a 18629header file containing @samp{#pragma interface} is included in a 18630compilation, this auxiliary information is not generated (unless 18631the main input source file itself uses @samp{#pragma implementation}). 18632Instead, the object files contain references to be resolved at link 18633time. 18634 18635The second form of this directive is useful for the case where you have 18636multiple headers with the same name in different directories. If you 18637use this form, you must specify the same string to @samp{#pragma 18638implementation}. 18639 18640@item #pragma implementation 18641@itemx #pragma implementation "@var{objects}.h" 18642@kindex #pragma implementation 18643Use this pragma in a @emph{main input file}, when you want full output from 18644included header files to be generated (and made globally visible). The 18645included header file, in turn, should use @samp{#pragma interface}. 18646Backup copies of inline member functions, debugging information, and the 18647internal tables used to implement virtual functions are all generated in 18648implementation files. 18649 18650@cindex implied @code{#pragma implementation} 18651@cindex @code{#pragma implementation}, implied 18652@cindex naming convention, implementation headers 18653If you use @samp{#pragma implementation} with no argument, it applies to 18654an include file with the same basename@footnote{A file's @dfn{basename} 18655is the name stripped of all leading path information and of trailing 18656suffixes, such as @samp{.h} or @samp{.C} or @samp{.cc}.} as your source 18657file. For example, in @file{allclass.cc}, giving just 18658@samp{#pragma implementation} 18659by itself is equivalent to @samp{#pragma implementation "allclass.h"}. 18660 18661Use the string argument if you want a single implementation file to 18662include code from multiple header files. (You must also use 18663@samp{#include} to include the header file; @samp{#pragma 18664implementation} only specifies how to use the file---it doesn't actually 18665include it.) 18666 18667There is no way to split up the contents of a single header file into 18668multiple implementation files. 18669@end table 18670 18671@cindex inlining and C++ pragmas 18672@cindex C++ pragmas, effect on inlining 18673@cindex pragmas in C++, effect on inlining 18674@samp{#pragma implementation} and @samp{#pragma interface} also have an 18675effect on function inlining. 18676 18677If you define a class in a header file marked with @samp{#pragma 18678interface}, the effect on an inline function defined in that class is 18679similar to an explicit @code{extern} declaration---the compiler emits 18680no code at all to define an independent version of the function. Its 18681definition is used only for inlining with its callers. 18682 18683@opindex fno-implement-inlines 18684Conversely, when you include the same header file in a main source file 18685that declares it as @samp{#pragma implementation}, the compiler emits 18686code for the function itself; this defines a version of the function 18687that can be found via pointers (or by callers compiled without 18688inlining). If all calls to the function can be inlined, you can avoid 18689emitting the function by compiling with @option{-fno-implement-inlines}. 18690If any calls are not inlined, you will get linker errors. 18691 18692@node Template Instantiation 18693@section Where's the Template? 18694@cindex template instantiation 18695 18696C++ templates are the first language feature to require more 18697intelligence from the environment than one usually finds on a UNIX 18698system. Somehow the compiler and linker have to make sure that each 18699template instance occurs exactly once in the executable if it is needed, 18700and not at all otherwise. There are two basic approaches to this 18701problem, which are referred to as the Borland model and the Cfront model. 18702 18703@table @asis 18704@item Borland model 18705Borland C++ solved the template instantiation problem by adding the code 18706equivalent of common blocks to their linker; the compiler emits template 18707instances in each translation unit that uses them, and the linker 18708collapses them together. The advantage of this model is that the linker 18709only has to consider the object files themselves; there is no external 18710complexity to worry about. This disadvantage is that compilation time 18711is increased because the template code is being compiled repeatedly. 18712Code written for this model tends to include definitions of all 18713templates in the header file, since they must be seen to be 18714instantiated. 18715 18716@item Cfront model 18717The AT&T C++ translator, Cfront, solved the template instantiation 18718problem by creating the notion of a template repository, an 18719automatically maintained place where template instances are stored. A 18720more modern version of the repository works as follows: As individual 18721object files are built, the compiler places any template definitions and 18722instantiations encountered in the repository. At link time, the link 18723wrapper adds in the objects in the repository and compiles any needed 18724instances that were not previously emitted. The advantages of this 18725model are more optimal compilation speed and the ability to use the 18726system linker; to implement the Borland model a compiler vendor also 18727needs to replace the linker. The disadvantages are vastly increased 18728complexity, and thus potential for error; for some code this can be 18729just as transparent, but in practice it can been very difficult to build 18730multiple programs in one directory and one program in multiple 18731directories. Code written for this model tends to separate definitions 18732of non-inline member templates into a separate file, which should be 18733compiled separately. 18734@end table 18735 18736When used with GNU ld version 2.8 or later on an ELF system such as 18737GNU/Linux or Solaris 2, or on Microsoft Windows, G++ supports the 18738Borland model. On other systems, G++ implements neither automatic 18739model. 18740 18741You have the following options for dealing with template instantiations: 18742 18743@enumerate 18744@item 18745@opindex frepo 18746Compile your template-using code with @option{-frepo}. The compiler 18747generates files with the extension @samp{.rpo} listing all of the 18748template instantiations used in the corresponding object files that 18749could be instantiated there; the link wrapper, @samp{collect2}, 18750then updates the @samp{.rpo} files to tell the compiler where to place 18751those instantiations and rebuild any affected object files. The 18752link-time overhead is negligible after the first pass, as the compiler 18753continues to place the instantiations in the same files. 18754 18755This is your best option for application code written for the Borland 18756model, as it just works. Code written for the Cfront model 18757needs to be modified so that the template definitions are available at 18758one or more points of instantiation; usually this is as simple as adding 18759@code{#include <tmethods.cc>} to the end of each template header. 18760 18761For library code, if you want the library to provide all of the template 18762instantiations it needs, just try to link all of its object files 18763together; the link will fail, but cause the instantiations to be 18764generated as a side effect. Be warned, however, that this may cause 18765conflicts if multiple libraries try to provide the same instantiations. 18766For greater control, use explicit instantiation as described in the next 18767option. 18768 18769@item 18770@opindex fno-implicit-templates 18771Compile your code with @option{-fno-implicit-templates} to disable the 18772implicit generation of template instances, and explicitly instantiate 18773all the ones you use. This approach requires more knowledge of exactly 18774which instances you need than do the others, but it's less 18775mysterious and allows greater control. You can scatter the explicit 18776instantiations throughout your program, perhaps putting them in the 18777translation units where the instances are used or the translation units 18778that define the templates themselves; you can put all of the explicit 18779instantiations you need into one big file; or you can create small files 18780like 18781 18782@smallexample 18783#include "Foo.h" 18784#include "Foo.cc" 18785 18786template class Foo<int>; 18787template ostream& operator << 18788 (ostream&, const Foo<int>&); 18789@end smallexample 18790 18791@noindent 18792for each of the instances you need, and create a template instantiation 18793library from those. 18794 18795If you are using Cfront-model code, you can probably get away with not 18796using @option{-fno-implicit-templates} when compiling files that don't 18797@samp{#include} the member template definitions. 18798 18799If you use one big file to do the instantiations, you may want to 18800compile it without @option{-fno-implicit-templates} so you get all of the 18801instances required by your explicit instantiations (but not by any 18802other files) without having to specify them as well. 18803 18804The ISO C++ 2011 standard allows forward declaration of explicit 18805instantiations (with @code{extern}). G++ supports explicit instantiation 18806declarations in C++98 mode and has extended the template instantiation 18807syntax to support instantiation of the compiler support data for a 18808template class (i.e.@: the vtable) without instantiating any of its 18809members (with @code{inline}), and instantiation of only the static data 18810members of a template class, without the support data or member 18811functions (with @code{static}): 18812 18813@smallexample 18814extern template int max (int, int); 18815inline template class Foo<int>; 18816static template class Foo<int>; 18817@end smallexample 18818 18819@item 18820Do nothing. Pretend G++ does implement automatic instantiation 18821management. Code written for the Borland model works fine, but 18822each translation unit contains instances of each of the templates it 18823uses. In a large program, this can lead to an unacceptable amount of code 18824duplication. 18825@end enumerate 18826 18827@node Bound member functions 18828@section Extracting the Function Pointer from a Bound Pointer to Member Function 18829@cindex pmf 18830@cindex pointer to member function 18831@cindex bound pointer to member function 18832 18833In C++, pointer to member functions (PMFs) are implemented using a wide 18834pointer of sorts to handle all the possible call mechanisms; the PMF 18835needs to store information about how to adjust the @samp{this} pointer, 18836and if the function pointed to is virtual, where to find the vtable, and 18837where in the vtable to look for the member function. If you are using 18838PMFs in an inner loop, you should really reconsider that decision. If 18839that is not an option, you can extract the pointer to the function that 18840would be called for a given object/PMF pair and call it directly inside 18841the inner loop, to save a bit of time. 18842 18843Note that you still pay the penalty for the call through a 18844function pointer; on most modern architectures, such a call defeats the 18845branch prediction features of the CPU@. This is also true of normal 18846virtual function calls. 18847 18848The syntax for this extension is 18849 18850@smallexample 18851extern A a; 18852extern int (A::*fp)(); 18853typedef int (*fptr)(A *); 18854 18855fptr p = (fptr)(a.*fp); 18856@end smallexample 18857 18858For PMF constants (i.e.@: expressions of the form @samp{&Klasse::Member}), 18859no object is needed to obtain the address of the function. They can be 18860converted to function pointers directly: 18861 18862@smallexample 18863fptr p1 = (fptr)(&A::foo); 18864@end smallexample 18865 18866@opindex Wno-pmf-conversions 18867You must specify @option{-Wno-pmf-conversions} to use this extension. 18868 18869@node C++ Attributes 18870@section C++-Specific Variable, Function, and Type Attributes 18871 18872Some attributes only make sense for C++ programs. 18873 18874@table @code 18875@item abi_tag ("@var{tag}", ...) 18876@cindex @code{abi_tag} function attribute 18877@cindex @code{abi_tag} variable attribute 18878@cindex @code{abi_tag} type attribute 18879The @code{abi_tag} attribute can be applied to a function, variable, or class 18880declaration. It modifies the mangled name of the entity to 18881incorporate the tag name, in order to distinguish the function or 18882class from an earlier version with a different ABI; perhaps the class 18883has changed size, or the function has a different return type that is 18884not encoded in the mangled name. 18885 18886The attribute can also be applied to an inline namespace, but does not 18887affect the mangled name of the namespace; in this case it is only used 18888for @option{-Wabi-tag} warnings and automatic tagging of functions and 18889variables. Tagging inline namespaces is generally preferable to 18890tagging individual declarations, but the latter is sometimes 18891necessary, such as when only certain members of a class need to be 18892tagged. 18893 18894The argument can be a list of strings of arbitrary length. The 18895strings are sorted on output, so the order of the list is 18896unimportant. 18897 18898A redeclaration of an entity must not add new ABI tags, 18899since doing so would change the mangled name. 18900 18901The ABI tags apply to a name, so all instantiations and 18902specializations of a template have the same tags. The attribute will 18903be ignored if applied to an explicit specialization or instantiation. 18904 18905The @option{-Wabi-tag} flag enables a warning about a class which does 18906not have all the ABI tags used by its subobjects and virtual functions; for users with code 18907that needs to coexist with an earlier ABI, using this option can help 18908to find all affected types that need to be tagged. 18909 18910When a type involving an ABI tag is used as the type of a variable or 18911return type of a function where that tag is not already present in the 18912signature of the function, the tag is automatically applied to the 18913variable or function. @option{-Wabi-tag} also warns about this 18914situation; this warning can be avoided by explicitly tagging the 18915variable or function or moving it into a tagged inline namespace. 18916 18917@item init_priority (@var{priority}) 18918@cindex @code{init_priority} variable attribute 18919 18920In Standard C++, objects defined at namespace scope are guaranteed to be 18921initialized in an order in strict accordance with that of their definitions 18922@emph{in a given translation unit}. No guarantee is made for initializations 18923across translation units. However, GNU C++ allows users to control the 18924order of initialization of objects defined at namespace scope with the 18925@code{init_priority} attribute by specifying a relative @var{priority}, 18926a constant integral expression currently bounded between 101 and 65535 18927inclusive. Lower numbers indicate a higher priority. 18928 18929In the following example, @code{A} would normally be created before 18930@code{B}, but the @code{init_priority} attribute reverses that order: 18931 18932@smallexample 18933Some_Class A __attribute__ ((init_priority (2000))); 18934Some_Class B __attribute__ ((init_priority (543))); 18935@end smallexample 18936 18937@noindent 18938Note that the particular values of @var{priority} do not matter; only their 18939relative ordering. 18940 18941@item java_interface 18942@cindex @code{java_interface} type attribute 18943 18944This type attribute informs C++ that the class is a Java interface. It may 18945only be applied to classes declared within an @code{extern "Java"} block. 18946Calls to methods declared in this interface are dispatched using GCJ's 18947interface table mechanism, instead of regular virtual table dispatch. 18948 18949@item warn_unused 18950@cindex @code{warn_unused} type attribute 18951 18952For C++ types with non-trivial constructors and/or destructors it is 18953impossible for the compiler to determine whether a variable of this 18954type is truly unused if it is not referenced. This type attribute 18955informs the compiler that variables of this type should be warned 18956about if they appear to be unused, just like variables of fundamental 18957types. 18958 18959This attribute is appropriate for types which just represent a value, 18960such as @code{std::string}; it is not appropriate for types which 18961control a resource, such as @code{std::mutex}. 18962 18963This attribute is also accepted in C, but it is unnecessary because C 18964does not have constructors or destructors. 18965 18966@end table 18967 18968See also @ref{Namespace Association}. 18969 18970@node Function Multiversioning 18971@section Function Multiversioning 18972@cindex function versions 18973 18974With the GNU C++ front end, for x86 targets, you may specify multiple 18975versions of a function, where each function is specialized for a 18976specific target feature. At runtime, the appropriate version of the 18977function is automatically executed depending on the characteristics of 18978the execution platform. Here is an example. 18979 18980@smallexample 18981__attribute__ ((target ("default"))) 18982int foo () 18983@{ 18984 // The default version of foo. 18985 return 0; 18986@} 18987 18988__attribute__ ((target ("sse4.2"))) 18989int foo () 18990@{ 18991 // foo version for SSE4.2 18992 return 1; 18993@} 18994 18995__attribute__ ((target ("arch=atom"))) 18996int foo () 18997@{ 18998 // foo version for the Intel ATOM processor 18999 return 2; 19000@} 19001 19002__attribute__ ((target ("arch=amdfam10"))) 19003int foo () 19004@{ 19005 // foo version for the AMD Family 0x10 processors. 19006 return 3; 19007@} 19008 19009int main () 19010@{ 19011 int (*p)() = &foo; 19012 assert ((*p) () == foo ()); 19013 return 0; 19014@} 19015@end smallexample 19016 19017In the above example, four versions of function foo are created. The 19018first version of foo with the target attribute "default" is the default 19019version. This version gets executed when no other target specific 19020version qualifies for execution on a particular platform. A new version 19021of foo is created by using the same function signature but with a 19022different target string. Function foo is called or a pointer to it is 19023taken just like a regular function. GCC takes care of doing the 19024dispatching to call the right version at runtime. Refer to the 19025@uref{http://gcc.gnu.org/wiki/FunctionMultiVersioning, GCC wiki on 19026Function Multiversioning} for more details. 19027 19028@node Namespace Association 19029@section Namespace Association 19030 19031@strong{Caution:} The semantics of this extension are equivalent 19032to C++ 2011 inline namespaces. Users should use inline namespaces 19033instead as this extension will be removed in future versions of G++. 19034 19035A using-directive with @code{__attribute ((strong))} is stronger 19036than a normal using-directive in two ways: 19037 19038@itemize @bullet 19039@item 19040Templates from the used namespace can be specialized and explicitly 19041instantiated as though they were members of the using namespace. 19042 19043@item 19044The using namespace is considered an associated namespace of all 19045templates in the used namespace for purposes of argument-dependent 19046name lookup. 19047@end itemize 19048 19049The used namespace must be nested within the using namespace so that 19050normal unqualified lookup works properly. 19051 19052This is useful for composing a namespace transparently from 19053implementation namespaces. For example: 19054 19055@smallexample 19056namespace std @{ 19057 namespace debug @{ 19058 template <class T> struct A @{ @}; 19059 @} 19060 using namespace debug __attribute ((__strong__)); 19061 template <> struct A<int> @{ @}; // @r{OK to specialize} 19062 19063 template <class T> void f (A<T>); 19064@} 19065 19066int main() 19067@{ 19068 f (std::A<float>()); // @r{lookup finds} std::f 19069 f (std::A<int>()); 19070@} 19071@end smallexample 19072 19073@node Type Traits 19074@section Type Traits 19075 19076The C++ front end implements syntactic extensions that allow 19077compile-time determination of 19078various characteristics of a type (or of a 19079pair of types). 19080 19081@table @code 19082@item __has_nothrow_assign (type) 19083If @code{type} is const qualified or is a reference type then the trait is 19084false. Otherwise if @code{__has_trivial_assign (type)} is true then the trait 19085is true, else if @code{type} is a cv class or union type with copy assignment 19086operators that are known not to throw an exception then the trait is true, 19087else it is false. Requires: @code{type} shall be a complete type, 19088(possibly cv-qualified) @code{void}, or an array of unknown bound. 19089 19090@item __has_nothrow_copy (type) 19091If @code{__has_trivial_copy (type)} is true then the trait is true, else if 19092@code{type} is a cv class or union type with copy constructors that 19093are known not to throw an exception then the trait is true, else it is false. 19094Requires: @code{type} shall be a complete type, (possibly cv-qualified) 19095@code{void}, or an array of unknown bound. 19096 19097@item __has_nothrow_constructor (type) 19098If @code{__has_trivial_constructor (type)} is true then the trait is 19099true, else if @code{type} is a cv class or union type (or array 19100thereof) with a default constructor that is known not to throw an 19101exception then the trait is true, else it is false. Requires: 19102@code{type} shall be a complete type, (possibly cv-qualified) 19103@code{void}, or an array of unknown bound. 19104 19105@item __has_trivial_assign (type) 19106If @code{type} is const qualified or is a reference type then the trait is 19107false. Otherwise if @code{__is_pod (type)} is true then the trait is 19108true, else if @code{type} is a cv class or union type with a trivial 19109copy assignment ([class.copy]) then the trait is true, else it is 19110false. Requires: @code{type} shall be a complete type, (possibly 19111cv-qualified) @code{void}, or an array of unknown bound. 19112 19113@item __has_trivial_copy (type) 19114If @code{__is_pod (type)} is true or @code{type} is a reference type 19115then the trait is true, else if @code{type} is a cv class or union type 19116with a trivial copy constructor ([class.copy]) then the trait 19117is true, else it is false. Requires: @code{type} shall be a complete 19118type, (possibly cv-qualified) @code{void}, or an array of unknown bound. 19119 19120@item __has_trivial_constructor (type) 19121If @code{__is_pod (type)} is true then the trait is true, else if 19122@code{type} is a cv class or union type (or array thereof) with a 19123trivial default constructor ([class.ctor]) then the trait is true, 19124else it is false. Requires: @code{type} shall be a complete 19125type, (possibly cv-qualified) @code{void}, or an array of unknown bound. 19126 19127@item __has_trivial_destructor (type) 19128If @code{__is_pod (type)} is true or @code{type} is a reference type then 19129the trait is true, else if @code{type} is a cv class or union type (or 19130array thereof) with a trivial destructor ([class.dtor]) then the trait 19131is true, else it is false. Requires: @code{type} shall be a complete 19132type, (possibly cv-qualified) @code{void}, or an array of unknown bound. 19133 19134@item __has_virtual_destructor (type) 19135If @code{type} is a class type with a virtual destructor 19136([class.dtor]) then the trait is true, else it is false. Requires: 19137@code{type} shall be a complete type, (possibly cv-qualified) 19138@code{void}, or an array of unknown bound. 19139 19140@item __is_abstract (type) 19141If @code{type} is an abstract class ([class.abstract]) then the trait 19142is true, else it is false. Requires: @code{type} shall be a complete 19143type, (possibly cv-qualified) @code{void}, or an array of unknown bound. 19144 19145@item __is_base_of (base_type, derived_type) 19146If @code{base_type} is a base class of @code{derived_type} 19147([class.derived]) then the trait is true, otherwise it is false. 19148Top-level cv qualifications of @code{base_type} and 19149@code{derived_type} are ignored. For the purposes of this trait, a 19150class type is considered is own base. Requires: if @code{__is_class 19151(base_type)} and @code{__is_class (derived_type)} are true and 19152@code{base_type} and @code{derived_type} are not the same type 19153(disregarding cv-qualifiers), @code{derived_type} shall be a complete 19154type. Diagnostic is produced if this requirement is not met. 19155 19156@item __is_class (type) 19157If @code{type} is a cv class type, and not a union type 19158([basic.compound]) the trait is true, else it is false. 19159 19160@item __is_empty (type) 19161If @code{__is_class (type)} is false then the trait is false. 19162Otherwise @code{type} is considered empty if and only if: @code{type} 19163has no non-static data members, or all non-static data members, if 19164any, are bit-fields of length 0, and @code{type} has no virtual 19165members, and @code{type} has no virtual base classes, and @code{type} 19166has no base classes @code{base_type} for which 19167@code{__is_empty (base_type)} is false. Requires: @code{type} shall 19168be a complete type, (possibly cv-qualified) @code{void}, or an array 19169of unknown bound. 19170 19171@item __is_enum (type) 19172If @code{type} is a cv enumeration type ([basic.compound]) the trait is 19173true, else it is false. 19174 19175@item __is_literal_type (type) 19176If @code{type} is a literal type ([basic.types]) the trait is 19177true, else it is false. Requires: @code{type} shall be a complete type, 19178(possibly cv-qualified) @code{void}, or an array of unknown bound. 19179 19180@item __is_pod (type) 19181If @code{type} is a cv POD type ([basic.types]) then the trait is true, 19182else it is false. Requires: @code{type} shall be a complete type, 19183(possibly cv-qualified) @code{void}, or an array of unknown bound. 19184 19185@item __is_polymorphic (type) 19186If @code{type} is a polymorphic class ([class.virtual]) then the trait 19187is true, else it is false. Requires: @code{type} shall be a complete 19188type, (possibly cv-qualified) @code{void}, or an array of unknown bound. 19189 19190@item __is_standard_layout (type) 19191If @code{type} is a standard-layout type ([basic.types]) the trait is 19192true, else it is false. Requires: @code{type} shall be a complete 19193type, (possibly cv-qualified) @code{void}, or an array of unknown bound. 19194 19195@item __is_trivial (type) 19196If @code{type} is a trivial type ([basic.types]) the trait is 19197true, else it is false. Requires: @code{type} shall be a complete 19198type, (possibly cv-qualified) @code{void}, or an array of unknown bound. 19199 19200@item __is_union (type) 19201If @code{type} is a cv union type ([basic.compound]) the trait is 19202true, else it is false. 19203 19204@item __underlying_type (type) 19205The underlying type of @code{type}. Requires: @code{type} shall be 19206an enumeration type ([dcl.enum]). 19207 19208@end table 19209 19210@node Java Exceptions 19211@section Java Exceptions 19212 19213The Java language uses a slightly different exception handling model 19214from C++. Normally, GNU C++ automatically detects when you are 19215writing C++ code that uses Java exceptions, and handle them 19216appropriately. However, if C++ code only needs to execute destructors 19217when Java exceptions are thrown through it, GCC guesses incorrectly. 19218Sample problematic code is: 19219 19220@smallexample 19221 struct S @{ ~S(); @}; 19222 extern void bar(); // @r{is written in Java, and may throw exceptions} 19223 void foo() 19224 @{ 19225 S s; 19226 bar(); 19227 @} 19228@end smallexample 19229 19230@noindent 19231The usual effect of an incorrect guess is a link failure, complaining of 19232a missing routine called @samp{__gxx_personality_v0}. 19233 19234You can inform the compiler that Java exceptions are to be used in a 19235translation unit, irrespective of what it might think, by writing 19236@samp{@w{#pragma GCC java_exceptions}} at the head of the file. This 19237@samp{#pragma} must appear before any functions that throw or catch 19238exceptions, or run destructors when exceptions are thrown through them. 19239 19240You cannot mix Java and C++ exceptions in the same translation unit. It 19241is believed to be safe to throw a C++ exception from one file through 19242another file compiled for the Java exception model, or vice versa, but 19243there may be bugs in this area. 19244 19245@node Deprecated Features 19246@section Deprecated Features 19247 19248In the past, the GNU C++ compiler was extended to experiment with new 19249features, at a time when the C++ language was still evolving. Now that 19250the C++ standard is complete, some of those features are superseded by 19251superior alternatives. Using the old features might cause a warning in 19252some cases that the feature will be dropped in the future. In other 19253cases, the feature might be gone already. 19254 19255While the list below is not exhaustive, it documents some of the options 19256that are now deprecated: 19257 19258@table @code 19259@item -fexternal-templates 19260@itemx -falt-external-templates 19261These are two of the many ways for G++ to implement template 19262instantiation. @xref{Template Instantiation}. The C++ standard clearly 19263defines how template definitions have to be organized across 19264implementation units. G++ has an implicit instantiation mechanism that 19265should work just fine for standard-conforming code. 19266 19267@item -fstrict-prototype 19268@itemx -fno-strict-prototype 19269Previously it was possible to use an empty prototype parameter list to 19270indicate an unspecified number of parameters (like C), rather than no 19271parameters, as C++ demands. This feature has been removed, except where 19272it is required for backwards compatibility. @xref{Backwards Compatibility}. 19273@end table 19274 19275G++ allows a virtual function returning @samp{void *} to be overridden 19276by one returning a different pointer type. This extension to the 19277covariant return type rules is now deprecated and will be removed from a 19278future version. 19279 19280The G++ minimum and maximum operators (@samp{<?} and @samp{>?}) and 19281their compound forms (@samp{<?=}) and @samp{>?=}) have been deprecated 19282and are now removed from G++. Code using these operators should be 19283modified to use @code{std::min} and @code{std::max} instead. 19284 19285The named return value extension has been deprecated, and is now 19286removed from G++. 19287 19288The use of initializer lists with new expressions has been deprecated, 19289and is now removed from G++. 19290 19291Floating and complex non-type template parameters have been deprecated, 19292and are now removed from G++. 19293 19294The implicit typename extension has been deprecated and is now 19295removed from G++. 19296 19297The use of default arguments in function pointers, function typedefs 19298and other places where they are not permitted by the standard is 19299deprecated and will be removed from a future version of G++. 19300 19301G++ allows floating-point literals to appear in integral constant expressions, 19302e.g.@: @samp{ enum E @{ e = int(2.2 * 3.7) @} } 19303This extension is deprecated and will be removed from a future version. 19304 19305G++ allows static data members of const floating-point type to be declared 19306with an initializer in a class definition. The standard only allows 19307initializers for static members of const integral types and const 19308enumeration types so this extension has been deprecated and will be removed 19309from a future version. 19310 19311@node Backwards Compatibility 19312@section Backwards Compatibility 19313@cindex Backwards Compatibility 19314@cindex ARM [Annotated C++ Reference Manual] 19315 19316Now that there is a definitive ISO standard C++, G++ has a specification 19317to adhere to. The C++ language evolved over time, and features that 19318used to be acceptable in previous drafts of the standard, such as the ARM 19319[Annotated C++ Reference Manual], are no longer accepted. In order to allow 19320compilation of C++ written to such drafts, G++ contains some backwards 19321compatibilities. @emph{All such backwards compatibility features are 19322liable to disappear in future versions of G++.} They should be considered 19323deprecated. @xref{Deprecated Features}. 19324 19325@table @code 19326@item For scope 19327If a variable is declared at for scope, it used to remain in scope until 19328the end of the scope that contained the for statement (rather than just 19329within the for scope). G++ retains this, but issues a warning, if such a 19330variable is accessed outside the for scope. 19331 19332@item Implicit C language 19333Old C system header files did not contain an @code{extern "C" @{@dots{}@}} 19334scope to set the language. On such systems, all header files are 19335implicitly scoped inside a C language scope. Also, an empty prototype 19336@code{()} is treated as an unspecified number of arguments, rather 19337than no arguments, as C++ demands. 19338@end table 19339 19340@c LocalWords: emph deftypefn builtin ARCv2EM SIMD builtins msimd 19341@c LocalWords: typedef v4si v8hi DMA dma vdiwr vdowr 19342