1 c Copyright (C) 1988-2022 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 12 GNU C provides several language features not found in ISO standard C@. 13 (The @option{-pedantic} option directs GCC to print a warning message if 14 any of these features is used.) To test for the availability of these 15 features in conditional compilation, check for a predefined macro 16 @code{__GNUC__}, which is always defined under GCC@. 17 18 These extensions are available in C and Objective-C@. Most of them are 19 also available in C++. @xref{C++ Extensions,,Extensions to the 20 C++ Language}, for extensions that apply @emph{only} to C++. 21 22 Some features that are in ISO C99 but not C90 or C++ are also, as 23 extensions, accepted by GCC in C90 mode and in C++. 24 25 @menu 26 * Statement Exprs:: Putting statements and declarations inside expressions. 27 * Local Labels:: Labels local to a block. 28 * Labels as Values:: Getting pointers to labels, and computed gotos. 29 * Nested Functions:: Nested function in GNU C. 30 * Nonlocal Gotos:: Nonlocal gotos. 31 * Constructing Calls:: Dispatching a call to another function. 32 * Typeof:: @code{typeof}: referring to the type of an expression. 33 * Conditionals:: Omitting the middle operand of a @samp{?:} expression. 34 * __int128:: 128-bit integers---@code{__int128}. 35 * Long Long:: Double-word integers---@code{long long int}. 36 * Complex:: Data types for complex numbers. 37 * Floating Types:: Additional Floating Types. 38 * Half-Precision:: Half-Precision Floating Point. 39 * Decimal Float:: Decimal Floating Types. 40 * Hex Floats:: Hexadecimal floating-point constants. 41 * Fixed-Point:: Fixed-Point Types. 42 * Named Address Spaces::Named address spaces. 43 * Zero Length:: Zero-length arrays. 44 * Empty Structures:: Structures with no members. 45 * Variable Length:: Arrays whose length is computed at run time. 46 * Variadic Macros:: Macros with a variable number of arguments. 47 * Escaped Newlines:: Slightly looser rules for escaped newlines. 48 * Subscripting:: Any array can be subscripted, even if not an lvalue. 49 * Pointer Arith:: Arithmetic on @code{void}-pointers and function pointers. 50 * Variadic Pointer Args:: Pointer arguments to variadic functions. 51 * Pointers to Arrays:: Pointers to arrays with qualifiers work as expected. 52 * Initializers:: Non-constant initializers. 53 * Compound Literals:: Compound literals give structures, unions 54 or arrays as values. 55 * Designated Inits:: Labeling elements of initializers. 56 * Case Ranges:: `case 1 ... 9' and such. 57 * Cast to Union:: Casting to union type from any member of the union. 58 * Mixed Labels and Declarations:: Mixing declarations, labels and code. 59 * Function Attributes:: Declaring that functions have no side effects, 60 or that they can never return. 61 * Variable Attributes:: Specifying attributes of variables. 62 * Type Attributes:: Specifying attributes of types. 63 * Label Attributes:: Specifying attributes on labels. 64 * Enumerator Attributes:: Specifying attributes on enumerators. 65 * Statement Attributes:: Specifying attributes on statements. 66 * Attribute Syntax:: Formal syntax for attributes. 67 * Function Prototypes:: Prototype declarations and old-style definitions. 68 * C++ Comments:: C++ comments are recognized. 69 * Dollar Signs:: Dollar sign is allowed in identifiers. 70 * Character Escapes:: @samp{\e} stands for the character @key{ESC}. 71 * Alignment:: Determining the alignment of a function, type or variable. 72 * Inline:: Defining inline functions (as fast as macros). 73 * Volatiles:: What constitutes an access to a volatile object. 74 * Using Assembly Language with C:: Instructions and extensions for interfacing C with assembler. 75 * Alternate Keywords:: @code{__const__}, @code{__asm__}, etc., for header files. 76 * Incomplete Enums:: @code{enum foo;}, with details to follow. 77 * Function Names:: Printable strings which are the name of the current 78 function. 79 * Return Address:: Getting the return or frame address of a function. 80 * Vector Extensions:: Using vector instructions through built-in functions. 81 * Offsetof:: Special syntax for implementing @code{offsetof}. 82 * __sync Builtins:: Legacy built-in functions for atomic memory access. 83 * __atomic Builtins:: Atomic built-in functions with memory model. 84 * Integer Overflow Builtins:: Built-in functions to perform arithmetics and 85 arithmetic overflow checking. 86 * x86 specific memory model extensions for transactional memory:: x86 memory models. 87 * Object Size Checking:: Built-in functions for limited buffer overflow 88 checking. 89 * Other Builtins:: Other built-in functions. 90 * Target Builtins:: Built-in functions specific to particular targets. 91 * Target Format Checks:: Format checks specific to particular targets. 92 * Pragmas:: Pragmas accepted by GCC. 93 * Unnamed Fields:: Unnamed struct/union fields within structs/unions. 94 * Thread-Local:: Per-thread variables. 95 * Binary constants:: Binary constants using the @samp{0b} prefix. 96 @end menu 97 98 @node Statement Exprs 99 @section Statements and Declarations in Expressions 100 @cindex statements inside expressions 101 @cindex declarations inside expressions 102 @cindex expressions containing statements 103 @cindex macros, statements in expressions 104 105 @c the above section title wrapped and causes an underfull hbox.. i 106 @c changed it from "within" to "in". --mew 4feb93 107 A compound statement enclosed in parentheses may appear as an expression 108 in GNU C@. This allows you to use loops, switches, and local variables 109 within an expression. 110 111 Recall that a compound statement is a sequence of statements surrounded 112 by braces; in this construct, parentheses go around the braces. For 113 example: 114 115 @smallexample 116 (@{ int y = foo (); int z; 117 if (y > 0) z = y; 118 else z = - y; 119 z; @}) 120 @end smallexample 121 122 @noindent 123 is a valid (though slightly more complex than necessary) expression 124 for the absolute value of @code{foo ()}. 125 126 The last thing in the compound statement should be an expression 127 followed by a semicolon; the value of this subexpression serves as the 128 value of the entire construct. (If you use some other kind of statement 129 last within the braces, the construct has type @code{void}, and thus 130 effectively no value.) 131 132 This feature is especially useful in making macro definitions ``safe'' (so 133 that they evaluate each operand exactly once). For example, the 134 ``maximum'' function is commonly defined as a macro in standard C as 135 follows: 136 137 @smallexample 138 #define max(a,b) ((a) > (b) ? (a) : (b)) 139 @end smallexample 140 141 @noindent 142 @cindex side effects, macro argument 143 But this definition computes either @var{a} or @var{b} twice, with bad 144 results if the operand has side effects. In GNU C, if you know the 145 type of the operands (here taken as @code{int}), you can avoid this 146 problem by defining the macro as follows: 147 148 @smallexample 149 #define maxint(a,b) \ 150 (@{int _a = (a), _b = (b); _a > _b ? _a : _b; @}) 151 @end smallexample 152 153 Note that introducing variable declarations (as we do in @code{maxint}) can 154 cause variable shadowing, so while this example using the @code{max} macro 155 produces correct results: 156 @smallexample 157 int _a = 1, _b = 2, c; 158 c = max (_a, _b); 159 @end smallexample 160 @noindent 161 this example using maxint will not: 162 @smallexample 163 int _a = 1, _b = 2, c; 164 c = maxint (_a, _b); 165 @end smallexample 166 167 This problem may for instance occur when we use this pattern recursively, like 168 so: 169 170 @smallexample 171 #define maxint3(a, b, c) \ 172 (@{int _a = (a), _b = (b), _c = (c); maxint (maxint (_a, _b), _c); @}) 173 @end smallexample 174 175 Embedded statements are not allowed in constant expressions, such as 176 the value of an enumeration constant, the width of a bit-field, or 177 the initial value of a static variable. 178 179 If you don't know the type of the operand, you can still do this, but you 180 must use @code{typeof} or @code{__auto_type} (@pxref{Typeof}). 181 182 In G++, the result value of a statement expression undergoes array and 183 function pointer decay, and is returned by value to the enclosing 184 expression. For instance, if @code{A} is a class, then 185 186 @smallexample 187 A a; 188 189 (@{a;@}).Foo () 190 @end smallexample 191 192 @noindent 193 constructs a temporary @code{A} object to hold the result of the 194 statement expression, and that is used to invoke @code{Foo}. 195 Therefore the @code{this} pointer observed by @code{Foo} is not the 196 address of @code{a}. 197 198 In a statement expression, any temporaries created within a statement 199 are destroyed at that statement's end. This makes statement 200 expressions inside macros slightly different from function calls. In 201 the latter case temporaries introduced during argument evaluation are 202 destroyed at the end of the statement that includes the function 203 call. In the statement expression case they are destroyed during 204 the statement expression. For instance, 205 206 @smallexample 207 #define macro(a) (@{__typeof__(a) b = (a); b + 3; @}) 208 template<typename T> T function(T a) @{ T b = a; return b + 3; @} 209 210 void foo () 211 @{ 212 macro (X ()); 213 function (X ()); 214 @} 215 @end smallexample 216 217 @noindent 218 has different places where temporaries are destroyed. For the 219 @code{macro} case, the temporary @code{X} is destroyed just after 220 the initialization of @code{b}. In the @code{function} case that 221 temporary is destroyed when the function returns. 222 223 These considerations mean that it is probably a bad idea to use 224 statement expressions of this form in header files that are designed to 225 work with C++. (Note that some versions of the GNU C Library contained 226 header files using statement expressions that lead to precisely this 227 bug.) 228 229 Jumping into a statement expression with @code{goto} or using a 230 @code{switch} statement outside the statement expression with a 231 @code{case} or @code{default} label inside the statement expression is 232 not permitted. Jumping into a statement expression with a computed 233 @code{goto} (@pxref{Labels as Values}) has undefined behavior. 234 Jumping out of a statement expression is permitted, but if the 235 statement expression is part of a larger expression then it is 236 unspecified which other subexpressions of that expression have been 237 evaluated except where the language definition requires certain 238 subexpressions to be evaluated before or after the statement 239 expression. A @code{break} or @code{continue} statement inside of 240 a statement expression used in @code{while}, @code{do} or @code{for} 241 loop or @code{switch} statement condition 242 or @code{for} statement init or increment expressions jumps to an 243 outer loop or @code{switch} statement if any (otherwise it is an error), 244 rather than to the loop or @code{switch} statement in whose condition 245 or init or increment expression it appears. 246 In any case, as with a function call, the evaluation of a 247 statement expression is not interleaved with the evaluation of other 248 parts of the containing expression. For example, 249 250 @smallexample 251 foo (), ((@{ bar1 (); goto a; 0; @}) + bar2 ()), baz(); 252 @end smallexample 253 254 @noindent 255 calls @code{foo} and @code{bar1} and does not call @code{baz} but 256 may or may not call @code{bar2}. If @code{bar2} is called, it is 257 called after @code{foo} and before @code{bar1}. 258 259 @node Local Labels 260 @section Locally Declared Labels 261 @cindex local labels 262 @cindex macros, local labels 263 264 GCC allows you to declare @dfn{local labels} in any nested block 265 scope. A local label is just like an ordinary label, but you can 266 only reference it (with a @code{goto} statement, or by taking its 267 address) within the block in which it is declared. 268 269 A local label declaration looks like this: 270 271 @smallexample 272 __label__ @var{label}; 273 @end smallexample 274 275 @noindent 276 or 277 278 @smallexample 279 __label__ @var{label1}, @var{label2}, /* @r{@dots{}} */; 280 @end smallexample 281 282 Local label declarations must come at the beginning of the block, 283 before any ordinary declarations or statements. 284 285 The label declaration defines the label @emph{name}, but does not define 286 the label itself. You must do this in the usual way, with 287 @code{@var{label}:}, within the statements of the statement expression. 288 289 The local label feature is useful for complex macros. If a macro 290 contains nested loops, a @code{goto} can be useful for breaking out of 291 them. However, an ordinary label whose scope is the whole function 292 cannot be used: if the macro can be expanded several times in one 293 function, the label is multiply defined in that function. A 294 local label avoids this problem. For example: 295 296 @smallexample 297 #define SEARCH(value, array, target) \ 298 do @{ \ 299 __label__ found; \ 300 typeof (target) _SEARCH_target = (target); \ 301 typeof (*(array)) *_SEARCH_array = (array); \ 302 int i, j; \ 303 int value; \ 304 for (i = 0; i < max; i++) \ 305 for (j = 0; j < max; j++) \ 306 if (_SEARCH_array[i][j] == _SEARCH_target) \ 307 @{ (value) = i; goto found; @} \ 308 (value) = -1; \ 309 found:; \ 310 @} while (0) 311 @end smallexample 312 313 This could also be written using a statement expression: 314 315 @smallexample 316 #define SEARCH(array, target) \ 317 (@{ \ 318 __label__ found; \ 319 typeof (target) _SEARCH_target = (target); \ 320 typeof (*(array)) *_SEARCH_array = (array); \ 321 int i, j; \ 322 int value; \ 323 for (i = 0; i < max; i++) \ 324 for (j = 0; j < max; j++) \ 325 if (_SEARCH_array[i][j] == _SEARCH_target) \ 326 @{ value = i; goto found; @} \ 327 value = -1; \ 328 found: \ 329 value; \ 330 @}) 331 @end smallexample 332 333 Local label declarations also make the labels they declare visible to 334 nested functions, if there are any. @xref{Nested Functions}, for details. 335 336 @node Labels as Values 337 @section Labels as Values 338 @cindex labels as values 339 @cindex computed gotos 340 @cindex goto with computed label 341 @cindex address of a label 342 343 You can get the address of a label defined in the current function 344 (or a containing function) with the unary operator @samp{&&}. The 345 value has type @code{void *}. This value is a constant and can be used 346 wherever a constant of that type is valid. For example: 347 348 @smallexample 349 void *ptr; 350 /* @r{@dots{}} */ 351 ptr = &&foo; 352 @end smallexample 353 354 To use these values, you need to be able to jump to one. This is done 355 with the computed goto statement@footnote{The analogous feature in 356 Fortran is called an assigned goto, but that name seems inappropriate in 357 C, where one can do more than simply store label addresses in label 358 variables.}, @code{goto *@var{exp};}. For example, 359 360 @smallexample 361 goto *ptr; 362 @end smallexample 363 364 @noindent 365 Any expression of type @code{void *} is allowed. 366 367 One way of using these constants is in initializing a static array that 368 serves as a jump table: 369 370 @smallexample 371 static void *array[] = @{ &&foo, &&bar, &&hack @}; 372 @end smallexample 373 374 @noindent 375 Then you can select a label with indexing, like this: 376 377 @smallexample 378 goto *array[i]; 379 @end smallexample 380 381 @noindent 382 Note that this does not check whether the subscript is in bounds---array 383 indexing in C never does that. 384 385 Such an array of label values serves a purpose much like that of the 386 @code{switch} statement. The @code{switch} statement is cleaner, so 387 use that rather than an array unless the problem does not fit a 388 @code{switch} statement very well. 389 390 Another use of label values is in an interpreter for threaded code. 391 The labels within the interpreter function can be stored in the 392 threaded code for super-fast dispatching. 393 394 You may not use this mechanism to jump to code in a different function. 395 If you do that, totally unpredictable things happen. The best way to 396 avoid this is to store the label address only in automatic variables and 397 never pass it as an argument. 398 399 An alternate way to write the above example is 400 401 @smallexample 402 static const int array[] = @{ &&foo - &&foo, &&bar - &&foo, 403 &&hack - &&foo @}; 404 goto *(&&foo + array[i]); 405 @end smallexample 406 407 @noindent 408 This is more friendly to code living in shared libraries, as it reduces 409 the number of dynamic relocations that are needed, and by consequence, 410 allows the data to be read-only. 411 This alternative with label differences is not supported for the AVR target, 412 please use the first approach for AVR programs. 413 414 The @code{&&foo} expressions for the same label might have different 415 values if the containing function is inlined or cloned. If a program 416 relies on them being always the same, 417 @code{__attribute__((__noinline__,__noclone__))} should be used to 418 prevent inlining and cloning. If @code{&&foo} is used in a static 419 variable initializer, inlining and cloning is forbidden. 420 421 @node Nested Functions 422 @section Nested Functions 423 @cindex nested functions 424 @cindex downward funargs 425 @cindex thunks 426 427 A @dfn{nested function} is a function defined inside another function. 428 Nested functions are supported as an extension in GNU C, but are not 429 supported by GNU C++. 430 431 The nested function's name is local to the block where it is defined. 432 For example, here we define a nested function named @code{square}, and 433 call it twice: 434 435 @smallexample 436 @group 437 foo (double a, double b) 438 @{ 439 double square (double z) @{ return z * z; @} 440 441 return square (a) + square (b); 442 @} 443 @end group 444 @end smallexample 445 446 The nested function can access all the variables of the containing 447 function that are visible at the point of its definition. This is 448 called @dfn{lexical scoping}. For example, here we show a nested 449 function which uses an inherited variable named @code{offset}: 450 451 @smallexample 452 @group 453 bar (int *array, int offset, int size) 454 @{ 455 int access (int *array, int index) 456 @{ return array[index + offset]; @} 457 int i; 458 /* @r{@dots{}} */ 459 for (i = 0; i < size; i++) 460 /* @r{@dots{}} */ access (array, i) /* @r{@dots{}} */ 461 @} 462 @end group 463 @end smallexample 464 465 Nested function definitions are permitted within functions in the places 466 where variable definitions are allowed; that is, in any block, mixed 467 with the other declarations and statements in the block. 468 469 It is possible to call the nested function from outside the scope of its 470 name by storing its address or passing the address to another function: 471 472 @smallexample 473 hack (int *array, int size) 474 @{ 475 void store (int index, int value) 476 @{ array[index] = value; @} 477 478 intermediate (store, size); 479 @} 480 @end smallexample 481 482 Here, the function @code{intermediate} receives the address of 483 @code{store} as an argument. If @code{intermediate} calls @code{store}, 484 the arguments given to @code{store} are used to store into @code{array}. 485 But this technique works only so long as the containing function 486 (@code{hack}, in this example) does not exit. 487 488 If you try to call the nested function through its address after the 489 containing function exits, all hell breaks loose. If you try 490 to call it after a containing scope level exits, and if it refers 491 to some of the variables that are no longer in scope, you may be lucky, 492 but it's not wise to take the risk. If, however, the nested function 493 does not refer to anything that has gone out of scope, you should be 494 safe. 495 496 GCC implements taking the address of a nested function using a technique 497 called @dfn{trampolines}. This technique was described in 498 @cite{Lexical Closures for C++} (Thomas M. Breuel, USENIX 499 C++ Conference Proceedings, October 17-21, 1988). 500 501 A nested function can jump to a label inherited from a containing 502 function, provided the label is explicitly declared in the containing 503 function (@pxref{Local Labels}). Such a jump returns instantly to the 504 containing function, exiting the nested function that did the 505 @code{goto} and any intermediate functions as well. Here is an example: 506 507 @smallexample 508 @group 509 bar (int *array, int offset, int size) 510 @{ 511 __label__ failure; 512 int access (int *array, int index) 513 @{ 514 if (index > size) 515 goto failure; 516 return array[index + offset]; 517 @} 518 int i; 519 /* @r{@dots{}} */ 520 for (i = 0; i < size; i++) 521 /* @r{@dots{}} */ access (array, i) /* @r{@dots{}} */ 522 /* @r{@dots{}} */ 523 return 0; 524 525 /* @r{Control comes here from @code{access} 526 if it detects an error.} */ 527 failure: 528 return -1; 529 @} 530 @end group 531 @end smallexample 532 533 A nested function always has no linkage. Declaring one with 534 @code{extern} or @code{static} is erroneous. If you need to declare the nested function 535 before its definition, use @code{auto} (which is otherwise meaningless 536 for function declarations). 537 538 @smallexample 539 bar (int *array, int offset, int size) 540 @{ 541 __label__ failure; 542 auto int access (int *, int); 543 /* @r{@dots{}} */ 544 int access (int *array, int index) 545 @{ 546 if (index > size) 547 goto failure; 548 return array[index + offset]; 549 @} 550 /* @r{@dots{}} */ 551 @} 552 @end smallexample 553 554 @node Nonlocal Gotos 555 @section Nonlocal Gotos 556 @cindex nonlocal gotos 557 558 GCC provides the built-in functions @code{__builtin_setjmp} and 559 @code{__builtin_longjmp} which are similar to, but not interchangeable 560 with, the C library functions @code{setjmp} and @code{longjmp}. 561 The built-in versions are used internally by GCC's libraries 562 to implement exception handling on some targets. You should use the 563 standard C library functions declared in @code{<setjmp.h>} in user code 564 instead of the builtins. 565 566 The built-in versions of these functions use GCC's normal 567 mechanisms to save and restore registers using the stack on function 568 entry and exit. The jump buffer argument @var{buf} holds only the 569 information needed to restore the stack frame, rather than the entire 570 set of saved register values. 571 572 An important caveat is that GCC arranges to save and restore only 573 those registers known to the specific architecture variant being 574 compiled for. This can make @code{__builtin_setjmp} and 575 @code{__builtin_longjmp} more efficient than their library 576 counterparts in some cases, but it can also cause incorrect and 577 mysterious behavior when mixing with code that uses the full register 578 set. 579 580 You should declare the jump buffer argument @var{buf} to the 581 built-in functions as: 582 583 @smallexample 584 #include <stdint.h> 585 intptr_t @var{buf}[5]; 586 @end smallexample 587 588 @deftypefn {Built-in Function} {int} __builtin_setjmp (intptr_t *@var{buf}) 589 This function saves the current stack context in @var{buf}. 590 @code{__builtin_setjmp} returns 0 when returning directly, 591 and 1 when returning from @code{__builtin_longjmp} using the same 592 @var{buf}. 593 @end deftypefn 594 595 @deftypefn {Built-in Function} {void} __builtin_longjmp (intptr_t *@var{buf}, int @var{val}) 596 This function restores the stack context in @var{buf}, 597 saved by a previous call to @code{__builtin_setjmp}. After 598 @code{__builtin_longjmp} is finished, the program resumes execution as 599 if the matching @code{__builtin_setjmp} returns the value @var{val}, 600 which must be 1. 601 602 Because @code{__builtin_longjmp} depends on the function return 603 mechanism to restore the stack context, it cannot be called 604 from the same function calling @code{__builtin_setjmp} to 605 initialize @var{buf}. It can only be called from a function called 606 (directly or indirectly) from the function calling @code{__builtin_setjmp}. 607 @end deftypefn 608 609 @node Constructing Calls 610 @section Constructing Function Calls 611 @cindex constructing calls 612 @cindex forwarding calls 613 614 Using the built-in functions described below, you can record 615 the arguments a function received, and call another function 616 with the same arguments, without knowing the number or types 617 of the arguments. 618 619 You can also record the return value of that function call, 620 and later return that value, without knowing what data type 621 the function tried to return (as long as your caller expects 622 that data type). 623 624 However, these built-in functions may interact badly with some 625 sophisticated features or other extensions of the language. It 626 is, therefore, not recommended to use them outside very simple 627 functions acting as mere forwarders for their arguments. 628 629 @deftypefn {Built-in Function} {void *} __builtin_apply_args () 630 This built-in function returns a pointer to data 631 describing how to perform a call with the same arguments as are passed 632 to the current function. 633 634 The function saves the arg pointer register, structure value address, 635 and all registers that might be used to pass arguments to a function 636 into a block of memory allocated on the stack. Then it returns the 637 address of that block. 638 @end deftypefn 639 640 @deftypefn {Built-in Function} {void *} __builtin_apply (void (*@var{function})(), void *@var{arguments}, size_t @var{size}) 641 This built-in function invokes @var{function} 642 with a copy of the parameters described by @var{arguments} 643 and @var{size}. 644 645 The value of @var{arguments} should be the value returned by 646 @code{__builtin_apply_args}. The argument @var{size} specifies the size 647 of the stack argument data, in bytes. 648 649 This function returns a pointer to data describing 650 how to return whatever value is returned by @var{function}. The data 651 is saved in a block of memory allocated on the stack. 652 653 It is not always simple to compute the proper value for @var{size}. The 654 value is used by @code{__builtin_apply} to compute the amount of data 655 that should be pushed on the stack and copied from the incoming argument 656 area. 657 @end deftypefn 658 659 @deftypefn {Built-in Function} {void} __builtin_return (void *@var{result}) 660 This built-in function returns the value described by @var{result} from 661 the containing function. You should specify, for @var{result}, a value 662 returned by @code{__builtin_apply}. 663 @end deftypefn 664 665 @deftypefn {Built-in Function} {} __builtin_va_arg_pack () 666 This built-in function represents all anonymous arguments of an inline 667 function. It can be used only in inline functions that are always 668 inlined, never compiled as a separate function, such as those using 669 @code{__attribute__ ((__always_inline__))} or 670 @code{__attribute__ ((__gnu_inline__))} extern inline functions. 671 It must be only passed as last argument to some other function 672 with variable arguments. This is useful for writing small wrapper 673 inlines for variable argument functions, when using preprocessor 674 macros is undesirable. For example: 675 @smallexample 676 extern int myprintf (FILE *f, const char *format, ...); 677 extern inline __attribute__ ((__gnu_inline__)) int 678 myprintf (FILE *f, const char *format, ...) 679 @{ 680 int r = fprintf (f, "myprintf: "); 681 if (r < 0) 682 return r; 683 int s = fprintf (f, format, __builtin_va_arg_pack ()); 684 if (s < 0) 685 return s; 686 return r + s; 687 @} 688 @end smallexample 689 @end deftypefn 690 691 @deftypefn {Built-in Function} {int} __builtin_va_arg_pack_len () 692 This built-in function returns the number of anonymous arguments of 693 an inline function. It can be used only in inline functions that 694 are always inlined, never compiled as a separate function, such 695 as those using @code{__attribute__ ((__always_inline__))} or 696 @code{__attribute__ ((__gnu_inline__))} extern inline functions. 697 For example following does link- or run-time checking of open 698 arguments for optimized code: 699 @smallexample 700 #ifdef __OPTIMIZE__ 701 extern inline __attribute__((__gnu_inline__)) int 702 myopen (const char *path, int oflag, ...) 703 @{ 704 if (__builtin_va_arg_pack_len () > 1) 705 warn_open_too_many_arguments (); 706 707 if (__builtin_constant_p (oflag)) 708 @{ 709 if ((oflag & O_CREAT) != 0 && __builtin_va_arg_pack_len () < 1) 710 @{ 711 warn_open_missing_mode (); 712 return __open_2 (path, oflag); 713 @} 714 return open (path, oflag, __builtin_va_arg_pack ()); 715 @} 716 717 if (__builtin_va_arg_pack_len () < 1) 718 return __open_2 (path, oflag); 719 720 return open (path, oflag, __builtin_va_arg_pack ()); 721 @} 722 #endif 723 @end smallexample 724 @end deftypefn 725 726 @node Typeof 727 @section Referring to a Type with @code{typeof} 728 @findex typeof 729 @findex sizeof 730 @cindex macros, types of arguments 731 732 Another way to refer to the type of an expression is with @code{typeof}. 733 The syntax of using of this keyword looks like @code{sizeof}, but the 734 construct acts semantically like a type name defined with @code{typedef}. 735 736 There are two ways of writing the argument to @code{typeof}: with an 737 expression or with a type. Here is an example with an expression: 738 739 @smallexample 740 typeof (x[0](1)) 741 @end smallexample 742 743 @noindent 744 This assumes that @code{x} is an array of pointers to functions; 745 the type described is that of the values of the functions. 746 747 Here is an example with a typename as the argument: 748 749 @smallexample 750 typeof (int *) 751 @end smallexample 752 753 @noindent 754 Here the type described is that of pointers to @code{int}. 755 756 If you are writing a header file that must work when included in ISO C 757 programs, write @code{__typeof__} instead of @code{typeof}. 758 @xref{Alternate Keywords}. 759 760 A @code{typeof} construct can be used anywhere a typedef name can be 761 used. For example, you can use it in a declaration, in a cast, or inside 762 of @code{sizeof} or @code{typeof}. 763 764 The operand of @code{typeof} is evaluated for its side effects if and 765 only if it is an expression of variably modified type or the name of 766 such a type. 767 768 @code{typeof} is often useful in conjunction with 769 statement expressions (@pxref{Statement Exprs}). 770 Here is how the two together can 771 be used to define a safe ``maximum'' macro which operates on any 772 arithmetic type and evaluates each of its arguments exactly once: 773 774 @smallexample 775 #define max(a,b) \ 776 (@{ typeof (a) _a = (a); \ 777 typeof (b) _b = (b); \ 778 _a > _b ? _a : _b; @}) 779 @end smallexample 780 781 @cindex underscores in variables in macros 782 @cindex @samp{_} in variables in macros 783 @cindex local variables in macros 784 @cindex variables, local, in macros 785 @cindex macros, local variables in 786 787 The reason for using names that start with underscores for the local 788 variables is to avoid conflicts with variable names that occur within the 789 expressions that are substituted for @code{a} and @code{b}. Eventually we 790 hope to design a new form of declaration syntax that allows you to declare 791 variables whose scopes start only after their initializers; this will be a 792 more reliable way to prevent such conflicts. 793 794 @noindent 795 Some more examples of the use of @code{typeof}: 796 797 @itemize @bullet 798 @item 799 This declares @code{y} with the type of what @code{x} points to. 800 801 @smallexample 802 typeof (*x) y; 803 @end smallexample 804 805 @item 806 This declares @code{y} as an array of such values. 807 808 @smallexample 809 typeof (*x) y[4]; 810 @end smallexample 811 812 @item 813 This declares @code{y} as an array of pointers to characters: 814 815 @smallexample 816 typeof (typeof (char *)[4]) y; 817 @end smallexample 818 819 @noindent 820 It is equivalent to the following traditional C declaration: 821 822 @smallexample 823 char *y[4]; 824 @end smallexample 825 826 To see the meaning of the declaration using @code{typeof}, and why it 827 might be a useful way to write, rewrite it with these macros: 828 829 @smallexample 830 #define pointer(T) typeof(T *) 831 #define array(T, N) typeof(T [N]) 832 @end smallexample 833 834 @noindent 835 Now the declaration can be rewritten this way: 836 837 @smallexample 838 array (pointer (char), 4) y; 839 @end smallexample 840 841 @noindent 842 Thus, @code{array (pointer (char), 4)} is the type of arrays of 4 843 pointers to @code{char}. 844 @end itemize 845 846 In GNU C, but not GNU C++, you may also declare the type of a variable 847 as @code{__auto_type}. In that case, the declaration must declare 848 only one variable, whose declarator must just be an identifier, the 849 declaration must be initialized, and the type of the variable is 850 determined by the initializer; the name of the variable is not in 851 scope until after the initializer. (In C++, you should use C++11 852 @code{auto} for this purpose.) Using @code{__auto_type}, the 853 ``maximum'' macro above could be written as: 854 855 @smallexample 856 #define max(a,b) \ 857 (@{ __auto_type _a = (a); \ 858 __auto_type _b = (b); \ 859 _a > _b ? _a : _b; @}) 860 @end smallexample 861 862 Using @code{__auto_type} instead of @code{typeof} has two advantages: 863 864 @itemize @bullet 865 @item Each argument to the macro appears only once in the expansion of 866 the macro. This prevents the size of the macro expansion growing 867 exponentially when calls to such macros are nested inside arguments of 868 such macros. 869 870 @item If the argument to the macro has variably modified type, it is 871 evaluated only once when using @code{__auto_type}, but twice if 872 @code{typeof} is used. 873 @end itemize 874 875 @node Conditionals 876 @section Conditionals with Omitted Operands 877 @cindex conditional expressions, extensions 878 @cindex omitted middle-operands 879 @cindex middle-operands, omitted 880 @cindex extensions, @code{?:} 881 @cindex @code{?:} extensions 882 883 The middle operand in a conditional expression may be omitted. Then 884 if the first operand is nonzero, its value is the value of the conditional 885 expression. 886 887 Therefore, the expression 888 889 @smallexample 890 x ? : y 891 @end smallexample 892 893 @noindent 894 has the value of @code{x} if that is nonzero; otherwise, the value of 895 @code{y}. 896 897 This example is perfectly equivalent to 898 899 @smallexample 900 x ? x : y 901 @end smallexample 902 903 @cindex side effect in @code{?:} 904 @cindex @code{?:} side effect 905 @noindent 906 In this simple case, the ability to omit the middle operand is not 907 especially useful. When it becomes useful is when the first operand does, 908 or may (if it is a macro argument), contain a side effect. Then repeating 909 the operand in the middle would perform the side effect twice. Omitting 910 the middle operand uses the value already computed without the undesirable 911 effects of recomputing it. 912 913 @node __int128 914 @section 128-bit Integers 915 @cindex @code{__int128} data types 916 917 As an extension the integer scalar type @code{__int128} is supported for 918 targets which have an integer mode wide enough to hold 128 bits. 919 Simply write @code{__int128} for a signed 128-bit integer, or 920 @code{unsigned __int128} for an unsigned 128-bit integer. There is no 921 support in GCC for expressing an integer constant of type @code{__int128} 922 for targets with @code{long long} integer less than 128 bits wide. 923 924 @node Long Long 925 @section Double-Word Integers 926 @cindex @code{long long} data types 927 @cindex double-word arithmetic 928 @cindex multiprecision arithmetic 929 @cindex @code{LL} integer suffix 930 @cindex @code{ULL} integer suffix 931 932 ISO C99 and ISO C++11 support data types for integers that are at least 933 64 bits wide, and as an extension GCC supports them in C90 and C++98 modes. 934 Simply write @code{long long int} for a signed integer, or 935 @code{unsigned long long int} for an unsigned integer. To make an 936 integer constant of type @code{long long int}, add the suffix @samp{LL} 937 to the integer. To make an integer constant of type @code{unsigned long 938 long int}, add the suffix @samp{ULL} to the integer. 939 940 You can use these types in arithmetic like any other integer types. 941 Addition, subtraction, and bitwise boolean operations on these types 942 are open-coded on all types of machines. Multiplication is open-coded 943 if the machine supports a fullword-to-doubleword widening multiply 944 instruction. Division and shifts are open-coded only on machines that 945 provide special support. The operations that are not open-coded use 946 special library routines that come with GCC@. 947 948 There may be pitfalls when you use @code{long long} types for function 949 arguments without function prototypes. If a function 950 expects type @code{int} for its argument, and you pass a value of type 951 @code{long long int}, confusion results because the caller and the 952 subroutine disagree about the number of bytes for the argument. 953 Likewise, if the function expects @code{long long int} and you pass 954 @code{int}. The best way to avoid such problems is to use prototypes. 955 956 @node Complex 957 @section Complex Numbers 958 @cindex complex numbers 959 @cindex @code{_Complex} keyword 960 @cindex @code{__complex__} keyword 961 962 ISO C99 supports complex floating data types, and as an extension GCC 963 supports them in C90 mode and in C++. GCC also supports complex integer data 964 types which are not part of ISO C99. You can declare complex types 965 using the keyword @code{_Complex}. As an extension, the older GNU 966 keyword @code{__complex__} is also supported. 967 968 For example, @samp{_Complex double x;} declares @code{x} as a 969 variable whose real part and imaginary part are both of type 970 @code{double}. @samp{_Complex short int y;} declares @code{y} to 971 have real and imaginary parts of type @code{short int}; this is not 972 likely to be useful, but it shows that the set of complex types is 973 complete. 974 975 To write a constant with a complex data type, use the suffix @samp{i} or 976 @samp{j} (either one; they are equivalent). For example, @code{2.5fi} 977 has type @code{_Complex float} and @code{3i} has type 978 @code{_Complex int}. Such a constant always has a pure imaginary 979 value, but you can form any complex value you like by adding one to a 980 real constant. This is a GNU extension; if you have an ISO C99 981 conforming C library (such as the GNU C Library), and want to construct complex 982 constants of floating type, you should include @code{<complex.h>} and 983 use the macros @code{I} or @code{_Complex_I} instead. 984 985 The ISO C++14 library also defines the @samp{i} suffix, so C++14 code 986 that includes the @samp{<complex>} header cannot use @samp{i} for the 987 GNU extension. The @samp{j} suffix still has the GNU meaning. 988 989 GCC can handle both implicit and explicit casts between the @code{_Complex} 990 types and other @code{_Complex} types as casting both the real and imaginary 991 parts to the scalar type. 992 GCC can handle implicit and explicit casts from a scalar type to a @code{_Complex} 993 type and where the imaginary part will be considered zero. 994 The C front-end can handle implicit and explicit casts from a @code{_Complex} type 995 to a scalar type where the imaginary part will be ignored. In C++ code, this cast 996 is considered illformed and G++ will error out. 997 998 GCC provides a built-in function @code{__builtin_complex} will can be used to 999 construct a complex value. 1000 1001 @cindex @code{__real__} keyword 1002 @cindex @code{__imag__} keyword 1003 1004 GCC has a few extensions which can be used to extract the real 1005 and the imaginary part of the complex-valued expression. Note 1006 these expressions are lvalues if the @var{exp} is an lvalue. 1007 These expressions operands have the type of a complex type 1008 which might get prompoted to a complex type from a scalar type. 1009 E.g. @code{__real__ (int)@var{x}} is the same as casting to 1010 @code{_Complex int} before @code{__real__} is done. 1011 1012 @multitable @columnfractions .4 .6 1013 @headitem Expression @tab Description 1014 @item @code{__real__ @var{exp}} 1015 @tab Extract the real part of @var{exp}. 1016 @item @code{__imag__ @var{exp}} 1017 @tab Extract the imaginary part of @var{exp}. 1018 @end multitable 1019 1020 For values of floating point, you should use the ISO C99 1021 functions, declared in @code{<complex.h>} and also provided as 1022 built-in functions by GCC@. 1023 1024 @multitable @columnfractions .4 .2 .2 .2 1025 @headitem Expression @tab float @tab double @tab long double 1026 @item @code{__real__ @var{exp}} 1027 @tab @code{crealf} @tab @code{creal} @tab @code{creall} 1028 @item @code{__imag__ @var{exp}} 1029 @tab @code{cimagf} @tab @code{cimag} @tab @code{cimagl} 1030 @end multitable 1031 1032 @cindex complex conjugation 1033 The operator @samp{~} performs complex conjugation when used on a value 1034 with a complex type. This is a GNU extension; for values of 1035 floating type, you should use the ISO C99 functions @code{conjf}, 1036 @code{conj} and @code{conjl}, declared in @code{<complex.h>} and also 1037 provided as built-in functions by GCC@. Note unlike the @code{__real__} 1038 and @code{__imag__} operators, this operator will not do an implicit cast 1039 to the complex type because the @samp{~} is already a normal operator. 1040 1041 GCC can allocate complex automatic variables in a noncontiguous 1042 fashion; it's even possible for the real part to be in a register while 1043 the imaginary part is on the stack (or vice versa). Only the DWARF 1044 debug info format can represent this, so use of DWARF is recommended. 1045 If you are using the stabs debug info format, GCC describes a noncontiguous 1046 complex variable as if it were two separate variables of noncomplex type. 1047 If the variable's actual name is @code{foo}, the two fictitious 1048 variables are named @code{foo$real} and @code{foo$imag}. You can 1049 examine and set these two fictitious variables with your debugger. 1050 1051 @deftypefn {Built-in Function} @var{type} __builtin_complex (@var{real}, @var{imag}) 1052 1053 The built-in function @code{__builtin_complex} is provided for use in 1054 implementing the ISO C11 macros @code{CMPLXF}, @code{CMPLX} and 1055 @code{CMPLXL}. @var{real} and @var{imag} must have the same type, a 1056 real binary floating-point type, and the result has the corresponding 1057 complex type with real and imaginary parts @var{real} and @var{imag}. 1058 Unlike @samp{@var{real} + I * @var{imag}}, this works even when 1059 infinities, NaNs and negative zeros are involved. 1060 1061 @end deftypefn 1062 1063 @node Floating Types 1064 @section Additional Floating Types 1065 @cindex additional floating types 1066 @cindex @code{_Float@var{n}} data types 1067 @cindex @code{_Float@var{n}x} data types 1068 @cindex @code{__float80} data type 1069 @cindex @code{__float128} data type 1070 @cindex @code{__ibm128} data type 1071 @cindex @code{w} floating point suffix 1072 @cindex @code{q} floating point suffix 1073 @cindex @code{W} floating point suffix 1074 @cindex @code{Q} floating point suffix 1075 1076 ISO/IEC TS 18661-3:2015 defines C support for additional floating 1077 types @code{_Float@var{n}} and @code{_Float@var{n}x}, and GCC supports 1078 these type names; the set of types supported depends on the target 1079 architecture. These types are not supported when compiling C++. 1080 Constants with these types use suffixes @code{f@var{n}} or 1081 @code{F@var{n}} and @code{f@var{n}x} or @code{F@var{n}x}. These type 1082 names can be used together with @code{_Complex} to declare complex 1083 types. 1084 1085 As an extension, GNU C and GNU C++ support additional floating 1086 types, which are not supported by all targets. 1087 @itemize @bullet 1088 @item @code{__float128} is available on i386, x86_64, IA-64, and 1089 hppa HP-UX, as well as on PowerPC GNU/Linux targets that enable 1090 the vector scalar (VSX) instruction set. @code{__float128} supports 1091 the 128-bit floating type. On i386, x86_64, PowerPC, and IA-64 1092 other than HP-UX, @code{__float128} is an alias for @code{_Float128}. 1093 On hppa and IA-64 HP-UX, @code{__float128} is an alias for @code{long 1094 double}. 1095 1096 @item @code{__float80} is available on the i386, x86_64, and IA-64 1097 targets, and supports the 80-bit (@code{XFmode}) floating type. It is 1098 an alias for the type name @code{_Float64x} on these targets. 1099 1100 @item @code{__ibm128} is available on PowerPC targets, and provides 1101 access to the IBM extended double format which is the current format 1102 used for @code{long double}. When @code{long double} transitions to 1103 @code{__float128} on PowerPC in the future, @code{__ibm128} will remain 1104 for use in conversions between the two types. 1105 @end itemize 1106 1107 Support for these additional types includes the arithmetic operators: 1108 add, subtract, multiply, divide; unary arithmetic operators; 1109 relational operators; equality operators; and conversions to and from 1110 integer and other floating types. Use a suffix @samp{w} or @samp{W} 1111 in a literal constant of type @code{__float80} or type 1112 @code{__ibm128}. Use a suffix @samp{q} or @samp{Q} for @code{_float128}. 1113 1114 In order to use @code{_Float128}, @code{__float128}, and @code{__ibm128} 1115 on PowerPC Linux systems, you must use the @option{-mfloat128} option. It is 1116 expected in future versions of GCC that @code{_Float128} and @code{__float128} 1117 will be enabled automatically. 1118 1119 The @code{_Float128} type is supported on all systems where 1120 @code{__float128} is supported or where @code{long double} has the 1121 IEEE binary128 format. The @code{_Float64x} type is supported on all 1122 systems where @code{__float128} is supported. The @code{_Float32} 1123 type is supported on all systems supporting IEEE binary32; the 1124 @code{_Float64} and @code{_Float32x} types are supported on all systems 1125 supporting IEEE binary64. The @code{_Float16} type is supported on AArch64 1126 systems by default, on ARM systems when the IEEE format for 16-bit 1127 floating-point types is selected with @option{-mfp16-format=ieee} and, 1128 for both C and C++, on x86 systems with SSE2 enabled. GCC does not currently 1129 support @code{_Float128x} on any systems. 1130 1131 On the i386, x86_64, IA-64, and HP-UX targets, you can declare complex 1132 types using the corresponding internal complex type, @code{XCmode} for 1133 @code{__float80} type and @code{TCmode} for @code{__float128} type: 1134 1135 @smallexample 1136 typedef _Complex float __attribute__((mode(TC))) _Complex128; 1137 typedef _Complex float __attribute__((mode(XC))) _Complex80; 1138 @end smallexample 1139 1140 On the PowerPC Linux VSX targets, you can declare complex types using 1141 the corresponding internal complex type, @code{KCmode} for 1142 @code{__float128} type and @code{ICmode} for @code{__ibm128} type: 1143 1144 @smallexample 1145 typedef _Complex float __attribute__((mode(KC))) _Complex_float128; 1146 typedef _Complex float __attribute__((mode(IC))) _Complex_ibm128; 1147 @end smallexample 1148 1149 @node Half-Precision 1150 @section Half-Precision Floating Point 1151 @cindex half-precision floating point 1152 @cindex @code{__fp16} data type 1153 @cindex @code{__Float16} data type 1154 1155 On ARM and AArch64 targets, GCC supports half-precision (16-bit) floating 1156 point via the @code{__fp16} type defined in the ARM C Language Extensions. 1157 On ARM systems, you must enable this type explicitly with the 1158 @option{-mfp16-format} command-line option in order to use it. 1159 On x86 targets with SSE2 enabled, GCC supports half-precision (16-bit) 1160 floating point via the @code{_Float16} type. For C++, x86 provides a builtin 1161 type named @code{_Float16} which contains same data format as C. 1162 1163 ARM targets support two incompatible representations for half-precision 1164 floating-point values. You must choose one of the representations and 1165 use it consistently in your program. 1166 1167 Specifying @option{-mfp16-format=ieee} selects the IEEE 754-2008 format. 1168 This format can represent normalized values in the range of @math{2^{-14}} to 65504. 1169 There are 11 bits of significand precision, approximately 3 1170 decimal digits. 1171 1172 Specifying @option{-mfp16-format=alternative} selects the ARM 1173 alternative format. This representation is similar to the IEEE 1174 format, but does not support infinities or NaNs. Instead, the range 1175 of exponents is extended, so that this format can represent normalized 1176 values in the range of @math{2^{-14}} to 131008. 1177 1178 The GCC port for AArch64 only supports the IEEE 754-2008 format, and does 1179 not require use of the @option{-mfp16-format} command-line option. 1180 1181 The @code{__fp16} type may only be used as an argument to intrinsics defined 1182 in @code{<arm_fp16.h>}, or as a storage format. For purposes of 1183 arithmetic and other operations, @code{__fp16} values in C or C++ 1184 expressions are automatically promoted to @code{float}. 1185 1186 The ARM target provides hardware support for conversions between 1187 @code{__fp16} and @code{float} values 1188 as an extension to VFP and NEON (Advanced SIMD), and from ARMv8-A provides 1189 hardware support for conversions between @code{__fp16} and @code{double} 1190 values. GCC generates code using these hardware instructions if you 1191 compile with options to select an FPU that provides them; 1192 for example, @option{-mfpu=neon-fp16 -mfloat-abi=softfp}, 1193 in addition to the @option{-mfp16-format} option to select 1194 a half-precision format. 1195 1196 Language-level support for the @code{__fp16} data type is 1197 independent of whether GCC generates code using hardware floating-point 1198 instructions. In cases where hardware support is not specified, GCC 1199 implements conversions between @code{__fp16} and other types as library 1200 calls. 1201 1202 It is recommended that portable code use the @code{_Float16} type defined 1203 by ISO/IEC TS 18661-3:2015. @xref{Floating Types}. 1204 1205 On x86 targets with SSE2 enabled, without @option{-mavx512fp16}, 1206 all operations will be emulated by software emulation and the @code{float} 1207 instructions. The default behavior for @code{FLT_EVAL_METHOD} is to keep the 1208 intermediate result of the operation as 32-bit precision. This may lead to 1209 inconsistent behavior between software emulation and AVX512-FP16 instructions. 1210 Using @option{-fexcess-precision=16} will force round back after each operation. 1211 1212 Using @option{-mavx512fp16} will generate AVX512-FP16 instructions instead of 1213 software emulation. The default behavior of @code{FLT_EVAL_METHOD} is to round 1214 after each operation. The same is true with @option{-fexcess-precision=standard} 1215 and @option{-mfpmath=sse}. If there is no @option{-mfpmath=sse}, 1216 @option{-fexcess-precision=standard} alone does the same thing as before, 1217 It is useful for code that does not have @code{_Float16} and runs on the x87 1218 FPU. 1219 1220 @node Decimal Float 1221 @section Decimal Floating Types 1222 @cindex decimal floating types 1223 @cindex @code{_Decimal32} data type 1224 @cindex @code{_Decimal64} data type 1225 @cindex @code{_Decimal128} data type 1226 @cindex @code{df} integer suffix 1227 @cindex @code{dd} integer suffix 1228 @cindex @code{dl} integer suffix 1229 @cindex @code{DF} integer suffix 1230 @cindex @code{DD} integer suffix 1231 @cindex @code{DL} integer suffix 1232 1233 As an extension, GNU C supports decimal floating types as 1234 defined in the N1312 draft of ISO/IEC WDTR24732. Support for decimal 1235 floating types in GCC will evolve as the draft technical report changes. 1236 Calling conventions for any target might also change. Not all targets 1237 support decimal floating types. 1238 1239 The decimal floating types are @code{_Decimal32}, @code{_Decimal64}, and 1240 @code{_Decimal128}. They use a radix of ten, unlike the floating types 1241 @code{float}, @code{double}, and @code{long double} whose radix is not 1242 specified by the C standard but is usually two. 1243 1244 Support for decimal floating types includes the arithmetic operators 1245 add, subtract, multiply, divide; unary arithmetic operators; 1246 relational operators; equality operators; and conversions to and from 1247 integer and other floating types. Use a suffix @samp{df} or 1248 @samp{DF} in a literal constant of type @code{_Decimal32}, @samp{dd} 1249 or @samp{DD} for @code{_Decimal64}, and @samp{dl} or @samp{DL} for 1250 @code{_Decimal128}. 1251 1252 GCC support of decimal float as specified by the draft technical report 1253 is incomplete: 1254 1255 @itemize @bullet 1256 @item 1257 When the value of a decimal floating type cannot be represented in the 1258 integer type to which it is being converted, the result is undefined 1259 rather than the result value specified by the draft technical report. 1260 1261 @item 1262 GCC does not provide the C library functionality associated with 1263 @file{math.h}, @file{fenv.h}, @file{stdio.h}, @file{stdlib.h}, and 1264 @file{wchar.h}, which must come from a separate C library implementation. 1265 Because of this the GNU C compiler does not define macro 1266 @code{__STDC_DEC_FP__} to indicate that the implementation conforms to 1267 the technical report. 1268 @end itemize 1269 1270 Types @code{_Decimal32}, @code{_Decimal64}, and @code{_Decimal128} 1271 are supported by the DWARF debug information format. 1272 1273 @node Hex Floats 1274 @section Hex Floats 1275 @cindex hex floats 1276 1277 ISO C99 and ISO C++17 support floating-point numbers written not only in 1278 the usual decimal notation, such as @code{1.55e1}, but also numbers such as 1279 @code{0x1.fp3} written in hexadecimal format. As a GNU extension, GCC 1280 supports this in C90 mode (except in some cases when strictly 1281 conforming) and in C++98, C++11 and C++14 modes. In that format the 1282 @samp{0x} hex introducer and the @samp{p} or @samp{P} exponent field are 1283 mandatory. The exponent is a decimal number that indicates the power of 1284 2 by which the significant part is multiplied. Thus @samp{0x1.f} is 1285 @tex 1286 $1 {15\over16}$, 1287 @end tex 1288 @ifnottex 1289 1 15/16, 1290 @end ifnottex 1291 @samp{p3} multiplies it by 8, and the value of @code{0x1.fp3} 1292 is the same as @code{1.55e1}. 1293 1294 Unlike for floating-point numbers in the decimal notation the exponent 1295 is always required in the hexadecimal notation. Otherwise the compiler 1296 would not be able to resolve the ambiguity of, e.g., @code{0x1.f}. This 1297 could mean @code{1.0f} or @code{1.9375} since @samp{f} is also the 1298 extension for floating-point constants of type @code{float}. 1299 1300 @node Fixed-Point 1301 @section Fixed-Point Types 1302 @cindex fixed-point types 1303 @cindex @code{_Fract} data type 1304 @cindex @code{_Accum} data type 1305 @cindex @code{_Sat} data type 1306 @cindex @code{hr} fixed-suffix 1307 @cindex @code{r} fixed-suffix 1308 @cindex @code{lr} fixed-suffix 1309 @cindex @code{llr} fixed-suffix 1310 @cindex @code{uhr} fixed-suffix 1311 @cindex @code{ur} fixed-suffix 1312 @cindex @code{ulr} fixed-suffix 1313 @cindex @code{ullr} fixed-suffix 1314 @cindex @code{hk} fixed-suffix 1315 @cindex @code{k} fixed-suffix 1316 @cindex @code{lk} fixed-suffix 1317 @cindex @code{llk} fixed-suffix 1318 @cindex @code{uhk} fixed-suffix 1319 @cindex @code{uk} fixed-suffix 1320 @cindex @code{ulk} fixed-suffix 1321 @cindex @code{ullk} fixed-suffix 1322 @cindex @code{HR} fixed-suffix 1323 @cindex @code{R} fixed-suffix 1324 @cindex @code{LR} fixed-suffix 1325 @cindex @code{LLR} fixed-suffix 1326 @cindex @code{UHR} fixed-suffix 1327 @cindex @code{UR} fixed-suffix 1328 @cindex @code{ULR} fixed-suffix 1329 @cindex @code{ULLR} fixed-suffix 1330 @cindex @code{HK} fixed-suffix 1331 @cindex @code{K} fixed-suffix 1332 @cindex @code{LK} fixed-suffix 1333 @cindex @code{LLK} fixed-suffix 1334 @cindex @code{UHK} fixed-suffix 1335 @cindex @code{UK} fixed-suffix 1336 @cindex @code{ULK} fixed-suffix 1337 @cindex @code{ULLK} fixed-suffix 1338 1339 As an extension, GNU C supports fixed-point types as 1340 defined in the N1169 draft of ISO/IEC DTR 18037. Support for fixed-point 1341 types in GCC will evolve as the draft technical report changes. 1342 Calling conventions for any target might also change. Not all targets 1343 support fixed-point types. 1344 1345 The fixed-point types are 1346 @code{short _Fract}, 1347 @code{_Fract}, 1348 @code{long _Fract}, 1349 @code{long long _Fract}, 1350 @code{unsigned short _Fract}, 1351 @code{unsigned _Fract}, 1352 @code{unsigned long _Fract}, 1353 @code{unsigned long long _Fract}, 1354 @code{_Sat short _Fract}, 1355 @code{_Sat _Fract}, 1356 @code{_Sat long _Fract}, 1357 @code{_Sat long long _Fract}, 1358 @code{_Sat unsigned short _Fract}, 1359 @code{_Sat unsigned _Fract}, 1360 @code{_Sat unsigned long _Fract}, 1361 @code{_Sat unsigned long long _Fract}, 1362 @code{short _Accum}, 1363 @code{_Accum}, 1364 @code{long _Accum}, 1365 @code{long long _Accum}, 1366 @code{unsigned short _Accum}, 1367 @code{unsigned _Accum}, 1368 @code{unsigned long _Accum}, 1369 @code{unsigned long long _Accum}, 1370 @code{_Sat short _Accum}, 1371 @code{_Sat _Accum}, 1372 @code{_Sat long _Accum}, 1373 @code{_Sat long long _Accum}, 1374 @code{_Sat unsigned short _Accum}, 1375 @code{_Sat unsigned _Accum}, 1376 @code{_Sat unsigned long _Accum}, 1377 @code{_Sat unsigned long long _Accum}. 1378 1379 Fixed-point data values contain fractional and optional integral parts. 1380 The format of fixed-point data varies and depends on the target machine. 1381 1382 Support for fixed-point types includes: 1383 @itemize @bullet 1384 @item 1385 prefix and postfix increment and decrement operators (@code{++}, @code{--}) 1386 @item 1387 unary arithmetic operators (@code{+}, @code{-}, @code{!}) 1388 @item 1389 binary arithmetic operators (@code{+}, @code{-}, @code{*}, @code{/}) 1390 @item 1391 binary shift operators (@code{<<}, @code{>>}) 1392 @item 1393 relational operators (@code{<}, @code{<=}, @code{>=}, @code{>}) 1394 @item 1395 equality operators (@code{==}, @code{!=}) 1396 @item 1397 assignment operators (@code{+=}, @code{-=}, @code{*=}, @code{/=}, 1398 @code{<<=}, @code{>>=}) 1399 @item 1400 conversions to and from integer, floating-point, or fixed-point types 1401 @end itemize 1402 1403 Use a suffix in a fixed-point literal constant: 1404 @itemize 1405 @item @samp{hr} or @samp{HR} for @code{short _Fract} and 1406 @code{_Sat short _Fract} 1407 @item @samp{r} or @samp{R} for @code{_Fract} and @code{_Sat _Fract} 1408 @item @samp{lr} or @samp{LR} for @code{long _Fract} and 1409 @code{_Sat long _Fract} 1410 @item @samp{llr} or @samp{LLR} for @code{long long _Fract} and 1411 @code{_Sat long long _Fract} 1412 @item @samp{uhr} or @samp{UHR} for @code{unsigned short _Fract} and 1413 @code{_Sat unsigned short _Fract} 1414 @item @samp{ur} or @samp{UR} for @code{unsigned _Fract} and 1415 @code{_Sat unsigned _Fract} 1416 @item @samp{ulr} or @samp{ULR} for @code{unsigned long _Fract} and 1417 @code{_Sat unsigned long _Fract} 1418 @item @samp{ullr} or @samp{ULLR} for @code{unsigned long long _Fract} 1419 and @code{_Sat unsigned long long _Fract} 1420 @item @samp{hk} or @samp{HK} for @code{short _Accum} and 1421 @code{_Sat short _Accum} 1422 @item @samp{k} or @samp{K} for @code{_Accum} and @code{_Sat _Accum} 1423 @item @samp{lk} or @samp{LK} for @code{long _Accum} and 1424 @code{_Sat long _Accum} 1425 @item @samp{llk} or @samp{LLK} for @code{long long _Accum} and 1426 @code{_Sat long long _Accum} 1427 @item @samp{uhk} or @samp{UHK} for @code{unsigned short _Accum} and 1428 @code{_Sat unsigned short _Accum} 1429 @item @samp{uk} or @samp{UK} for @code{unsigned _Accum} and 1430 @code{_Sat unsigned _Accum} 1431 @item @samp{ulk} or @samp{ULK} for @code{unsigned long _Accum} and 1432 @code{_Sat unsigned long _Accum} 1433 @item @samp{ullk} or @samp{ULLK} for @code{unsigned long long _Accum} 1434 and @code{_Sat unsigned long long _Accum} 1435 @end itemize 1436 1437 GCC support of fixed-point types as specified by the draft technical report 1438 is incomplete: 1439 1440 @itemize @bullet 1441 @item 1442 Pragmas to control overflow and rounding behaviors are not implemented. 1443 @end itemize 1444 1445 Fixed-point types are supported by the DWARF debug information format. 1446 1447 @node Named Address Spaces 1448 @section Named Address Spaces 1449 @cindex Named Address Spaces 1450 1451 As an extension, GNU C supports named address spaces as 1452 defined in the N1275 draft of ISO/IEC DTR 18037. Support for named 1453 address spaces in GCC will evolve as the draft technical report 1454 changes. Calling conventions for any target might also change. At 1455 present, only the AVR, M32C, PRU, RL78, and x86 targets support 1456 address spaces other than the generic address space. 1457 1458 Address space identifiers may be used exactly like any other C type 1459 qualifier (e.g., @code{const} or @code{volatile}). See the N1275 1460 document for more details. 1461 1462 @anchor{AVR Named Address Spaces} 1463 @subsection AVR Named Address Spaces 1464 1465 On the AVR target, there are several address spaces that can be used 1466 in order to put read-only data into the flash memory and access that 1467 data by means of the special instructions @code{LPM} or @code{ELPM} 1468 needed to read from flash. 1469 1470 Devices belonging to @code{avrtiny} and @code{avrxmega3} can access 1471 flash memory by means of @code{LD*} instructions because the flash 1472 memory is mapped into the RAM address space. There is @emph{no need} 1473 for language extensions like @code{__flash} or attribute 1474 @ref{AVR Variable Attributes,,@code{progmem}}. 1475 The default linker description files for these devices cater for that 1476 feature and @code{.rodata} stays in flash: The compiler just generates 1477 @code{LD*} instructions, and the linker script adds core specific 1478 offsets to all @code{.rodata} symbols: @code{0x4000} in the case of 1479 @code{avrtiny} and @code{0x8000} in the case of @code{avrxmega3}. 1480 See @ref{AVR Options} for a list of respective devices. 1481 1482 For devices not in @code{avrtiny} or @code{avrxmega3}, 1483 any data including read-only data is located in RAM (the generic 1484 address space) because flash memory is not visible in the RAM address 1485 space. In order to locate read-only data in flash memory @emph{and} 1486 to generate the right instructions to access this data without 1487 using (inline) assembler code, special address spaces are needed. 1488 1489 @table @code 1490 @item __flash 1491 @cindex @code{__flash} AVR Named Address Spaces 1492 The @code{__flash} qualifier locates data in the 1493 @code{.progmem.data} section. Data is read using the @code{LPM} 1494 instruction. Pointers to this address space are 16 bits wide. 1495 1496 @item __flash1 1497 @itemx __flash2 1498 @itemx __flash3 1499 @itemx __flash4 1500 @itemx __flash5 1501 @cindex @code{__flash1} AVR Named Address Spaces 1502 @cindex @code{__flash2} AVR Named Address Spaces 1503 @cindex @code{__flash3} AVR Named Address Spaces 1504 @cindex @code{__flash4} AVR Named Address Spaces 1505 @cindex @code{__flash5} AVR Named Address Spaces 1506 These are 16-bit address spaces locating data in section 1507 @code{.progmem@var{N}.data} where @var{N} refers to 1508 address space @code{__flash@var{N}}. 1509 The compiler sets the @code{RAMPZ} segment register appropriately 1510 before reading data by means of the @code{ELPM} instruction. 1511 1512 @item __memx 1513 @cindex @code{__memx} AVR Named Address Spaces 1514 This is a 24-bit address space that linearizes flash and RAM: 1515 If the high bit of the address is set, data is read from 1516 RAM using the lower two bytes as RAM address. 1517 If the high bit of the address is clear, data is read from flash 1518 with @code{RAMPZ} set according to the high byte of the address. 1519 @xref{AVR Built-in Functions,,@code{__builtin_avr_flash_segment}}. 1520 1521 Objects in this address space are located in @code{.progmemx.data}. 1522 @end table 1523 1524 @b{Example} 1525 1526 @smallexample 1527 char my_read (const __flash char ** p) 1528 @{ 1529 /* p is a pointer to RAM that points to a pointer to flash. 1530 The first indirection of p reads that flash pointer 1531 from RAM and the second indirection reads a char from this 1532 flash address. */ 1533 1534 return **p; 1535 @} 1536 1537 /* Locate array[] in flash memory */ 1538 const __flash int array[] = @{ 3, 5, 7, 11, 13, 17, 19 @}; 1539 1540 int i = 1; 1541 1542 int main (void) 1543 @{ 1544 /* Return 17 by reading from flash memory */ 1545 return array[array[i]]; 1546 @} 1547 @end smallexample 1548 1549 @noindent 1550 For each named address space supported by avr-gcc there is an equally 1551 named but uppercase built-in macro defined. 1552 The purpose is to facilitate testing if respective address space 1553 support is available or not: 1554 1555 @smallexample 1556 #ifdef __FLASH 1557 const __flash int var = 1; 1558 1559 int read_var (void) 1560 @{ 1561 return var; 1562 @} 1563 #else 1564 #include <avr/pgmspace.h> /* From AVR-LibC */ 1565 1566 const int var PROGMEM = 1; 1567 1568 int read_var (void) 1569 @{ 1570 return (int) pgm_read_word (&var); 1571 @} 1572 #endif /* __FLASH */ 1573 @end smallexample 1574 1575 @noindent 1576 Notice that attribute @ref{AVR Variable Attributes,,@code{progmem}} 1577 locates data in flash but 1578 accesses to these data read from generic address space, i.e.@: 1579 from RAM, 1580 so that you need special accessors like @code{pgm_read_byte} 1581 from @w{@uref{http://nongnu.org/avr-libc/user-manual/,AVR-LibC}} 1582 together with attribute @code{progmem}. 1583 1584 @noindent 1585 @b{Limitations and caveats} 1586 1587 @itemize 1588 @item 1589 Reading across the 64@tie{}KiB section boundary of 1590 the @code{__flash} or @code{__flash@var{N}} address spaces 1591 shows undefined behavior. The only address space that 1592 supports reading across the 64@tie{}KiB flash segment boundaries is 1593 @code{__memx}. 1594 1595 @item 1596 If you use one of the @code{__flash@var{N}} address spaces 1597 you must arrange your linker script to locate the 1598 @code{.progmem@var{N}.data} sections according to your needs. 1599 1600 @item 1601 Any data or pointers to the non-generic address spaces must 1602 be qualified as @code{const}, i.e.@: as read-only data. 1603 This still applies if the data in one of these address 1604 spaces like software version number or calibration lookup table are intended to 1605 be changed after load time by, say, a boot loader. In this case 1606 the right qualification is @code{const} @code{volatile} so that the compiler 1607 must not optimize away known values or insert them 1608 as immediates into operands of instructions. 1609 1610 @item 1611 The following code initializes a variable @code{pfoo} 1612 located in static storage with a 24-bit address: 1613 @smallexample 1614 extern const __memx char foo; 1615 const __memx void *pfoo = &foo; 1616 @end smallexample 1617 1618 @item 1619 On the reduced Tiny devices like ATtiny40, no address spaces are supported. 1620 Just use vanilla C / C++ code without overhead as outlined above. 1621 Attribute @code{progmem} is supported but works differently, 1622 see @ref{AVR Variable Attributes}. 1623 1624 @end itemize 1625 1626 @subsection M32C Named Address Spaces 1627 @cindex @code{__far} M32C Named Address Spaces 1628 1629 On the M32C target, with the R8C and M16C CPU variants, variables 1630 qualified with @code{__far} are accessed using 32-bit addresses in 1631 order to access memory beyond the first 64@tie{}Ki bytes. If 1632 @code{__far} is used with the M32CM or M32C CPU variants, it has no 1633 effect. 1634 1635 @subsection PRU Named Address Spaces 1636 @cindex @code{__regio_symbol} PRU Named Address Spaces 1637 1638 On the PRU target, variables qualified with @code{__regio_symbol} are 1639 aliases used to access the special I/O CPU registers. They must be 1640 declared as @code{extern} because such variables will not be allocated in 1641 any data memory. They must also be marked as @code{volatile}, and can 1642 only be 32-bit integer types. The only names those variables can have 1643 are @code{__R30} and @code{__R31}, representing respectively the 1644 @code{R30} and @code{R31} special I/O CPU registers. Hence the following 1645 example is the only valid usage of @code{__regio_symbol}: 1646 1647 @smallexample 1648 extern volatile __regio_symbol uint32_t __R30; 1649 extern volatile __regio_symbol uint32_t __R31; 1650 @end smallexample 1651 1652 @subsection RL78 Named Address Spaces 1653 @cindex @code{__far} RL78 Named Address Spaces 1654 1655 On the RL78 target, variables qualified with @code{__far} are accessed 1656 with 32-bit pointers (20-bit addresses) rather than the default 16-bit 1657 addresses. Non-far variables are assumed to appear in the topmost 1658 64@tie{}KiB of the address space. 1659 1660 @subsection x86 Named Address Spaces 1661 @cindex x86 named address spaces 1662 1663 On the x86 target, variables may be declared as being relative 1664 to the @code{%fs} or @code{%gs} segments. 1665 1666 @table @code 1667 @item __seg_fs 1668 @itemx __seg_gs 1669 @cindex @code{__seg_fs} x86 named address space 1670 @cindex @code{__seg_gs} x86 named address space 1671 The object is accessed with the respective segment override prefix. 1672 1673 The respective segment base must be set via some method specific to 1674 the operating system. Rather than require an expensive system call 1675 to retrieve the segment base, these address spaces are not considered 1676 to be subspaces of the generic (flat) address space. This means that 1677 explicit casts are required to convert pointers between these address 1678 spaces and the generic address space. In practice the application 1679 should cast to @code{uintptr_t} and apply the segment base offset 1680 that it installed previously. 1681 1682 The preprocessor symbols @code{__SEG_FS} and @code{__SEG_GS} are 1683 defined when these address spaces are supported. 1684 @end table 1685 1686 @node Zero Length 1687 @section Arrays of Length Zero 1688 @cindex arrays of length zero 1689 @cindex zero-length arrays 1690 @cindex length-zero arrays 1691 @cindex flexible array members 1692 1693 Declaring zero-length arrays is allowed in GNU C as an extension. 1694 A zero-length array can be useful as the last element of a structure 1695 that is really a header for a variable-length object: 1696 1697 @smallexample 1698 struct line @{ 1699 int length; 1700 char contents[0]; 1701 @}; 1702 1703 struct line *thisline = (struct line *) 1704 malloc (sizeof (struct line) + this_length); 1705 thisline->length = this_length; 1706 @end smallexample 1707 1708 Although the size of a zero-length array is zero, an array member of 1709 this kind may increase the size of the enclosing type as a result of tail 1710 padding. The offset of a zero-length array member from the beginning 1711 of the enclosing structure is the same as the offset of an array with 1712 one or more elements of the same type. The alignment of a zero-length 1713 array is the same as the alignment of its elements. 1714 1715 Declaring zero-length arrays in other contexts, including as interior 1716 members of structure objects or as non-member objects, is discouraged. 1717 Accessing elements of zero-length arrays declared in such contexts is 1718 undefined and may be diagnosed. 1719 1720 In the absence of the zero-length array extension, in ISO C90 1721 the @code{contents} array in the example above would typically be declared 1722 to have a single element. Unlike a zero-length array which only contributes 1723 to the size of the enclosing structure for the purposes of alignment, 1724 a one-element array always occupies at least as much space as a single 1725 object of the type. Although using one-element arrays this way is 1726 discouraged, GCC handles accesses to trailing one-element array members 1727 analogously to zero-length arrays. 1728 1729 The preferred mechanism to declare variable-length types like 1730 @code{struct line} above is the ISO C99 @dfn{flexible array member}, 1731 with slightly different syntax and semantics: 1732 1733 @itemize @bullet 1734 @item 1735 Flexible array members are written as @code{contents[]} without 1736 the @code{0}. 1737 1738 @item 1739 Flexible array members have incomplete type, and so the @code{sizeof} 1740 operator may not be applied. As a quirk of the original implementation 1741 of zero-length arrays, @code{sizeof} evaluates to zero. 1742 1743 @item 1744 Flexible array members may only appear as the last member of a 1745 @code{struct} that is otherwise non-empty. 1746 1747 @item 1748 A structure containing a flexible array member, or a union containing 1749 such a structure (possibly recursively), may not be a member of a 1750 structure or an element of an array. (However, these uses are 1751 permitted by GCC as extensions.) 1752 @end itemize 1753 1754 Non-empty initialization of zero-length 1755 arrays is treated like any case where there are more initializer 1756 elements than the array holds, in that a suitable warning about ``excess 1757 elements in array'' is given, and the excess elements (all of them, in 1758 this case) are ignored. 1759 1760 GCC allows static initialization of flexible array members. 1761 This is equivalent to defining a new structure containing the original 1762 structure followed by an array of sufficient size to contain the data. 1763 E.g.@: in the following, @code{f1} is constructed as if it were declared 1764 like @code{f2}. 1765 1766 @smallexample 1767 struct f1 @{ 1768 int x; int y[]; 1769 @} f1 = @{ 1, @{ 2, 3, 4 @} @}; 1770 1771 struct f2 @{ 1772 struct f1 f1; int data[3]; 1773 @} f2 = @{ @{ 1 @}, @{ 2, 3, 4 @} @}; 1774 @end smallexample 1775 1776 @noindent 1777 The convenience of this extension is that @code{f1} has the desired 1778 type, eliminating the need to consistently refer to @code{f2.f1}. 1779 1780 This has symmetry with normal static arrays, in that an array of 1781 unknown size is also written with @code{[]}. 1782 1783 Of course, this extension only makes sense if the extra data comes at 1784 the end of a top-level object, as otherwise we would be overwriting 1785 data at subsequent offsets. To avoid undue complication and confusion 1786 with initialization of deeply nested arrays, we simply disallow any 1787 non-empty initialization except when the structure is the top-level 1788 object. For example: 1789 1790 @smallexample 1791 struct foo @{ int x; int y[]; @}; 1792 struct bar @{ struct foo z; @}; 1793 1794 struct foo a = @{ 1, @{ 2, 3, 4 @} @}; // @r{Valid.} 1795 struct bar b = @{ @{ 1, @{ 2, 3, 4 @} @} @}; // @r{Invalid.} 1796 struct bar c = @{ @{ 1, @{ @} @} @}; // @r{Valid.} 1797 struct foo d[1] = @{ @{ 1, @{ 2, 3, 4 @} @} @}; // @r{Invalid.} 1798 @end smallexample 1799 1800 @node Empty Structures 1801 @section Structures with No Members 1802 @cindex empty structures 1803 @cindex zero-size structures 1804 1805 GCC permits a C structure to have no members: 1806 1807 @smallexample 1808 struct empty @{ 1809 @}; 1810 @end smallexample 1811 1812 The structure has size zero. In C++, empty structures are part 1813 of the language. G++ treats empty structures as if they had a single 1814 member of type @code{char}. 1815 1816 @node Variable Length 1817 @section Arrays of Variable Length 1818 @cindex variable-length arrays 1819 @cindex arrays of variable length 1820 @cindex VLAs 1821 1822 Variable-length automatic arrays are allowed in ISO C99, and as an 1823 extension GCC accepts them in C90 mode and in C++. These arrays are 1824 declared like any other automatic arrays, but with a length that is not 1825 a constant expression. The storage is allocated at the point of 1826 declaration and deallocated when the block scope containing the declaration 1827 exits. For 1828 example: 1829 1830 @smallexample 1831 FILE * 1832 concat_fopen (char *s1, char *s2, char *mode) 1833 @{ 1834 char str[strlen (s1) + strlen (s2) + 1]; 1835 strcpy (str, s1); 1836 strcat (str, s2); 1837 return fopen (str, mode); 1838 @} 1839 @end smallexample 1840 1841 @cindex scope of a variable length array 1842 @cindex variable-length array scope 1843 @cindex deallocating variable length arrays 1844 Jumping or breaking out of the scope of the array name deallocates the 1845 storage. Jumping into the scope is not allowed; you get an error 1846 message for it. 1847 1848 @cindex variable-length array in a structure 1849 As an extension, GCC accepts variable-length arrays as a member of 1850 a structure or a union. For example: 1851 1852 @smallexample 1853 void 1854 foo (int n) 1855 @{ 1856 struct S @{ int x[n]; @}; 1857 @} 1858 @end smallexample 1859 1860 @cindex @code{alloca} vs variable-length arrays 1861 You can use the function @code{alloca} to get an effect much like 1862 variable-length arrays. The function @code{alloca} is available in 1863 many other C implementations (but not in all). On the other hand, 1864 variable-length arrays are more elegant. 1865 1866 There are other differences between these two methods. Space allocated 1867 with @code{alloca} exists until the containing @emph{function} returns. 1868 The space for a variable-length array is deallocated as soon as the array 1869 name's scope ends, unless you also use @code{alloca} in this scope. 1870 1871 You can also use variable-length arrays as arguments to functions: 1872 1873 @smallexample 1874 struct entry 1875 tester (int len, char data[len][len]) 1876 @{ 1877 /* @r{@dots{}} */ 1878 @} 1879 @end smallexample 1880 1881 The length of an array is computed once when the storage is allocated 1882 and is remembered for the scope of the array in case you access it with 1883 @code{sizeof}. 1884 1885 If you want to pass the array first and the length afterward, you can 1886 use a forward declaration in the parameter list---another GNU extension. 1887 1888 @smallexample 1889 struct entry 1890 tester (int len; char data[len][len], int len) 1891 @{ 1892 /* @r{@dots{}} */ 1893 @} 1894 @end smallexample 1895 1896 @cindex parameter forward declaration 1897 The @samp{int len} before the semicolon is a @dfn{parameter forward 1898 declaration}, and it serves the purpose of making the name @code{len} 1899 known when the declaration of @code{data} is parsed. 1900 1901 You can write any number of such parameter forward declarations in the 1902 parameter list. They can be separated by commas or semicolons, but the 1903 last one must end with a semicolon, which is followed by the ``real'' 1904 parameter declarations. Each forward declaration must match a ``real'' 1905 declaration in parameter name and data type. ISO C99 does not support 1906 parameter forward declarations. 1907 1908 @node Variadic Macros 1909 @section Macros with a Variable Number of Arguments. 1910 @cindex variable number of arguments 1911 @cindex macro with variable arguments 1912 @cindex rest argument (in macro) 1913 @cindex variadic macros 1914 1915 In the ISO C standard of 1999, a macro can be declared to accept a 1916 variable number of arguments much as a function can. The syntax for 1917 defining the macro is similar to that of a function. Here is an 1918 example: 1919 1920 @smallexample 1921 #define debug(format, ...) fprintf (stderr, format, __VA_ARGS__) 1922 @end smallexample 1923 1924 @noindent 1925 Here @samp{@dots{}} is a @dfn{variable argument}. In the invocation of 1926 such a macro, it represents the zero or more tokens until the closing 1927 parenthesis that ends the invocation, including any commas. This set of 1928 tokens replaces the identifier @code{__VA_ARGS__} in the macro body 1929 wherever it appears. See the CPP manual for more information. 1930 1931 GCC has long supported variadic macros, and used a different syntax that 1932 allowed you to give a name to the variable arguments just like any other 1933 argument. Here is an example: 1934 1935 @smallexample 1936 #define debug(format, args...) fprintf (stderr, format, args) 1937 @end smallexample 1938 1939 @noindent 1940 This is in all ways equivalent to the ISO C example above, but arguably 1941 more readable and descriptive. 1942 1943 GNU CPP has two further variadic macro extensions, and permits them to 1944 be used with either of the above forms of macro definition. 1945 1946 In standard C, you are not allowed to leave the variable argument out 1947 entirely; but you are allowed to pass an empty argument. For example, 1948 this invocation is invalid in ISO C, because there is no comma after 1949 the string: 1950 1951 @smallexample 1952 debug ("A message") 1953 @end smallexample 1954 1955 GNU CPP permits you to completely omit the variable arguments in this 1956 way. In the above examples, the compiler would complain, though since 1957 the expansion of the macro still has the extra comma after the format 1958 string. 1959 1960 To help solve this problem, CPP behaves specially for variable arguments 1961 used with the token paste operator, @samp{##}. If instead you write 1962 1963 @smallexample 1964 #define debug(format, ...) fprintf (stderr, format, ## __VA_ARGS__) 1965 @end smallexample 1966 1967 @noindent 1968 and if the variable arguments are omitted or empty, the @samp{##} 1969 operator causes the preprocessor to remove the comma before it. If you 1970 do provide some variable arguments in your macro invocation, GNU CPP 1971 does not complain about the paste operation and instead places the 1972 variable arguments after the comma. Just like any other pasted macro 1973 argument, these arguments are not macro expanded. 1974 1975 @node Escaped Newlines 1976 @section Slightly Looser Rules for Escaped Newlines 1977 @cindex escaped newlines 1978 @cindex newlines (escaped) 1979 1980 The preprocessor treatment of escaped newlines is more relaxed 1981 than that specified by the C90 standard, which requires the newline 1982 to immediately follow a backslash. 1983 GCC's implementation allows whitespace in the form 1984 of spaces, horizontal and vertical tabs, and form feeds between the 1985 backslash and the subsequent newline. The preprocessor issues a 1986 warning, but treats it as a valid escaped newline and combines the two 1987 lines to form a single logical line. This works within comments and 1988 tokens, as well as between tokens. Comments are @emph{not} treated as 1989 whitespace for the purposes of this relaxation, since they have not 1990 yet been replaced with spaces. 1991 1992 @node Subscripting 1993 @section Non-Lvalue Arrays May Have Subscripts 1994 @cindex subscripting 1995 @cindex arrays, non-lvalue 1996 1997 @cindex subscripting and function values 1998 In ISO C99, arrays that are not lvalues still decay to pointers, and 1999 may be subscripted, although they may not be modified or used after 2000 the next sequence point and the unary @samp{&} operator may not be 2001 applied to them. As an extension, GNU C allows such arrays to be 2002 subscripted in C90 mode, though otherwise they do not decay to 2003 pointers outside C99 mode. For example, 2004 this is valid in GNU C though not valid in C90: 2005 2006 @smallexample 2007 @group 2008 struct foo @{int a[4];@}; 2009 2010 struct foo f(); 2011 2012 bar (int index) 2013 @{ 2014 return f().a[index]; 2015 @} 2016 @end group 2017 @end smallexample 2018 2019 @node Pointer Arith 2020 @section Arithmetic on @code{void}- and Function-Pointers 2021 @cindex void pointers, arithmetic 2022 @cindex void, size of pointer to 2023 @cindex function pointers, arithmetic 2024 @cindex function, size of pointer to 2025 2026 In GNU C, addition and subtraction operations are supported on pointers to 2027 @code{void} and on pointers to functions. This is done by treating the 2028 size of a @code{void} or of a function as 1. 2029 2030 A consequence of this is that @code{sizeof} is also allowed on @code{void} 2031 and on function types, and returns 1. 2032 2033 @opindex Wpointer-arith 2034 The option @option{-Wpointer-arith} requests a warning if these extensions 2035 are used. 2036 2037 @node Variadic Pointer Args 2038 @section Pointer Arguments in Variadic Functions 2039 @cindex pointer arguments in variadic functions 2040 @cindex variadic functions, pointer arguments 2041 2042 Standard C requires that pointer types used with @code{va_arg} in 2043 functions with variable argument lists either must be compatible with 2044 that of the actual argument, or that one type must be a pointer to 2045 @code{void} and the other a pointer to a character type. GNU C 2046 implements the POSIX XSI extension that additionally permits the use 2047 of @code{va_arg} with a pointer type to receive arguments of any other 2048 pointer type. 2049 2050 In particular, in GNU C @samp{va_arg (ap, void *)} can safely be used 2051 to consume an argument of any pointer type. 2052 2053 @node Pointers to Arrays 2054 @section Pointers to Arrays with Qualifiers Work as Expected 2055 @cindex pointers to arrays 2056 @cindex const qualifier 2057 2058 In GNU C, pointers to arrays with qualifiers work similar to pointers 2059 to other qualified types. For example, a value of type @code{int (*)[5]} 2060 can be used to initialize a variable of type @code{const int (*)[5]}. 2061 These types are incompatible in ISO C because the @code{const} qualifier 2062 is formally attached to the element type of the array and not the 2063 array itself. 2064 2065 @smallexample 2066 extern void 2067 transpose (int N, int M, double out[M][N], const double in[N][M]); 2068 double x[3][2]; 2069 double y[2][3]; 2070 @r{@dots{}} 2071 transpose(3, 2, y, x); 2072 @end smallexample 2073 2074 @node Initializers 2075 @section Non-Constant Initializers 2076 @cindex initializers, non-constant 2077 @cindex non-constant initializers 2078 2079 As in standard C++ and ISO C99, the elements of an aggregate initializer for an 2080 automatic variable are not required to be constant expressions in GNU C@. 2081 Here is an example of an initializer with run-time varying elements: 2082 2083 @smallexample 2084 foo (float f, float g) 2085 @{ 2086 float beat_freqs[2] = @{ f-g, f+g @}; 2087 /* @r{@dots{}} */ 2088 @} 2089 @end smallexample 2090 2091 @node Compound Literals 2092 @section Compound Literals 2093 @cindex constructor expressions 2094 @cindex initializations in expressions 2095 @cindex structures, constructor expression 2096 @cindex expressions, constructor 2097 @cindex compound literals 2098 @c The GNU C name for what C99 calls compound literals was "constructor expressions". 2099 2100 A compound literal looks like a cast of a brace-enclosed aggregate 2101 initializer list. Its value is an object of the type specified in 2102 the cast, containing the elements specified in the initializer. 2103 Unlike the result of a cast, a compound literal is an lvalue. ISO 2104 C99 and later support compound literals. As an extension, GCC 2105 supports compound literals also in C90 mode and in C++, although 2106 as explained below, the C++ semantics are somewhat different. 2107 2108 Usually, the specified type of a compound literal is a structure. Assume 2109 that @code{struct foo} and @code{structure} are declared as shown: 2110 2111 @smallexample 2112 struct foo @{int a; char b[2];@} structure; 2113 @end smallexample 2114 2115 @noindent 2116 Here is an example of constructing a @code{struct foo} with a compound literal: 2117 2118 @smallexample 2119 structure = ((struct foo) @{x + y, 'a', 0@}); 2120 @end smallexample 2121 2122 @noindent 2123 This is equivalent to writing the following: 2124 2125 @smallexample 2126 @{ 2127 struct foo temp = @{x + y, 'a', 0@}; 2128 structure = temp; 2129 @} 2130 @end smallexample 2131 2132 You can also construct an array, though this is dangerous in C++, as 2133 explained below. If all the elements of the compound literal are 2134 (made up of) simple constant expressions suitable for use in 2135 initializers of objects of static storage duration, then the compound 2136 literal can be coerced to a pointer to its first element and used in 2137 such an initializer, as shown here: 2138 2139 @smallexample 2140 char **foo = (char *[]) @{ "x", "y", "z" @}; 2141 @end smallexample 2142 2143 Compound literals for scalar types and union types are also allowed. In 2144 the following example the variable @code{i} is initialized to the value 2145 @code{2}, the result of incrementing the unnamed object created by 2146 the compound literal. 2147 2148 @smallexample 2149 int i = ++(int) @{ 1 @}; 2150 @end smallexample 2151 2152 As a GNU extension, GCC allows initialization of objects with static storage 2153 duration by compound literals (which is not possible in ISO C99 because 2154 the initializer is not a constant). 2155 It is handled as if the object were initialized only with the brace-enclosed 2156 list if the types of the compound literal and the object match. 2157 The elements of the compound literal must be constant. 2158 If the object being initialized has array type of unknown size, the size is 2159 determined by the size of the compound literal. 2160 2161 @smallexample 2162 static struct foo x = (struct foo) @{1, 'a', 'b'@}; 2163 static int y[] = (int []) @{1, 2, 3@}; 2164 static int z[] = (int [3]) @{1@}; 2165 @end smallexample 2166 2167 @noindent 2168 The above lines are equivalent to the following: 2169 @smallexample 2170 static struct foo x = @{1, 'a', 'b'@}; 2171 static int y[] = @{1, 2, 3@}; 2172 static int z[] = @{1, 0, 0@}; 2173 @end smallexample 2174 2175 In C, a compound literal designates an unnamed object with static or 2176 automatic storage duration. In C++, a compound literal designates a 2177 temporary object that only lives until the end of its full-expression. 2178 As a result, well-defined C code that takes the address of a subobject 2179 of a compound literal can be undefined in C++, so G++ rejects 2180 the conversion of a temporary array to a pointer. For instance, if 2181 the array compound literal example above appeared inside a function, 2182 any subsequent use of @code{foo} in C++ would have undefined behavior 2183 because the lifetime of the array ends after the declaration of @code{foo}. 2184 2185 As an optimization, G++ sometimes gives array compound literals longer 2186 lifetimes: when the array either appears outside a function or has 2187 a @code{const}-qualified type. If @code{foo} and its initializer had 2188 elements of type @code{char *const} rather than @code{char *}, or if 2189 @code{foo} were a global variable, the array would have static storage 2190 duration. But it is probably safest just to avoid the use of array 2191 compound literals in C++ code. 2192 2193 @node Designated Inits 2194 @section Designated Initializers 2195 @cindex initializers with labeled elements 2196 @cindex labeled elements in initializers 2197 @cindex case labels in initializers 2198 @cindex designated initializers 2199 2200 Standard C90 requires the elements of an initializer to appear in a fixed 2201 order, the same as the order of the elements in the array or structure 2202 being initialized. 2203 2204 In ISO C99 you can give the elements in any order, specifying the array 2205 indices or structure field names they apply to, and GNU C allows this as 2206 an extension in C90 mode as well. This extension is not 2207 implemented in GNU C++. 2208 2209 To specify an array index, write 2210 @samp{[@var{index}] =} before the element value. For example, 2211 2212 @smallexample 2213 int a[6] = @{ [4] = 29, [2] = 15 @}; 2214 @end smallexample 2215 2216 @noindent 2217 is equivalent to 2218 2219 @smallexample 2220 int a[6] = @{ 0, 0, 15, 0, 29, 0 @}; 2221 @end smallexample 2222 2223 @noindent 2224 The index values must be constant expressions, even if the array being 2225 initialized is automatic. 2226 2227 An alternative syntax for this that has been obsolete since GCC 2.5 but 2228 GCC still accepts is to write @samp{[@var{index}]} before the element 2229 value, with no @samp{=}. 2230 2231 To initialize a range of elements to the same value, write 2232 @samp{[@var{first} ... @var{last}] = @var{value}}. This is a GNU 2233 extension. For example, 2234 2235 @smallexample 2236 int widths[] = @{ [0 ... 9] = 1, [10 ... 99] = 2, [100] = 3 @}; 2237 @end smallexample 2238 2239 @noindent 2240 If the value in it has side effects, the side effects happen only once, 2241 not for each initialized field by the range initializer. 2242 2243 @noindent 2244 Note that the length of the array is the highest value specified 2245 plus one. 2246 2247 In a structure initializer, specify the name of a field to initialize 2248 with @samp{.@var{fieldname} =} before the element value. For example, 2249 given the following structure, 2250 2251 @smallexample 2252 struct point @{ int x, y; @}; 2253 @end smallexample 2254 2255 @noindent 2256 the following initialization 2257 2258 @smallexample 2259 struct point p = @{ .y = yvalue, .x = xvalue @}; 2260 @end smallexample 2261 2262 @noindent 2263 is equivalent to 2264 2265 @smallexample 2266 struct point p = @{ xvalue, yvalue @}; 2267 @end smallexample 2268 2269 Another syntax that has the same meaning, obsolete since GCC 2.5, is 2270 @samp{@var{fieldname}:}, as shown here: 2271 2272 @smallexample 2273 struct point p = @{ y: yvalue, x: xvalue @}; 2274 @end smallexample 2275 2276 Omitted fields are implicitly initialized the same as for objects 2277 that have static storage duration. 2278 2279 @cindex designators 2280 The @samp{[@var{index}]} or @samp{.@var{fieldname}} is known as a 2281 @dfn{designator}. You can also use a designator (or the obsolete colon 2282 syntax) when initializing a union, to specify which element of the union 2283 should be used. For example, 2284 2285 @smallexample 2286 union foo @{ int i; double d; @}; 2287 2288 union foo f = @{ .d = 4 @}; 2289 @end smallexample 2290 2291 @noindent 2292 converts 4 to a @code{double} to store it in the union using 2293 the second element. By contrast, casting 4 to type @code{union foo} 2294 stores it into the union as the integer @code{i}, since it is 2295 an integer. @xref{Cast to Union}. 2296 2297 You can combine this technique of naming elements with ordinary C 2298 initialization of successive elements. Each initializer element that 2299 does not have a designator applies to the next consecutive element of the 2300 array or structure. For example, 2301 2302 @smallexample 2303 int a[6] = @{ [1] = v1, v2, [4] = v4 @}; 2304 @end smallexample 2305 2306 @noindent 2307 is equivalent to 2308 2309 @smallexample 2310 int a[6] = @{ 0, v1, v2, 0, v4, 0 @}; 2311 @end smallexample 2312 2313 Labeling the elements of an array initializer is especially useful 2314 when the indices are characters or belong to an @code{enum} type. 2315 For example: 2316 2317 @smallexample 2318 int whitespace[256] 2319 = @{ [' '] = 1, ['\t'] = 1, ['\h'] = 1, 2320 ['\f'] = 1, ['\n'] = 1, ['\r'] = 1 @}; 2321 @end smallexample 2322 2323 @cindex designator lists 2324 You can also write a series of @samp{.@var{fieldname}} and 2325 @samp{[@var{index}]} designators before an @samp{=} to specify a 2326 nested subobject to initialize; the list is taken relative to the 2327 subobject corresponding to the closest surrounding brace pair. For 2328 example, with the @samp{struct point} declaration above: 2329 2330 @smallexample 2331 struct point ptarray[10] = @{ [2].y = yv2, [2].x = xv2, [0].x = xv0 @}; 2332 @end smallexample 2333 2334 If the same field is initialized multiple times, or overlapping 2335 fields of a union are initialized, the value from the last 2336 initialization is used. When a field of a union is itself a structure, 2337 the entire structure from the last field initialized is used. If any previous 2338 initializer has side effect, it is unspecified whether the side effect 2339 happens or not. Currently, GCC discards the side-effecting 2340 initializer expressions and issues a warning. 2341 2342 @node Case Ranges 2343 @section Case Ranges 2344 @cindex case ranges 2345 @cindex ranges in case statements 2346 2347 You can specify a range of consecutive values in a single @code{case} label, 2348 like this: 2349 2350 @smallexample 2351 case @var{low} ... @var{high}: 2352 @end smallexample 2353 2354 @noindent 2355 This has the same effect as the proper number of individual @code{case} 2356 labels, one for each integer value from @var{low} to @var{high}, inclusive. 2357 2358 This feature is especially useful for ranges of ASCII character codes: 2359 2360 @smallexample 2361 case 'A' ... 'Z': 2362 @end smallexample 2363 2364 @strong{Be careful:} Write spaces around the @code{...}, for otherwise 2365 it may be parsed wrong when you use it with integer values. For example, 2366 write this: 2367 2368 @smallexample 2369 case 1 ... 5: 2370 @end smallexample 2371 2372 @noindent 2373 rather than this: 2374 2375 @smallexample 2376 case 1...5: 2377 @end smallexample 2378 2379 @node Cast to Union 2380 @section Cast to a Union Type 2381 @cindex cast to a union 2382 @cindex union, casting to a 2383 2384 A cast to a union type is a C extension not available in C++. It looks 2385 just like ordinary casts with the constraint that the type specified is 2386 a union type. You can specify the type either with the @code{union} 2387 keyword or with a @code{typedef} name that refers to a union. The result 2388 of a cast to a union is a temporary rvalue of the union type with a member 2389 whose type matches that of the operand initialized to the value of 2390 the operand. The effect of a cast to a union is similar to a compound 2391 literal except that it yields an rvalue like standard casts do. 2392 @xref{Compound Literals}. 2393 2394 Expressions that may be cast to the union type are those whose type matches 2395 at least one of the members of the union. Thus, given the following union 2396 and variables: 2397 2398 @smallexample 2399 union foo @{ int i; double d; @}; 2400 int x; 2401 double y; 2402 union foo z; 2403 @end smallexample 2404 2405 @noindent 2406 both @code{x} and @code{y} can be cast to type @code{union foo} and 2407 the following assignments 2408 @smallexample 2409 z = (union foo) x; 2410 z = (union foo) y; 2411 @end smallexample 2412 are shorthand equivalents of these 2413 @smallexample 2414 z = (union foo) @{ .i = x @}; 2415 z = (union foo) @{ .d = y @}; 2416 @end smallexample 2417 2418 However, @code{(union foo) FLT_MAX;} is not a valid cast because the union 2419 has no member of type @code{float}. 2420 2421 Using the cast as the right-hand side of an assignment to a variable of 2422 union type is equivalent to storing in a member of the union with 2423 the same type 2424 2425 @smallexample 2426 union foo u; 2427 /* @r{@dots{}} */ 2428 u = (union foo) x @equiv{} u.i = x 2429 u = (union foo) y @equiv{} u.d = y 2430 @end smallexample 2431 2432 You can also use the union cast as a function argument: 2433 2434 @smallexample 2435 void hack (union foo); 2436 /* @r{@dots{}} */ 2437 hack ((union foo) x); 2438 @end smallexample 2439 2440 @node Mixed Labels and Declarations 2441 @section Mixed Declarations, Labels and Code 2442 @cindex mixed declarations and code 2443 @cindex declarations, mixed with code 2444 @cindex code, mixed with declarations 2445 2446 ISO C99 and ISO C++ allow declarations and code to be freely mixed 2447 within compound statements. ISO C2X allows labels to be 2448 placed before declarations and at the end of a compound statement. 2449 As an extension, GNU C also allows all this in C90 mode. For example, 2450 you could do: 2451 2452 @smallexample 2453 int i; 2454 /* @r{@dots{}} */ 2455 i++; 2456 int j = i + 2; 2457 @end smallexample 2458 2459 Each identifier is visible from where it is declared until the end of 2460 the enclosing block. 2461 2462 @node Function Attributes 2463 @section Declaring Attributes of Functions 2464 @cindex function attributes 2465 @cindex declaring attributes of functions 2466 @cindex @code{volatile} applied to function 2467 @cindex @code{const} applied to function 2468 2469 In GNU C and C++, you can use function attributes to specify certain 2470 function properties that may help the compiler optimize calls or 2471 check code more carefully for correctness. For example, you 2472 can use attributes to specify that a function never returns 2473 (@code{noreturn}), returns a value depending only on the values of 2474 its arguments (@code{const}), or has @code{printf}-style arguments 2475 (@code{format}). 2476 2477 You can also use attributes to control memory placement, code 2478 generation options or call/return conventions within the function 2479 being annotated. Many of these attributes are target-specific. For 2480 example, many targets support attributes for defining interrupt 2481 handler functions, which typically must follow special register usage 2482 and return conventions. Such attributes are described in the subsection 2483 for each target. However, a considerable number of attributes are 2484 supported by most, if not all targets. Those are described in 2485 the @ref{Common Function Attributes} section. 2486 2487 Function attributes are introduced by the @code{__attribute__} keyword 2488 in the declaration of a function, followed by an attribute specification 2489 enclosed in double parentheses. You can specify multiple attributes in 2490 a declaration by separating them by commas within the double parentheses 2491 or by immediately following one attribute specification with another. 2492 @xref{Attribute Syntax}, for the exact rules on attribute syntax and 2493 placement. Compatible attribute specifications on distinct declarations 2494 of the same function are merged. An attribute specification that is not 2495 compatible with attributes already applied to a declaration of the same 2496 function is ignored with a warning. 2497 2498 Some function attributes take one or more arguments that refer to 2499 the function's parameters by their positions within the function parameter 2500 list. Such attribute arguments are referred to as @dfn{positional arguments}. 2501 Unless specified otherwise, positional arguments that specify properties 2502 of parameters with pointer types can also specify the same properties of 2503 the implicit C++ @code{this} argument in non-static member functions, and 2504 of parameters of reference to a pointer type. For ordinary functions, 2505 position one refers to the first parameter on the list. In C++ non-static 2506 member functions, position one refers to the implicit @code{this} pointer. 2507 The same restrictions and effects apply to function attributes used with 2508 ordinary functions or C++ member functions. 2509 2510 GCC also supports attributes on 2511 variable declarations (@pxref{Variable Attributes}), 2512 labels (@pxref{Label Attributes}), 2513 enumerators (@pxref{Enumerator Attributes}), 2514 statements (@pxref{Statement Attributes}), 2515 types (@pxref{Type Attributes}), 2516 and on field declarations (for @code{tainted_args}). 2517 2518 There is some overlap between the purposes of attributes and pragmas 2519 (@pxref{Pragmas,,Pragmas Accepted by GCC}). It has been 2520 found convenient to use @code{__attribute__} to achieve a natural 2521 attachment of attributes to their corresponding declarations, whereas 2522 @code{#pragma} is of use for compatibility with other compilers 2523 or constructs that do not naturally form part of the grammar. 2524 2525 In addition to the attributes documented here, 2526 GCC plugins may provide their own attributes. 2527 2528 @menu 2529 * Common Function Attributes:: 2530 * AArch64 Function Attributes:: 2531 * AMD GCN Function Attributes:: 2532 * ARC Function Attributes:: 2533 * ARM Function Attributes:: 2534 * AVR Function Attributes:: 2535 * Blackfin Function Attributes:: 2536 * BPF Function Attributes:: 2537 * CR16 Function Attributes:: 2538 * C-SKY Function Attributes:: 2539 * Epiphany Function Attributes:: 2540 * H8/300 Function Attributes:: 2541 * IA-64 Function Attributes:: 2542 * M32C Function Attributes:: 2543 * M32R/D Function Attributes:: 2544 * m68k Function Attributes:: 2545 * MCORE Function Attributes:: 2546 * MeP Function Attributes:: 2547 * MicroBlaze Function Attributes:: 2548 * Microsoft Windows Function Attributes:: 2549 * MIPS Function Attributes:: 2550 * MSP430 Function Attributes:: 2551 * NDS32 Function Attributes:: 2552 * Nios II Function Attributes:: 2553 * Nvidia PTX Function Attributes:: 2554 * PowerPC Function Attributes:: 2555 * RISC-V Function Attributes:: 2556 * RL78 Function Attributes:: 2557 * RX Function Attributes:: 2558 * S/390 Function Attributes:: 2559 * SH Function Attributes:: 2560 * Symbian OS Function Attributes:: 2561 * V850 Function Attributes:: 2562 * Visium Function Attributes:: 2563 * x86 Function Attributes:: 2564 * Xstormy16 Function Attributes:: 2565 @end menu 2566 2567 @node Common Function Attributes 2568 @subsection Common Function Attributes 2569 2570 The following attributes are supported on most targets. 2571 2572 @table @code 2573 @c Keep this table alphabetized by attribute name. Treat _ as space. 2574 2575 @item access (@var{access-mode}, @var{ref-index}) 2576 @itemx access (@var{access-mode}, @var{ref-index}, @var{size-index}) 2577 2578 The @code{access} attribute enables the detection of invalid or unsafe 2579 accesses by functions to which they apply or their callers, as well as 2580 write-only accesses to objects that are never read from. Such accesses 2581 may be diagnosed by warnings such as @option{-Wstringop-overflow}, 2582 @option{-Wuninitialized}, @option{-Wunused}, and others. 2583 2584 The @code{access} attribute specifies that a function to whose by-reference 2585 arguments the attribute applies accesses the referenced object according to 2586 @var{access-mode}. The @var{access-mode} argument is required and must be 2587 one of four names: @code{read_only}, @code{read_write}, @code{write_only}, 2588 or @code{none}. The remaining two are positional arguments. 2589 2590 The required @var{ref-index} positional argument denotes a function 2591 argument of pointer (or in C++, reference) type that is subject to 2592 the access. The same pointer argument can be referenced by at most one 2593 distinct @code{access} attribute. 2594 2595 The optional @var{size-index} positional argument denotes a function 2596 argument of integer type that specifies the maximum size of the access. 2597 The size is the number of elements of the type referenced by @var{ref-index}, 2598 or the number of bytes when the pointer type is @code{void*}. When no 2599 @var{size-index} argument is specified, the pointer argument must be either 2600 null or point to a space that is suitably aligned and large for at least one 2601 object of the referenced type (this implies that a past-the-end pointer is 2602 not a valid argument). The actual size of the access may be less but it 2603 must not be more. 2604 2605 The @code{read_only} access mode specifies that the pointer to which it 2606 applies is used to read the referenced object but not write to it. Unless 2607 the argument specifying the size of the access denoted by @var{size-index} 2608 is zero, the referenced object must be initialized. The mode implies 2609 a stronger guarantee than the @code{const} qualifier which, when cast away 2610 from a pointer, does not prevent the pointed-to object from being modified. 2611 Examples of the use of the @code{read_only} access mode is the argument to 2612 the @code{puts} function, or the second and third arguments to 2613 the @code{memcpy} function. 2614 2615 @smallexample 2616 __attribute__ ((access (read_only, 1))) int puts (const char*); 2617 __attribute__ ((access (read_only, 2, 3))) void* memcpy (void*, const void*, size_t); 2618 @end smallexample 2619 2620 The @code{read_write} access mode applies to arguments of pointer types 2621 without the @code{const} qualifier. It specifies that the pointer to which 2622 it applies is used to both read and write the referenced object. Unless 2623 the argument specifying the size of the access denoted by @var{size-index} 2624 is zero, the object referenced by the pointer must be initialized. An example 2625 of the use of the @code{read_write} access mode is the first argument to 2626 the @code{strcat} function. 2627 2628 @smallexample 2629 __attribute__ ((access (read_write, 1), access (read_only, 2))) char* strcat (char*, const char*); 2630 @end smallexample 2631 2632 The @code{write_only} access mode applies to arguments of pointer types 2633 without the @code{const} qualifier. It specifies that the pointer to which 2634 it applies is used to write to the referenced object but not read from it. 2635 The object referenced by the pointer need not be initialized. An example 2636 of the use of the @code{write_only} access mode is the first argument to 2637 the @code{strcpy} function, or the first two arguments to the @code{fgets} 2638 function. 2639 2640 @smallexample 2641 __attribute__ ((access (write_only, 1), access (read_only, 2))) char* strcpy (char*, const char*); 2642 __attribute__ ((access (write_only, 1, 2), access (read_write, 3))) int fgets (char*, int, FILE*); 2643 @end smallexample 2644 2645 The access mode @code{none} specifies that the pointer to which it applies 2646 is not used to access the referenced object at all. Unless the pointer is 2647 null the pointed-to object must exist and have at least the size as denoted 2648 by the @var{size-index} argument. When the optional @var{size-index} 2649 argument is omitted for an argument of @code{void*} type the actual pointer 2650 agument is ignored. The referenced object need not be initialized. 2651 The mode is intended to be used as a means to help validate the expected 2652 object size, for example in functions that call @code{__builtin_object_size}. 2653 @xref{Object Size Checking}. 2654 2655 Note that the @code{access} attribute merely specifies how an object 2656 referenced by the pointer argument can be accessed; it does not imply that 2657 an access @strong{will} happen. Also, the @code{access} attribute does not 2658 imply the attribute @code{nonnull}; it may be appropriate to add both attributes 2659 at the declaration of a function that unconditionally manipulates a buffer via 2660 a pointer argument. See the @code{nonnull} attribute for more information and 2661 caveats. 2662 2663 @item alias ("@var{target}") 2664 @cindex @code{alias} function attribute 2665 The @code{alias} attribute causes the declaration to be emitted as an alias 2666 for another symbol, which must have been previously declared with the same 2667 type, and for variables, also the same size and alignment. Declaring an alias 2668 with a different type than the target is undefined and may be diagnosed. As 2669 an example, the following declarations: 2670 2671 @smallexample 2672 void __f () @{ /* @r{Do something.} */; @} 2673 void f () __attribute__ ((weak, alias ("__f"))); 2674 @end smallexample 2675 2676 @noindent 2677 define @samp{f} to be a weak alias for @samp{__f}. In C++, the mangled name 2678 for the target must be used. It is an error if @samp{__f} is not defined in 2679 the same translation unit. 2680 2681 This attribute requires assembler and object file support, 2682 and may not be available on all targets. 2683 2684 @item aligned 2685 @itemx aligned (@var{alignment}) 2686 @cindex @code{aligned} function attribute 2687 The @code{aligned} attribute specifies a minimum alignment for 2688 the first instruction of the function, measured in bytes. When specified, 2689 @var{alignment} must be an integer constant power of 2. Specifying no 2690 @var{alignment} argument implies the ideal alignment for the target. 2691 The @code{__alignof__} operator can be used to determine what that is 2692 (@pxref{Alignment}). The attribute has no effect when a definition for 2693 the function is not provided in the same translation unit. 2694 2695 The attribute cannot be used to decrease the alignment of a function 2696 previously declared with a more restrictive alignment; only to increase 2697 it. Attempts to do otherwise are diagnosed. Some targets specify 2698 a minimum default alignment for functions that is greater than 1. On 2699 such targets, specifying a less restrictive alignment is silently ignored. 2700 Using the attribute overrides the effect of the @option{-falign-functions} 2701 (@pxref{Optimize Options}) option for this function. 2702 2703 Note that the effectiveness of @code{aligned} attributes may be 2704 limited by inherent limitations in the system linker 2705 and/or object file format. On some systems, the 2706 linker is only able to arrange for functions to be aligned up to a 2707 certain maximum alignment. (For some linkers, the maximum supported 2708 alignment may be very very small.) See your linker documentation for 2709 further information. 2710 2711 The @code{aligned} attribute can also be used for variables and fields 2712 (@pxref{Variable Attributes}.) 2713 2714 @item alloc_align (@var{position}) 2715 @cindex @code{alloc_align} function attribute 2716 The @code{alloc_align} attribute may be applied to a function that 2717 returns a pointer and takes at least one argument of an integer or 2718 enumerated type. 2719 It indicates that the returned pointer is aligned on a boundary given 2720 by the function argument at @var{position}. Meaningful alignments are 2721 powers of 2 greater than one. GCC uses this information to improve 2722 pointer alignment analysis. 2723 2724 The function parameter denoting the allocated alignment is specified by 2725 one constant integer argument whose number is the argument of the attribute. 2726 Argument numbering starts at one. 2727 2728 For instance, 2729 2730 @smallexample 2731 void* my_memalign (size_t, size_t) __attribute__ ((alloc_align (1))); 2732 @end smallexample 2733 2734 @noindent 2735 declares that @code{my_memalign} returns memory with minimum alignment 2736 given by parameter 1. 2737 2738 @item alloc_size (@var{position}) 2739 @itemx alloc_size (@var{position-1}, @var{position-2}) 2740 @cindex @code{alloc_size} function attribute 2741 The @code{alloc_size} attribute may be applied to a function that 2742 returns a pointer and takes at least one argument of an integer or 2743 enumerated type. 2744 It indicates that the returned pointer points to memory whose size is 2745 given by the function argument at @var{position-1}, or by the product 2746 of the arguments at @var{position-1} and @var{position-2}. Meaningful 2747 sizes are positive values less than @code{PTRDIFF_MAX}. GCC uses this 2748 information to improve the results of @code{__builtin_object_size}. 2749 2750 The function parameter(s) denoting the allocated size are specified by 2751 one or two integer arguments supplied to the attribute. The allocated size 2752 is either the value of the single function argument specified or the product 2753 of the two function arguments specified. Argument numbering starts at 2754 one for ordinary functions, and at two for C++ non-static member functions. 2755 2756 For instance, 2757 2758 @smallexample 2759 void* my_calloc (size_t, size_t) __attribute__ ((alloc_size (1, 2))); 2760 void* my_realloc (void*, size_t) __attribute__ ((alloc_size (2))); 2761 @end smallexample 2762 2763 @noindent 2764 declares that @code{my_calloc} returns memory of the size given by 2765 the product of parameter 1 and 2 and that @code{my_realloc} returns memory 2766 of the size given by parameter 2. 2767 2768 @item always_inline 2769 @cindex @code{always_inline} function attribute 2770 Generally, functions are not inlined unless optimization is specified. 2771 For functions declared inline, this attribute inlines the function 2772 independent of any restrictions that otherwise apply to inlining. 2773 Failure to inline such a function is diagnosed as an error. 2774 Note that if such a function is called indirectly the compiler may 2775 or may not inline it depending on optimization level and a failure 2776 to inline an indirect call may or may not be diagnosed. 2777 2778 @item artificial 2779 @cindex @code{artificial} function attribute 2780 This attribute is useful for small inline wrappers that if possible 2781 should appear during debugging as a unit. Depending on the debug 2782 info format it either means marking the function as artificial 2783 or using the caller location for all instructions within the inlined 2784 body. 2785 2786 @item assume_aligned (@var{alignment}) 2787 @itemx assume_aligned (@var{alignment}, @var{offset}) 2788 @cindex @code{assume_aligned} function attribute 2789 The @code{assume_aligned} attribute may be applied to a function that 2790 returns a pointer. It indicates that the returned pointer is aligned 2791 on a boundary given by @var{alignment}. If the attribute has two 2792 arguments, the second argument is misalignment @var{offset}. Meaningful 2793 values of @var{alignment} are powers of 2 greater than one. Meaningful 2794 values of @var{offset} are greater than zero and less than @var{alignment}. 2795 2796 For instance 2797 2798 @smallexample 2799 void* my_alloc1 (size_t) __attribute__((assume_aligned (16))); 2800 void* my_alloc2 (size_t) __attribute__((assume_aligned (32, 8))); 2801 @end smallexample 2802 2803 @noindent 2804 declares that @code{my_alloc1} returns 16-byte aligned pointers and 2805 that @code{my_alloc2} returns a pointer whose value modulo 32 is equal 2806 to 8. 2807 2808 @item cold 2809 @cindex @code{cold} function attribute 2810 The @code{cold} attribute on functions is used to inform the compiler that 2811 the function is unlikely to be executed. The function is optimized for 2812 size rather than speed and on many targets it is placed into a special 2813 subsection of the text section so all cold functions appear close together, 2814 improving code locality of non-cold parts of program. The paths leading 2815 to calls of cold functions within code are marked as unlikely by the branch 2816 prediction mechanism. It is thus useful to mark functions used to handle 2817 unlikely conditions, such as @code{perror}, as cold to improve optimization 2818 of hot functions that do call marked functions in rare occasions. 2819 2820 When profile feedback is available, via @option{-fprofile-use}, cold functions 2821 are automatically detected and this attribute is ignored. 2822 2823 @item const 2824 @cindex @code{const} function attribute 2825 @cindex functions that have no side effects 2826 Calls to functions whose return value is not affected by changes to 2827 the observable state of the program and that have no observable effects 2828 on such state other than to return a value may lend themselves to 2829 optimizations such as common subexpression elimination. Declaring such 2830 functions with the @code{const} attribute allows GCC to avoid emitting 2831 some calls in repeated invocations of the function with the same argument 2832 values. 2833 2834 For example, 2835 2836 @smallexample 2837 int square (int) __attribute__ ((const)); 2838 @end smallexample 2839 2840 @noindent 2841 tells GCC that subsequent calls to function @code{square} with the same 2842 argument value can be replaced by the result of the first call regardless 2843 of the statements in between. 2844 2845 The @code{const} attribute prohibits a function from reading objects 2846 that affect its return value between successive invocations. However, 2847 functions declared with the attribute can safely read objects that do 2848 not change their return value, such as non-volatile constants. 2849 2850 The @code{const} attribute imposes greater restrictions on a function's 2851 definition than the similar @code{pure} attribute. Declaring the same 2852 function with both the @code{const} and the @code{pure} attribute is 2853 diagnosed. Because a const function cannot have any observable side 2854 effects it does not make sense for it to return @code{void}. Declaring 2855 such a function is diagnosed. 2856 2857 @cindex pointer arguments 2858 Note that a function that has pointer arguments and examines the data 2859 pointed to must @emph{not} be declared @code{const} if the pointed-to 2860 data might change between successive invocations of the function. In 2861 general, since a function cannot distinguish data that might change 2862 from data that cannot, const functions should never take pointer or, 2863 in C++, reference arguments. Likewise, a function that calls a non-const 2864 function usually must not be const itself. 2865 2866 @item constructor 2867 @itemx destructor 2868 @itemx constructor (@var{priority}) 2869 @itemx destructor (@var{priority}) 2870 @cindex @code{constructor} function attribute 2871 @cindex @code{destructor} function attribute 2872 The @code{constructor} attribute causes the function to be called 2873 automatically before execution enters @code{main ()}. Similarly, the 2874 @code{destructor} attribute causes the function to be called 2875 automatically after @code{main ()} completes or @code{exit ()} is 2876 called. Functions with these attributes are useful for 2877 initializing data that is used implicitly during the execution of 2878 the program. 2879 2880 On some targets the attributes also accept an integer argument to 2881 specify a priority to control the order in which constructor and 2882 destructor functions are run. A constructor 2883 with a smaller priority number runs before a constructor with a larger 2884 priority number; the opposite relationship holds for destructors. Note 2885 that priorities 0-100 are reserved. So, if you have a constructor that 2886 allocates a resource and a destructor that deallocates the same 2887 resource, both functions typically have the same priority. The 2888 priorities for constructor and destructor functions are the same as 2889 those specified for namespace-scope C++ objects (@pxref{C++ Attributes}). 2890 However, at present, the order in which constructors for C++ objects 2891 with static storage duration and functions decorated with attribute 2892 @code{constructor} are invoked is unspecified. In mixed declarations, 2893 attribute @code{init_priority} can be used to impose a specific ordering. 2894 2895 Using the argument forms of the @code{constructor} and @code{destructor} 2896 attributes on targets where the feature is not supported is rejected with 2897 an error. 2898 2899 @item copy 2900 @itemx copy (@var{function}) 2901 @cindex @code{copy} function attribute 2902 The @code{copy} attribute applies the set of attributes with which 2903 @var{function} has been declared to the declaration of the function 2904 to which the attribute is applied. The attribute is designed for 2905 libraries that define aliases or function resolvers that are expected 2906 to specify the same set of attributes as their targets. The @code{copy} 2907 attribute can be used with functions, variables, or types. However, 2908 the kind of symbol to which the attribute is applied (either function 2909 or variable) must match the kind of symbol to which the argument refers. 2910 The @code{copy} attribute copies only syntactic and semantic attributes 2911 but not attributes that affect a symbol's linkage or visibility such as 2912 @code{alias}, @code{visibility}, or @code{weak}. The @code{deprecated} 2913 and @code{target_clones} attribute are also not copied. 2914 @xref{Common Type Attributes}. 2915 @xref{Common Variable Attributes}. 2916 2917 For example, the @var{StrongAlias} macro below makes use of the @code{alias} 2918 and @code{copy} attributes to define an alias named @var{alloc} for function 2919 @var{allocate} declared with attributes @var{alloc_size}, @var{malloc}, and 2920 @var{nothrow}. Thanks to the @code{__typeof__} operator the alias has 2921 the same type as the target function. As a result of the @code{copy} 2922 attribute the alias also shares the same attributes as the target. 2923 2924 @smallexample 2925 #define StrongAlias(TargetFunc, AliasDecl) \ 2926 extern __typeof__ (TargetFunc) AliasDecl \ 2927 __attribute__ ((alias (#TargetFunc), copy (TargetFunc))); 2928 2929 extern __attribute__ ((alloc_size (1), malloc, nothrow)) 2930 void* allocate (size_t); 2931 StrongAlias (allocate, alloc); 2932 @end smallexample 2933 2934 @item deprecated 2935 @itemx deprecated (@var{msg}) 2936 @cindex @code{deprecated} function attribute 2937 The @code{deprecated} attribute results in a warning if the function 2938 is used anywhere in the source file. This is useful when identifying 2939 functions that are expected to be removed in a future version of a 2940 program. The warning also includes the location of the declaration 2941 of the deprecated function, to enable users to easily find further 2942 information about why the function is deprecated, or what they should 2943 do instead. Note that the warnings only occurs for uses: 2944 2945 @smallexample 2946 int old_fn () __attribute__ ((deprecated)); 2947 int old_fn (); 2948 int (*fn_ptr)() = old_fn; 2949 @end smallexample 2950 2951 @noindent 2952 results in a warning on line 3 but not line 2. The optional @var{msg} 2953 argument, which must be a string, is printed in the warning if 2954 present. 2955 2956 The @code{deprecated} attribute can also be used for variables and 2957 types (@pxref{Variable Attributes}, @pxref{Type Attributes}.) 2958 2959 The message attached to the attribute is affected by the setting of 2960 the @option{-fmessage-length} option. 2961 2962 @item unavailable 2963 @itemx unavailable (@var{msg}) 2964 @cindex @code{unavailable} function attribute 2965 The @code{unavailable} attribute results in an error if the function 2966 is used anywhere in the source file. This is useful when identifying 2967 functions that have been removed from a particular variation of an 2968 interface. Other than emitting an error rather than a warning, the 2969 @code{unavailable} attribute behaves in the same manner as 2970 @code{deprecated}. 2971 2972 The @code{unavailable} attribute can also be used for variables and 2973 types (@pxref{Variable Attributes}, @pxref{Type Attributes}.) 2974 2975 @item error ("@var{message}") 2976 @itemx warning ("@var{message}") 2977 @cindex @code{error} function attribute 2978 @cindex @code{warning} function attribute 2979 If the @code{error} or @code{warning} attribute 2980 is used on a function declaration and a call to such a function 2981 is not eliminated through dead code elimination or other optimizations, 2982 an error or warning (respectively) that includes @var{message} is diagnosed. 2983 This is useful 2984 for compile-time checking, especially together with @code{__builtin_constant_p} 2985 and inline functions where checking the inline function arguments is not 2986 possible through @code{extern char [(condition) ? 1 : -1];} tricks. 2987 2988 While it is possible to leave the function undefined and thus invoke 2989 a link failure (to define the function with 2990 a message in @code{.gnu.warning*} section), 2991 when using these attributes the problem is diagnosed 2992 earlier and with exact location of the call even in presence of inline 2993 functions or when not emitting debugging information. 2994 2995 @item externally_visible 2996 @cindex @code{externally_visible} function attribute 2997 This attribute, attached to a global variable or function, nullifies 2998 the effect of the @option{-fwhole-program} command-line option, so the 2999 object remains visible outside the current compilation unit. 3000 3001 If @option{-fwhole-program} is used together with @option{-flto} and 3002 @command{gold} is used as the linker plugin, 3003 @code{externally_visible} attributes are automatically added to functions 3004 (not variable yet due to a current @command{gold} issue) 3005 that are accessed outside of LTO objects according to resolution file 3006 produced by @command{gold}. 3007 For other linkers that cannot generate resolution file, 3008 explicit @code{externally_visible} attributes are still necessary. 3009 3010 @item flatten 3011 @cindex @code{flatten} function attribute 3012 Generally, inlining into a function is limited. For a function marked with 3013 this attribute, every call inside this function is inlined, if possible. 3014 Functions declared with attribute @code{noinline} and similar are not 3015 inlined. Whether the function itself is considered for inlining depends 3016 on its size and the current inlining parameters. 3017 3018 @item format (@var{archetype}, @var{string-index}, @var{first-to-check}) 3019 @cindex @code{format} function attribute 3020 @cindex functions with @code{printf}, @code{scanf}, @code{strftime} or @code{strfmon} style arguments 3021 @opindex Wformat 3022 The @code{format} attribute specifies that a function takes @code{printf}, 3023 @code{scanf}, @code{strftime} or @code{strfmon} style arguments that 3024 should be type-checked against a format string. For example, the 3025 declaration: 3026 3027 @smallexample 3028 extern int 3029 my_printf (void *my_object, const char *my_format, ...) 3030 __attribute__ ((format (printf, 2, 3))); 3031 @end smallexample 3032 3033 @noindent 3034 causes the compiler to check the arguments in calls to @code{my_printf} 3035 for consistency with the @code{printf} style format string argument 3036 @code{my_format}. 3037 3038 The parameter @var{archetype} determines how the format string is 3039 interpreted, and should be @code{printf}, @code{scanf}, @code{strftime}, 3040 @code{gnu_printf}, @code{gnu_scanf}, @code{gnu_strftime} or 3041 @code{strfmon}. (You can also use @code{__printf__}, 3042 @code{__scanf__}, @code{__strftime__} or @code{__strfmon__}.) On 3043 MinGW targets, @code{ms_printf}, @code{ms_scanf}, and 3044 @code{ms_strftime} are also present. 3045 @var{archetype} values such as @code{printf} refer to the formats accepted 3046 by the system's C runtime library, 3047 while values prefixed with @samp{gnu_} always refer 3048 to the formats accepted by the GNU C Library. On Microsoft Windows 3049 targets, values prefixed with @samp{ms_} refer to the formats accepted by the 3050 @file{msvcrt.dll} library. 3051 The parameter @var{string-index} 3052 specifies which argument is the format string argument (starting 3053 from 1), while @var{first-to-check} is the number of the first 3054 argument to check against the format string. For functions 3055 where the arguments are not available to be checked (such as 3056 @code{vprintf}), specify the third parameter as zero. In this case the 3057 compiler only checks the format string for consistency. For 3058 @code{strftime} formats, the third parameter is required to be zero. 3059 Since non-static C++ methods have an implicit @code{this} argument, the 3060 arguments of such methods should be counted from two, not one, when 3061 giving values for @var{string-index} and @var{first-to-check}. 3062 3063 In the example above, the format string (@code{my_format}) is the second 3064 argument of the function @code{my_print}, and the arguments to check 3065 start with the third argument, so the correct parameters for the format 3066 attribute are 2 and 3. 3067 3068 @opindex ffreestanding 3069 @opindex fno-builtin 3070 The @code{format} attribute allows you to identify your own functions 3071 that take format strings as arguments, so that GCC can check the 3072 calls to these functions for errors. The compiler always (unless 3073 @option{-ffreestanding} or @option{-fno-builtin} is used) checks formats 3074 for the standard library functions @code{printf}, @code{fprintf}, 3075 @code{sprintf}, @code{scanf}, @code{fscanf}, @code{sscanf}, @code{strftime}, 3076 @code{vprintf}, @code{vfprintf} and @code{vsprintf} whenever such 3077 warnings are requested (using @option{-Wformat}), so there is no need to 3078 modify the header file @file{stdio.h}. In C99 mode, the functions 3079 @code{snprintf}, @code{vsnprintf}, @code{vscanf}, @code{vfscanf} and 3080 @code{vsscanf} are also checked. Except in strictly conforming C 3081 standard modes, the X/Open function @code{strfmon} is also checked as 3082 are @code{printf_unlocked} and @code{fprintf_unlocked}. 3083 @xref{C Dialect Options,,Options Controlling C Dialect}. 3084 3085 For Objective-C dialects, @code{NSString} (or @code{__NSString__}) is 3086 recognized in the same context. Declarations including these format attributes 3087 are parsed for correct syntax, however the result of checking of such format 3088 strings is not yet defined, and is not carried out by this version of the 3089 compiler. 3090 3091 The target may also provide additional types of format checks. 3092 @xref{Target Format Checks,,Format Checks Specific to Particular 3093 Target Machines}. 3094 3095 @item format_arg (@var{string-index}) 3096 @cindex @code{format_arg} function attribute 3097 @opindex Wformat-nonliteral 3098 The @code{format_arg} attribute specifies that a function takes one or 3099 more format strings for a @code{printf}, @code{scanf}, @code{strftime} or 3100 @code{strfmon} style function and modifies it (for example, to translate 3101 it into another language), so the result can be passed to a 3102 @code{printf}, @code{scanf}, @code{strftime} or @code{strfmon} style 3103 function (with the remaining arguments to the format function the same 3104 as they would have been for the unmodified string). Multiple 3105 @code{format_arg} attributes may be applied to the same function, each 3106 designating a distinct parameter as a format string. For example, the 3107 declaration: 3108 3109 @smallexample 3110 extern char * 3111 my_dgettext (char *my_domain, const char *my_format) 3112 __attribute__ ((format_arg (2))); 3113 @end smallexample 3114 3115 @noindent 3116 causes the compiler to check the arguments in calls to a @code{printf}, 3117 @code{scanf}, @code{strftime} or @code{strfmon} type function, whose 3118 format string argument is a call to the @code{my_dgettext} function, for 3119 consistency with the format string argument @code{my_format}. If the 3120 @code{format_arg} attribute had not been specified, all the compiler 3121 could tell in such calls to format functions would be that the format 3122 string argument is not constant; this would generate a warning when 3123 @option{-Wformat-nonliteral} is used, but the calls could not be checked 3124 without the attribute. 3125 3126 In calls to a function declared with more than one @code{format_arg} 3127 attribute, each with a distinct argument value, the corresponding 3128 actual function arguments are checked against all format strings 3129 designated by the attributes. This capability is designed to support 3130 the GNU @code{ngettext} family of functions. 3131 3132 The parameter @var{string-index} specifies which argument is the format 3133 string argument (starting from one). Since non-static C++ methods have 3134 an implicit @code{this} argument, the arguments of such methods should 3135 be counted from two. 3136 3137 The @code{format_arg} attribute allows you to identify your own 3138 functions that modify format strings, so that GCC can check the 3139 calls to @code{printf}, @code{scanf}, @code{strftime} or @code{strfmon} 3140 type function whose operands are a call to one of your own function. 3141 The compiler always treats @code{gettext}, @code{dgettext}, and 3142 @code{dcgettext} in this manner except when strict ISO C support is 3143 requested by @option{-ansi} or an appropriate @option{-std} option, or 3144 @option{-ffreestanding} or @option{-fno-builtin} 3145 is used. @xref{C Dialect Options,,Options 3146 Controlling C Dialect}. 3147 3148 For Objective-C dialects, the @code{format-arg} attribute may refer to an 3149 @code{NSString} reference for compatibility with the @code{format} attribute 3150 above. 3151 3152 The target may also allow additional types in @code{format-arg} attributes. 3153 @xref{Target Format Checks,,Format Checks Specific to Particular 3154 Target Machines}. 3155 3156 @item gnu_inline 3157 @cindex @code{gnu_inline} function attribute 3158 This attribute should be used with a function that is also declared 3159 with the @code{inline} keyword. It directs GCC to treat the function 3160 as if it were defined in gnu90 mode even when compiling in C99 or 3161 gnu99 mode. 3162 3163 If the function is declared @code{extern}, then this definition of the 3164 function is used only for inlining. In no case is the function 3165 compiled as a standalone function, not even if you take its address 3166 explicitly. Such an address becomes an external reference, as if you 3167 had only declared the function, and had not defined it. This has 3168 almost the effect of a macro. The way to use this is to put a 3169 function definition in a header file with this attribute, and put 3170 another copy of the function, without @code{extern}, in a library 3171 file. The definition in the header file causes most calls to the 3172 function to be inlined. If any uses of the function remain, they 3173 refer to the single copy in the library. Note that the two 3174 definitions of the functions need not be precisely the same, although 3175 if they do not have the same effect your program may behave oddly. 3176 3177 In C, if the function is neither @code{extern} nor @code{static}, then 3178 the function is compiled as a standalone function, as well as being 3179 inlined where possible. 3180 3181 This is how GCC traditionally handled functions declared 3182 @code{inline}. Since ISO C99 specifies a different semantics for 3183 @code{inline}, this function attribute is provided as a transition 3184 measure and as a useful feature in its own right. This attribute is 3185 available in GCC 4.1.3 and later. It is available if either of the 3186 preprocessor macros @code{__GNUC_GNU_INLINE__} or 3187 @code{__GNUC_STDC_INLINE__} are defined. @xref{Inline,,An Inline 3188 Function is As Fast As a Macro}. 3189 3190 In C++, this attribute does not depend on @code{extern} in any way, 3191 but it still requires the @code{inline} keyword to enable its special 3192 behavior. 3193 3194 @item hot 3195 @cindex @code{hot} function attribute 3196 The @code{hot} attribute on a function is used to inform the compiler that 3197 the function is a hot spot of the compiled program. The function is 3198 optimized more aggressively and on many targets it is placed into a special 3199 subsection of the text section so all hot functions appear close together, 3200 improving locality. 3201 3202 When profile feedback is available, via @option{-fprofile-use}, hot functions 3203 are automatically detected and this attribute is ignored. 3204 3205 @item ifunc ("@var{resolver}") 3206 @cindex @code{ifunc} function attribute 3207 @cindex indirect functions 3208 @cindex functions that are dynamically resolved 3209 The @code{ifunc} attribute is used to mark a function as an indirect 3210 function using the STT_GNU_IFUNC symbol type extension to the ELF 3211 standard. This allows the resolution of the symbol value to be 3212 determined dynamically at load time, and an optimized version of the 3213 routine to be selected for the particular processor or other system 3214 characteristics determined then. To use this attribute, first define 3215 the implementation functions available, and a resolver function that 3216 returns a pointer to the selected implementation function. The 3217 implementation functions' declarations must match the API of the 3218 function being implemented. The resolver should be declared to 3219 be a function taking no arguments and returning a pointer to 3220 a function of the same type as the implementation. For example: 3221 3222 @smallexample 3223 void *my_memcpy (void *dst, const void *src, size_t len) 3224 @{ 3225 @dots{} 3226 return dst; 3227 @} 3228 3229 static void * (*resolve_memcpy (void))(void *, const void *, size_t) 3230 @{ 3231 return my_memcpy; // we will just always select this routine 3232 @} 3233 @end smallexample 3234 3235 @noindent 3236 The exported header file declaring the function the user calls would 3237 contain: 3238 3239 @smallexample 3240 extern void *memcpy (void *, const void *, size_t); 3241 @end smallexample 3242 3243 @noindent 3244 allowing the user to call @code{memcpy} as a regular function, unaware of 3245 the actual implementation. Finally, the indirect function needs to be 3246 defined in the same translation unit as the resolver function: 3247 3248 @smallexample 3249 void *memcpy (void *, const void *, size_t) 3250 __attribute__ ((ifunc ("resolve_memcpy"))); 3251 @end smallexample 3252 3253 In C++, the @code{ifunc} attribute takes a string that is the mangled name 3254 of the resolver function. A C++ resolver for a non-static member function 3255 of class @code{C} should be declared to return a pointer to a non-member 3256 function taking pointer to @code{C} as the first argument, followed by 3257 the same arguments as of the implementation function. G++ checks 3258 the signatures of the two functions and issues 3259 a @option{-Wattribute-alias} warning for mismatches. To suppress a warning 3260 for the necessary cast from a pointer to the implementation member function 3261 to the type of the corresponding non-member function use 3262 the @option{-Wno-pmf-conversions} option. For example: 3263 3264 @smallexample 3265 class S 3266 @{ 3267 private: 3268 int debug_impl (int); 3269 int optimized_impl (int); 3270 3271 typedef int Func (S*, int); 3272 3273 static Func* resolver (); 3274 public: 3275 3276 int interface (int); 3277 @}; 3278 3279 int S::debug_impl (int) @{ /* @r{@dots{}} */ @} 3280 int S::optimized_impl (int) @{ /* @r{@dots{}} */ @} 3281 3282 S::Func* S::resolver () 3283 @{ 3284 int (S::*pimpl) (int) 3285 = getenv ("DEBUG") ? &S::debug_impl : &S::optimized_impl; 3286 3287 // Cast triggers -Wno-pmf-conversions. 3288 return reinterpret_cast<Func*>(pimpl); 3289 @} 3290 3291 int S::interface (int) __attribute__ ((ifunc ("_ZN1S8resolverEv"))); 3292 @end smallexample 3293 3294 Indirect functions cannot be weak. Binutils version 2.20.1 or higher 3295 and GNU C Library version 2.11.1 are required to use this feature. 3296 3297 @item interrupt 3298 @itemx interrupt_handler 3299 Many GCC back ends support attributes to indicate that a function is 3300 an interrupt handler, which tells the compiler to generate function 3301 entry and exit sequences that differ from those from regular 3302 functions. The exact syntax and behavior are target-specific; 3303 refer to the following subsections for details. 3304 3305 @item leaf 3306 @cindex @code{leaf} function attribute 3307 Calls to external functions with this attribute must return to the 3308 current compilation unit only by return or by exception handling. In 3309 particular, a leaf function is not allowed to invoke callback functions 3310 passed to it from the current compilation unit, directly call functions 3311 exported by the unit, or @code{longjmp} into the unit. Leaf functions 3312 might still call functions from other compilation units and thus they 3313 are not necessarily leaf in the sense that they contain no function 3314 calls at all. 3315 3316 The attribute is intended for library functions to improve dataflow 3317 analysis. The compiler takes the hint that any data not escaping the 3318 current compilation unit cannot be used or modified by the leaf 3319 function. For example, the @code{sin} function is a leaf function, but 3320 @code{qsort} is not. 3321 3322 Note that leaf functions might indirectly run a signal handler defined 3323 in the current compilation unit that uses static variables. Similarly, 3324 when lazy symbol resolution is in effect, leaf functions might invoke 3325 indirect functions whose resolver function or implementation function is 3326 defined in the current compilation unit and uses static variables. There 3327 is no standard-compliant way to write such a signal handler, resolver 3328 function, or implementation function, and the best that you can do is to 3329 remove the @code{leaf} attribute or mark all such static variables 3330 @code{volatile}. Lastly, for ELF-based systems that support symbol 3331 interposition, care should be taken that functions defined in the 3332 current compilation unit do not unexpectedly interpose other symbols 3333 based on the defined standards mode and defined feature test macros; 3334 otherwise an inadvertent callback would be added. 3335 3336 The attribute has no effect on functions defined within the current 3337 compilation unit. This is to allow easy merging of multiple compilation 3338 units into one, for example, by using the link-time optimization. For 3339 this reason the attribute is not allowed on types to annotate indirect 3340 calls. 3341 3342 @item malloc 3343 @item malloc (@var{deallocator}) 3344 @item malloc (@var{deallocator}, @var{ptr-index}) 3345 @cindex @code{malloc} function attribute 3346 @cindex functions that behave like malloc 3347 Attribute @code{malloc} indicates that a function is @code{malloc}-like, 3348 i.e., that the pointer @var{P} returned by the function cannot alias any 3349 other pointer valid when the function returns, and moreover no 3350 pointers to valid objects occur in any storage addressed by @var{P}. In 3351 addition, the GCC predicts that a function with the attribute returns 3352 non-null in most cases. 3353 3354 Independently, the form of the attribute with one or two arguments 3355 associates @code{deallocator} as a suitable deallocation function for 3356 pointers returned from the @code{malloc}-like function. @var{ptr-index} 3357 denotes the positional argument to which when the pointer is passed in 3358 calls to @code{deallocator} has the effect of deallocating it. 3359 3360 Using the attribute with no arguments is designed to improve optimization 3361 by relying on the aliasing property it implies. Functions like @code{malloc} 3362 and @code{calloc} have this property because they return a pointer to 3363 uninitialized or zeroed-out, newly obtained storage. However, functions 3364 like @code{realloc} do not have this property, as they may return pointers 3365 to storage containing pointers to existing objects. Additionally, since 3366 all such functions are assumed to return null only infrequently, callers 3367 can be optimized based on that assumption. 3368 3369 Associating a function with a @var{deallocator} helps detect calls to 3370 mismatched allocation and deallocation functions and diagnose them under 3371 the control of options such as @option{-Wmismatched-dealloc}. It also 3372 makes it possible to diagnose attempts to deallocate objects that were not 3373 allocated dynamically, by @option{-Wfree-nonheap-object}. To indicate 3374 that an allocation function both satisifies the nonaliasing property and 3375 has a deallocator associated with it, both the plain form of the attribute 3376 and the one with the @var{deallocator} argument must be used. The same 3377 function can be both an allocator and a deallocator. Since inlining one 3378 of the associated functions but not the other could result in apparent 3379 mismatches, this form of attribute @code{malloc} is not accepted on inline 3380 functions. For the same reason, using the attribute prevents both 3381 the allocation and deallocation functions from being expanded inline. 3382 3383 For example, besides stating that the functions return pointers that do 3384 not alias any others, the following declarations make @code{fclose} 3385 a suitable deallocator for pointers returned from all functions except 3386 @code{popen}, and @code{pclose} as the only suitable deallocator for 3387 pointers returned from @code{popen}. The deallocator functions must 3388 be declared before they can be referenced in the attribute. 3389 3390 @smallexample 3391 int fclose (FILE*); 3392 int pclose (FILE*); 3393 3394 __attribute__ ((malloc, malloc (fclose, 1))) 3395 FILE* fdopen (int, const char*); 3396 __attribute__ ((malloc, malloc (fclose, 1))) 3397 FILE* fopen (const char*, const char*); 3398 __attribute__ ((malloc, malloc (fclose, 1))) 3399 FILE* fmemopen(void *, size_t, const char *); 3400 __attribute__ ((malloc, malloc (pclose, 1))) 3401 FILE* popen (const char*, const char*); 3402 __attribute__ ((malloc, malloc (fclose, 1))) 3403 FILE* tmpfile (void); 3404 @end smallexample 3405 3406 The warnings guarded by @option{-fanalyzer} respect allocation and 3407 deallocation pairs marked with the @code{malloc}. In particular: 3408 3409 @itemize @bullet 3410 3411 @item 3412 The analyzer will emit a @option{-Wanalyzer-mismatching-deallocation} 3413 diagnostic if there is an execution path in which the result of an 3414 allocation call is passed to a different deallocator. 3415 3416 @item 3417 The analyzer will emit a @option{-Wanalyzer-double-free} 3418 diagnostic if there is an execution path in which a value is passed 3419 more than once to a deallocation call. 3420 3421 @item 3422 The analyzer will consider the possibility that an allocation function 3423 could fail and return NULL. It will emit 3424 @option{-Wanalyzer-possible-null-dereference} and 3425 @option{-Wanalyzer-possible-null-argument} diagnostics if there are 3426 execution paths in which an unchecked result of an allocation call is 3427 dereferenced or passed to a function requiring a non-null argument. 3428 If the allocator always returns non-null, use 3429 @code{__attribute__ ((returns_nonnull))} to suppress these warnings. 3430 For example: 3431 @smallexample 3432 char *xstrdup (const char *) 3433 __attribute__((malloc (free), returns_nonnull)); 3434 @end smallexample 3435 3436 @item 3437 The analyzer will emit a @option{-Wanalyzer-use-after-free} 3438 diagnostic if there is an execution path in which the memory passed 3439 by pointer to a deallocation call is used after the deallocation. 3440 3441 @item 3442 The analyzer will emit a @option{-Wanalyzer-malloc-leak} diagnostic if 3443 there is an execution path in which the result of an allocation call 3444 is leaked (without being passed to the deallocation function). 3445 3446 @item 3447 The analyzer will emit a @option{-Wanalyzer-free-of-non-heap} diagnostic 3448 if a deallocation function is used on a global or on-stack variable. 3449 3450 @end itemize 3451 3452 The analyzer assumes that deallocators can gracefully handle the @code{NULL} 3453 pointer. If this is not the case, the deallocator can be marked with 3454 @code{__attribute__((nonnull))} so that @option{-fanalyzer} can emit 3455 a @option{-Wanalyzer-possible-null-argument} diagnostic for code paths 3456 in which the deallocator is called with NULL. 3457 3458 @item no_icf 3459 @cindex @code{no_icf} function attribute 3460 This function attribute prevents a functions from being merged with another 3461 semantically equivalent function. 3462 3463 @item no_instrument_function 3464 @cindex @code{no_instrument_function} function attribute 3465 @opindex finstrument-functions 3466 @opindex p 3467 @opindex pg 3468 If any of @option{-finstrument-functions}, @option{-p}, or @option{-pg} are 3469 given, profiling function calls are 3470 generated at entry and exit of most user-compiled functions. 3471 Functions with this attribute are not so instrumented. 3472 3473 @item no_profile_instrument_function 3474 @cindex @code{no_profile_instrument_function} function attribute 3475 The @code{no_profile_instrument_function} attribute on functions is used 3476 to inform the compiler that it should not process any profile feedback based 3477 optimization code instrumentation. 3478 3479 @item no_reorder 3480 @cindex @code{no_reorder} function attribute 3481 Do not reorder functions or variables marked @code{no_reorder} 3482 against each other or top level assembler statements the executable. 3483 The actual order in the program will depend on the linker command 3484 line. Static variables marked like this are also not removed. 3485 This has a similar effect 3486 as the @option{-fno-toplevel-reorder} option, but only applies to the 3487 marked symbols. 3488 3489 @item no_sanitize ("@var{sanitize_option}") 3490 @cindex @code{no_sanitize} function attribute 3491 The @code{no_sanitize} attribute on functions is used 3492 to inform the compiler that it should not do sanitization of any option 3493 mentioned in @var{sanitize_option}. A list of values acceptable by 3494 the @option{-fsanitize} option can be provided. 3495 3496 @smallexample 3497 void __attribute__ ((no_sanitize ("alignment", "object-size"))) 3498 f () @{ /* @r{Do something.} */; @} 3499 void __attribute__ ((no_sanitize ("alignment,object-size"))) 3500 g () @{ /* @r{Do something.} */; @} 3501 @end smallexample 3502 3503 @item no_sanitize_address 3504 @itemx no_address_safety_analysis 3505 @cindex @code{no_sanitize_address} function attribute 3506 The @code{no_sanitize_address} attribute on functions is used 3507 to inform the compiler that it should not instrument memory accesses 3508 in the function when compiling with the @option{-fsanitize=address} option. 3509 The @code{no_address_safety_analysis} is a deprecated alias of the 3510 @code{no_sanitize_address} attribute, new code should use 3511 @code{no_sanitize_address}. 3512 3513 @item no_sanitize_thread 3514 @cindex @code{no_sanitize_thread} function attribute 3515 The @code{no_sanitize_thread} attribute on functions is used 3516 to inform the compiler that it should not instrument memory accesses 3517 in the function when compiling with the @option{-fsanitize=thread} option. 3518 3519 @item no_sanitize_undefined 3520 @cindex @code{no_sanitize_undefined} function attribute 3521 The @code{no_sanitize_undefined} attribute on functions is used 3522 to inform the compiler that it should not check for undefined behavior 3523 in the function when compiling with the @option{-fsanitize=undefined} option. 3524 3525 @item no_sanitize_coverage 3526 @cindex @code{no_sanitize_coverage} function attribute 3527 The @code{no_sanitize_coverage} attribute on functions is used 3528 to inform the compiler that it should not do coverage-guided 3529 fuzzing code instrumentation (@option{-fsanitize-coverage}). 3530 3531 @item no_split_stack 3532 @cindex @code{no_split_stack} function attribute 3533 @opindex fsplit-stack 3534 If @option{-fsplit-stack} is given, functions have a small 3535 prologue which decides whether to split the stack. Functions with the 3536 @code{no_split_stack} attribute do not have that prologue, and thus 3537 may run with only a small amount of stack space available. 3538 3539 @item no_stack_limit 3540 @cindex @code{no_stack_limit} function attribute 3541 This attribute locally overrides the @option{-fstack-limit-register} 3542 and @option{-fstack-limit-symbol} command-line options; it has the effect 3543 of disabling stack limit checking in the function it applies to. 3544 3545 @item noclone 3546 @cindex @code{noclone} function attribute 3547 This function attribute prevents a function from being considered for 3548 cloning---a mechanism that produces specialized copies of functions 3549 and which is (currently) performed by interprocedural constant 3550 propagation. 3551 3552 @item noinline 3553 @cindex @code{noinline} function attribute 3554 This function attribute prevents a function from being considered for 3555 inlining. 3556 @c Don't enumerate the optimizations by name here; we try to be 3557 @c future-compatible with this mechanism. 3558 If the function does not have side effects, there are optimizations 3559 other than inlining that cause function calls to be optimized away, 3560 although the function call is live. To keep such calls from being 3561 optimized away, put 3562 @smallexample 3563 asm (""); 3564 @end smallexample 3565 3566 @noindent 3567 (@pxref{Extended Asm}) in the called function, to serve as a special 3568 side effect. 3569 3570 @item noipa 3571 @cindex @code{noipa} function attribute 3572 Disable interprocedural optimizations between the function with this 3573 attribute and its callers, as if the body of the function is not available 3574 when optimizing callers and the callers are unavailable when optimizing 3575 the body. This attribute implies @code{noinline}, @code{noclone} and 3576 @code{no_icf} attributes. However, this attribute is not equivalent 3577 to a combination of other attributes, because its purpose is to suppress 3578 existing and future optimizations employing interprocedural analysis, 3579 including those that do not have an attribute suitable for disabling 3580 them individually. This attribute is supported mainly for the purpose 3581 of testing the compiler. 3582 3583 @item nonnull 3584 @itemx nonnull (@var{arg-index}, @dots{}) 3585 @cindex @code{nonnull} function attribute 3586 @cindex functions with non-null pointer arguments 3587 The @code{nonnull} attribute may be applied to a function that takes at 3588 least one argument of a pointer type. It indicates that the referenced 3589 arguments must be non-null pointers. For instance, the declaration: 3590 3591 @smallexample 3592 extern void * 3593 my_memcpy (void *dest, const void *src, size_t len) 3594 __attribute__((nonnull (1, 2))); 3595 @end smallexample 3596 3597 @noindent 3598 informs the compiler that, in calls to @code{my_memcpy}, arguments 3599 @var{dest} and @var{src} must be non-null. 3600 3601 The attribute has an effect both on functions calls and function definitions. 3602 3603 For function calls: 3604 @itemize @bullet 3605 @item If the compiler determines that a null pointer is 3606 passed in an argument slot marked as non-null, and the 3607 @option{-Wnonnull} option is enabled, a warning is issued. 3608 @xref{Warning Options}. 3609 @item The @option{-fisolate-erroneous-paths-attribute} option can be 3610 specified to have GCC transform calls with null arguments to non-null 3611 functions into traps. @xref{Optimize Options}. 3612 @item The compiler may also perform optimizations based on the 3613 knowledge that certain function arguments cannot be null. These 3614 optimizations can be disabled by the 3615 @option{-fno-delete-null-pointer-checks} option. @xref{Optimize Options}. 3616 @end itemize 3617 3618 For function definitions: 3619 @itemize @bullet 3620 @item If the compiler determines that a function parameter that is 3621 marked with nonnull is compared with null, and 3622 @option{-Wnonnull-compare} option is enabled, a warning is issued. 3623 @xref{Warning Options}. 3624 @item The compiler may also perform optimizations based on the 3625 knowledge that @code{nonnul} parameters cannot be null. This can 3626 currently not be disabled other than by removing the nonnull 3627 attribute. 3628 @end itemize 3629 3630 If no @var{arg-index} is given to the @code{nonnull} attribute, 3631 all pointer arguments are marked as non-null. To illustrate, the 3632 following declaration is equivalent to the previous example: 3633 3634 @smallexample 3635 extern void * 3636 my_memcpy (void *dest, const void *src, size_t len) 3637 __attribute__((nonnull)); 3638 @end smallexample 3639 3640 @item noplt 3641 @cindex @code{noplt} function attribute 3642 The @code{noplt} attribute is the counterpart to option @option{-fno-plt}. 3643 Calls to functions marked with this attribute in position-independent code 3644 do not use the PLT. 3645 3646 @smallexample 3647 @group 3648 /* Externally defined function foo. */ 3649 int foo () __attribute__ ((noplt)); 3650 3651 int 3652 main (/* @r{@dots{}} */) 3653 @{ 3654 /* @r{@dots{}} */ 3655 foo (); 3656 /* @r{@dots{}} */ 3657 @} 3658 @end group 3659 @end smallexample 3660 3661 The @code{noplt} attribute on function @code{foo} 3662 tells the compiler to assume that 3663 the function @code{foo} is externally defined and that the call to 3664 @code{foo} must avoid the PLT 3665 in position-independent code. 3666 3667 In position-dependent code, a few targets also convert calls to 3668 functions that are marked to not use the PLT to use the GOT instead. 3669 3670 @item noreturn 3671 @cindex @code{noreturn} function attribute 3672 @cindex functions that never return 3673 A few standard library functions, such as @code{abort} and @code{exit}, 3674 cannot return. GCC knows this automatically. Some programs define 3675 their own functions that never return. You can declare them 3676 @code{noreturn} to tell the compiler this fact. For example, 3677 3678 @smallexample 3679 @group 3680 void fatal () __attribute__ ((noreturn)); 3681 3682 void 3683 fatal (/* @r{@dots{}} */) 3684 @{ 3685 /* @r{@dots{}} */ /* @r{Print error message.} */ /* @r{@dots{}} */ 3686 exit (1); 3687 @} 3688 @end group 3689 @end smallexample 3690 3691 The @code{noreturn} keyword tells the compiler to assume that 3692 @code{fatal} cannot return. It can then optimize without regard to what 3693 would happen if @code{fatal} ever did return. This makes slightly 3694 better code. More importantly, it helps avoid spurious warnings of 3695 uninitialized variables. 3696 3697 The @code{noreturn} keyword does not affect the exceptional path when that 3698 applies: a @code{noreturn}-marked function may still return to the caller 3699 by throwing an exception or calling @code{longjmp}. 3700 3701 In order to preserve backtraces, GCC will never turn calls to 3702 @code{noreturn} functions into tail calls. 3703 3704 Do not assume that registers saved by the calling function are 3705 restored before calling the @code{noreturn} function. 3706 3707 It does not make sense for a @code{noreturn} function to have a return 3708 type other than @code{void}. 3709 3710 @item nothrow 3711 @cindex @code{nothrow} function attribute 3712 The @code{nothrow} attribute is used to inform the compiler that a 3713 function cannot throw an exception. For example, most functions in 3714 the standard C library can be guaranteed not to throw an exception 3715 with the notable exceptions of @code{qsort} and @code{bsearch} that 3716 take function pointer arguments. 3717 3718 @item optimize (@var{level}, @dots{}) 3719 @item optimize (@var{string}, @dots{}) 3720 @cindex @code{optimize} function attribute 3721 The @code{optimize} attribute is used to specify that a function is to 3722 be compiled with different optimization options than specified on the 3723 command line. The optimize attribute arguments of a function behave 3724 behave as if appended to the command-line. 3725 3726 Valid arguments are constant non-negative integers and 3727 strings. Each numeric argument specifies an optimization @var{level}. 3728 Each @var{string} argument consists of one or more comma-separated 3729 substrings. Each substring that begins with the letter @code{O} refers 3730 to an optimization option such as @option{-O0} or @option{-Os}. Other 3731 substrings are taken as suffixes to the @code{-f} prefix jointly 3732 forming the name of an optimization option. @xref{Optimize Options}. 3733 3734 @samp{#pragma GCC optimize} can be used to set optimization options 3735 for more than one function. @xref{Function Specific Option Pragmas}, 3736 for details about the pragma. 3737 3738 Providing multiple strings as arguments separated by commas to specify 3739 multiple options is equivalent to separating the option suffixes with 3740 a comma (@samp{,}) within a single string. Spaces are not permitted 3741 within the strings. 3742 3743 Not every optimization option that starts with the @var{-f} prefix 3744 specified by the attribute necessarily has an effect on the function. 3745 The @code{optimize} attribute should be used for debugging purposes only. 3746 It is not suitable in production code. 3747 3748 @item patchable_function_entry 3749 @cindex @code{patchable_function_entry} function attribute 3750 @cindex extra NOP instructions at the function entry point 3751 In case the target's text segment can be made writable at run time by 3752 any means, padding the function entry with a number of NOPs can be 3753 used to provide a universal tool for instrumentation. 3754 3755 The @code{patchable_function_entry} function attribute can be used to 3756 change the number of NOPs to any desired value. The two-value syntax 3757 is the same as for the command-line switch 3758 @option{-fpatchable-function-entry=N,M}, generating @var{N} NOPs, with 3759 the function entry point before the @var{M}th NOP instruction. 3760 @var{M} defaults to 0 if omitted e.g.@: function entry point is before 3761 the first NOP. 3762 3763 If patchable function entries are enabled globally using the command-line 3764 option @option{-fpatchable-function-entry=N,M}, then you must disable 3765 instrumentation on all functions that are part of the instrumentation 3766 framework with the attribute @code{patchable_function_entry (0)} 3767 to prevent recursion. 3768 3769 @item pure 3770 @cindex @code{pure} function attribute 3771 @cindex functions that have no side effects 3772 3773 Calls to functions that have no observable effects on the state of 3774 the program other than to return a value may lend themselves to optimizations 3775 such as common subexpression elimination. Declaring such functions with 3776 the @code{pure} attribute allows GCC to avoid emitting some calls in repeated 3777 invocations of the function with the same argument values. 3778 3779 The @code{pure} attribute prohibits a function from modifying the state 3780 of the program that is observable by means other than inspecting 3781 the function's return value. However, functions declared with the @code{pure} 3782 attribute can safely read any non-volatile objects, and modify the value of 3783 objects in a way that does not affect their return value or the observable 3784 state of the program. 3785 3786 For example, 3787 3788 @smallexample 3789 int hash (char *) __attribute__ ((pure)); 3790 @end smallexample 3791 3792 @noindent 3793 tells GCC that subsequent calls to the function @code{hash} with the same 3794 string can be replaced by the result of the first call provided the state 3795 of the program observable by @code{hash}, including the contents of the array 3796 itself, does not change in between. Even though @code{hash} takes a non-const 3797 pointer argument it must not modify the array it points to, or any other object 3798 whose value the rest of the program may depend on. However, the caller may 3799 safely change the contents of the array between successive calls to 3800 the function (doing so disables the optimization). The restriction also 3801 applies to member objects referenced by the @code{this} pointer in C++ 3802 non-static member functions. 3803 3804 Some common examples of pure functions are @code{strlen} or @code{memcmp}. 3805 Interesting non-pure functions are functions with infinite loops or those 3806 depending on volatile memory or other system resource, that may change between 3807 consecutive calls (such as the standard C @code{feof} function in 3808 a multithreading environment). 3809 3810 The @code{pure} attribute imposes similar but looser restrictions on 3811 a function's definition than the @code{const} attribute: @code{pure} 3812 allows the function to read any non-volatile memory, even if it changes 3813 in between successive invocations of the function. Declaring the same 3814 function with both the @code{pure} and the @code{const} attribute is 3815 diagnosed. Because a pure function cannot have any observable side 3816 effects it does not make sense for such a function to return @code{void}. 3817 Declaring such a function is diagnosed. 3818 3819 @item returns_nonnull 3820 @cindex @code{returns_nonnull} function attribute 3821 The @code{returns_nonnull} attribute specifies that the function 3822 return value should be a non-null pointer. For instance, the declaration: 3823 3824 @smallexample 3825 extern void * 3826 mymalloc (size_t len) __attribute__((returns_nonnull)); 3827 @end smallexample 3828 3829 @noindent 3830 lets the compiler optimize callers based on the knowledge 3831 that the return value will never be null. 3832 3833 @item returns_twice 3834 @cindex @code{returns_twice} function attribute 3835 @cindex functions that return more than once 3836 The @code{returns_twice} attribute tells the compiler that a function may 3837 return more than one time. The compiler ensures that all registers 3838 are dead before calling such a function and emits a warning about 3839 the variables that may be clobbered after the second return from the 3840 function. Examples of such functions are @code{setjmp} and @code{vfork}. 3841 The @code{longjmp}-like counterpart of such function, if any, might need 3842 to be marked with the @code{noreturn} attribute. 3843 3844 @item section ("@var{section-name}") 3845 @cindex @code{section} function attribute 3846 @cindex functions in arbitrary sections 3847 Normally, the compiler places the code it generates in the @code{text} section. 3848 Sometimes, however, you need additional sections, or you need certain 3849 particular functions to appear in special sections. The @code{section} 3850 attribute specifies that a function lives in a particular section. 3851 For example, the declaration: 3852 3853 @smallexample 3854 extern void foobar (void) __attribute__ ((section ("bar"))); 3855 @end smallexample 3856 3857 @noindent 3858 puts the function @code{foobar} in the @code{bar} section. 3859 3860 Some file formats do not support arbitrary sections so the @code{section} 3861 attribute is not available on all platforms. 3862 If you need to map the entire contents of a module to a particular 3863 section, consider using the facilities of the linker instead. 3864 3865 @item sentinel 3866 @itemx sentinel (@var{position}) 3867 @cindex @code{sentinel} function attribute 3868 This function attribute indicates that an argument in a call to the function 3869 is expected to be an explicit @code{NULL}. The attribute is only valid on 3870 variadic functions. By default, the sentinel is expected to be the last 3871 argument of the function call. If the optional @var{position} argument 3872 is specified to the attribute, the sentinel must be located at 3873 @var{position} counting backwards from the end of the argument list. 3874 3875 @smallexample 3876 __attribute__ ((sentinel)) 3877 is equivalent to 3878 __attribute__ ((sentinel(0))) 3879 @end smallexample 3880 3881 The attribute is automatically set with a position of 0 for the built-in 3882 functions @code{execl} and @code{execlp}. The built-in function 3883 @code{execle} has the attribute set with a position of 1. 3884 3885 A valid @code{NULL} in this context is defined as zero with any object 3886 pointer type. If your system defines the @code{NULL} macro with 3887 an integer type then you need to add an explicit cast. During 3888 installation GCC replaces the system @code{<stddef.h>} header with 3889 a copy that redefines NULL appropriately. 3890 3891 The warnings for missing or incorrect sentinels are enabled with 3892 @option{-Wformat}. 3893 3894 @item simd 3895 @itemx simd("@var{mask}") 3896 @cindex @code{simd} function attribute 3897 This attribute enables creation of one or more function versions that 3898 can process multiple arguments using SIMD instructions from a 3899 single invocation. Specifying this attribute allows compiler to 3900 assume that such versions are available at link time (provided 3901 in the same or another translation unit). Generated versions are 3902 target-dependent and described in the corresponding Vector ABI document. For 3903 x86_64 target this document can be found 3904 @w{@uref{https://sourceware.org/glibc/wiki/libmvec?action=AttachFile&do=view&target=VectorABI.txt,here}}. 3905 3906 The optional argument @var{mask} may have the value 3907 @code{notinbranch} or @code{inbranch}, 3908 and instructs the compiler to generate non-masked or masked 3909 clones correspondingly. By default, all clones are generated. 3910 3911 If the attribute is specified and @code{#pragma omp declare simd} is 3912 present on a declaration and the @option{-fopenmp} or @option{-fopenmp-simd} 3913 switch is specified, then the attribute is ignored. 3914 3915 @item stack_protect 3916 @cindex @code{stack_protect} function attribute 3917 This attribute adds stack protection code to the function if 3918 flags @option{-fstack-protector}, @option{-fstack-protector-strong} 3919 or @option{-fstack-protector-explicit} are set. 3920 3921 @item no_stack_protector 3922 @cindex @code{no_stack_protector} function attribute 3923 This attribute prevents stack protection code for the function. 3924 3925 @item target (@var{string}, @dots{}) 3926 @cindex @code{target} function attribute 3927 Multiple target back ends implement the @code{target} attribute 3928 to specify that a function is to 3929 be compiled with different target options than specified on the 3930 command line. The original target command-line options are ignored. 3931 One or more strings can be provided as arguments. 3932 Each string consists of one or more comma-separated suffixes to 3933 the @code{-m} prefix jointly forming the name of a machine-dependent 3934 option. @xref{Submodel Options,,Machine-Dependent Options}. 3935 3936 The @code{target} attribute can be used for instance to have a function 3937 compiled with a different ISA (instruction set architecture) than the 3938 default. @samp{#pragma GCC target} can be used to specify target-specific 3939 options for more than one function. @xref{Function Specific Option Pragmas}, 3940 for details about the pragma. 3941 3942 For instance, on an x86, you could declare one function with the 3943 @code{target("sse4.1,arch=core2")} attribute and another with 3944 @code{target("sse4a,arch=amdfam10")}. This is equivalent to 3945 compiling the first function with @option{-msse4.1} and 3946 @option{-march=core2} options, and the second function with 3947 @option{-msse4a} and @option{-march=amdfam10} options. It is up to you 3948 to make sure that a function is only invoked on a machine that 3949 supports the particular ISA it is compiled for (for example by using 3950 @code{cpuid} on x86 to determine what feature bits and architecture 3951 family are used). 3952 3953 @smallexample 3954 int core2_func (void) __attribute__ ((__target__ ("arch=core2"))); 3955 int sse3_func (void) __attribute__ ((__target__ ("sse3"))); 3956 @end smallexample 3957 3958 Providing multiple strings as arguments separated by commas to specify 3959 multiple options is equivalent to separating the option suffixes with 3960 a comma (@samp{,}) within a single string. Spaces are not permitted 3961 within the strings. 3962 3963 The options supported are specific to each target; refer to @ref{x86 3964 Function Attributes}, @ref{PowerPC Function Attributes}, 3965 @ref{ARM Function Attributes}, @ref{AArch64 Function Attributes}, 3966 @ref{Nios II Function Attributes}, and @ref{S/390 Function Attributes} 3967 for details. 3968 3969 @item symver ("@var{name2}@@@var{nodename}") 3970 @cindex @code{symver} function attribute 3971 On ELF targets this attribute creates a symbol version. The @var{name2} part 3972 of the parameter is the actual name of the symbol by which it will be 3973 externally referenced. The @code{nodename} portion should be the name of a 3974 node specified in the version script supplied to the linker when building a 3975 shared library. Versioned symbol must be defined and must be exported with 3976 default visibility. 3977 3978 @smallexample 3979 __attribute__ ((__symver__ ("foo@@VERS_1"))) int 3980 foo_v1 (void) 3981 @{ 3982 @} 3983 @end smallexample 3984 3985 Will produce a @code{.symver foo_v1, foo@@VERS_1} directive in the assembler 3986 output. 3987 3988 One can also define multiple version for a given symbol 3989 (starting from binutils 2.35). 3990 3991 @smallexample 3992 __attribute__ ((__symver__ ("foo@@VERS_2"), __symver__ ("foo@@VERS_3"))) 3993 int symver_foo_v1 (void) 3994 @{ 3995 @} 3996 @end smallexample 3997 3998 This example creates a symbol name @code{symver_foo_v1} 3999 which will be version @code{VERS_2} and @code{VERS_3} of @code{foo}. 4000 4001 If you have an older release of binutils, then symbol alias needs to 4002 be used: 4003 4004 @smallexample 4005 __attribute__ ((__symver__ ("foo@@VERS_2"))) 4006 int foo_v1 (void) 4007 @{ 4008 return 0; 4009 @} 4010 4011 __attribute__ ((__symver__ ("foo@@VERS_3"))) 4012 __attribute__ ((alias ("foo_v1"))) 4013 int symver_foo_v1 (void); 4014 @end smallexample 4015 4016 Finally if the parameter is @code{"@var{name2}@@@@@var{nodename}"} then in 4017 addition to creating a symbol version (as if 4018 @code{"@var{name2}@@@var{nodename}"} was used) the version will be also used 4019 to resolve @var{name2} by the linker. 4020 4021 @item tainted_args 4022 @cindex @code{tainted_args} function attribute 4023 The @code{tainted_args} attribute is used to specify that a function is called 4024 in a way that requires sanitization of its arguments, such as a system 4025 call in an operating system kernel. Such a function can be considered part 4026 of the ``attack surface'' of the program. The attribute can be used both 4027 on function declarations, and on field declarations containing function 4028 pointers. In the latter case, any function used as an initializer of 4029 such a callback field will be treated as being called with tainted 4030 arguments. 4031 4032 The analyzer will pay particular attention to such functions when both 4033 @option{-fanalyzer} and @option{-fanalyzer-checker=taint} are supplied, 4034 potentially issuing warnings guarded by 4035 @option{-Wanalyzer-tainted-allocation-size}, 4036 @option{-Wanalyzer-tainted-array-index}, 4037 @option{-Wanalyzer-tainted-divisor}, 4038 @option{-Wanalyzer-tainted-offset}, 4039 and @option{-Wanalyzer-tainted-size}. 4040 4041 @item target_clones (@var{options}) 4042 @cindex @code{target_clones} function attribute 4043 The @code{target_clones} attribute is used to specify that a function 4044 be cloned into multiple versions compiled with different target options 4045 than specified on the command line. The supported options and restrictions 4046 are the same as for @code{target} attribute. 4047 4048 For instance, on an x86, you could compile a function with 4049 @code{target_clones("sse4.1,avx")}. GCC creates two function clones, 4050 one compiled with @option{-msse4.1} and another with @option{-mavx}. 4051 4052 On a PowerPC, you can compile a function with 4053 @code{target_clones("cpu=power9,default")}. GCC will create two 4054 function clones, one compiled with @option{-mcpu=power9} and another 4055 with the default options. GCC must be configured to use GLIBC 2.23 or 4056 newer in order to use the @code{target_clones} attribute. 4057 4058 It also creates a resolver function (see 4059 the @code{ifunc} attribute above) that dynamically selects a clone 4060 suitable for current architecture. The resolver is created only if there 4061 is a usage of a function with @code{target_clones} attribute. 4062 4063 Note that any subsequent call of a function without @code{target_clone} 4064 from a @code{target_clone} caller will not lead to copying 4065 (target clone) of the called function. 4066 If you want to enforce such behaviour, 4067 we recommend declaring the calling function with the @code{flatten} attribute? 4068 4069 @item unused 4070 @cindex @code{unused} function attribute 4071 This attribute, attached to a function, means that the function is meant 4072 to be possibly unused. GCC does not produce a warning for this 4073 function. 4074 4075 @item used 4076 @cindex @code{used} function attribute 4077 This attribute, attached to a function, means that code must be emitted 4078 for the function even if it appears that the function is not referenced. 4079 This is useful, for example, when the function is referenced only in 4080 inline assembly. 4081 4082 When applied to a member function of a C++ class template, the 4083 attribute also means that the function is instantiated if the 4084 class itself is instantiated. 4085 4086 @item retain 4087 @cindex @code{retain} function attribute 4088 For ELF targets that support the GNU or FreeBSD OSABIs, this attribute 4089 will save the function from linker garbage collection. To support 4090 this behavior, functions that have not been placed in specific sections 4091 (e.g. by the @code{section} attribute, or the @code{-ffunction-sections} 4092 option), will be placed in new, unique sections. 4093 4094 This additional functionality requires Binutils version 2.36 or later. 4095 4096 @item visibility ("@var{visibility_type}") 4097 @cindex @code{visibility} function attribute 4098 This attribute affects the linkage of the declaration to which it is attached. 4099 It can be applied to variables (@pxref{Common Variable Attributes}) and types 4100 (@pxref{Common Type Attributes}) as well as functions. 4101 4102 There are four supported @var{visibility_type} values: default, 4103 hidden, protected or internal visibility. 4104 4105 @smallexample 4106 void __attribute__ ((visibility ("protected"))) 4107 f () @{ /* @r{Do something.} */; @} 4108 int i __attribute__ ((visibility ("hidden"))); 4109 @end smallexample 4110 4111 The possible values of @var{visibility_type} correspond to the 4112 visibility settings in the ELF gABI. 4113 4114 @table @code 4115 @c keep this list of visibilities in alphabetical order. 4116 4117 @item default 4118 Default visibility is the normal case for the object file format. 4119 This value is available for the visibility attribute to override other 4120 options that may change the assumed visibility of entities. 4121 4122 On ELF, default visibility means that the declaration is visible to other 4123 modules and, in shared libraries, means that the declared entity may be 4124 overridden. 4125 4126 On Darwin, default visibility means that the declaration is visible to 4127 other modules. 4128 4129 Default visibility corresponds to ``external linkage'' in the language. 4130 4131 @item hidden 4132 Hidden visibility indicates that the entity declared has a new 4133 form of linkage, which we call ``hidden linkage''. Two 4134 declarations of an object with hidden linkage refer to the same object 4135 if they are in the same shared object. 4136 4137 @item internal 4138 Internal visibility is like hidden visibility, but with additional 4139 processor specific semantics. Unless otherwise specified by the 4140 psABI, GCC defines internal visibility to mean that a function is 4141 @emph{never} called from another module. Compare this with hidden 4142 functions which, while they cannot be referenced directly by other 4143 modules, can be referenced indirectly via function pointers. By 4144 indicating that a function cannot be called from outside the module, 4145 GCC may for instance omit the load of a PIC register since it is known 4146 that the calling function loaded the correct value. 4147 4148 @item protected 4149 Protected visibility is like default visibility except that it 4150 indicates that references within the defining module bind to the 4151 definition in that module. That is, the declared entity cannot be 4152 overridden by another module. 4153 4154 @end table 4155 4156 All visibilities are supported on many, but not all, ELF targets 4157 (supported when the assembler supports the @samp{.visibility} 4158 pseudo-op). Default visibility is supported everywhere. Hidden 4159 visibility is supported on Darwin targets. 4160 4161 The visibility attribute should be applied only to declarations that 4162 would otherwise have external linkage. The attribute should be applied 4163 consistently, so that the same entity should not be declared with 4164 different settings of the attribute. 4165 4166 In C++, the visibility attribute applies to types as well as functions 4167 and objects, because in C++ types have linkage. A class must not have 4168 greater visibility than its non-static data member types and bases, 4169 and class members default to the visibility of their class. Also, a 4170 declaration without explicit visibility is limited to the visibility 4171 of its type. 4172 4173 In C++, you can mark member functions and static member variables of a 4174 class with the visibility attribute. This is useful if you know a 4175 particular method or static member variable should only be used from 4176 one shared object; then you can mark it hidden while the rest of the 4177 class has default visibility. Care must be taken to avoid breaking 4178 the One Definition Rule; for example, it is usually not useful to mark 4179 an inline method as hidden without marking the whole class as hidden. 4180 4181 A C++ namespace declaration can also have the visibility attribute. 4182 4183 @smallexample 4184 namespace nspace1 __attribute__ ((visibility ("protected"))) 4185 @{ /* @r{Do something.} */; @} 4186 @end smallexample 4187 4188 This attribute applies only to the particular namespace body, not to 4189 other definitions of the same namespace; it is equivalent to using 4190 @samp{#pragma GCC visibility} before and after the namespace 4191 definition (@pxref{Visibility Pragmas}). 4192 4193 In C++, if a template argument has limited visibility, this 4194 restriction is implicitly propagated to the template instantiation. 4195 Otherwise, template instantiations and specializations default to the 4196 visibility of their template. 4197 4198 If both the template and enclosing class have explicit visibility, the 4199 visibility from the template is used. 4200 4201 @item warn_unused_result 4202 @cindex @code{warn_unused_result} function attribute 4203 The @code{warn_unused_result} attribute causes a warning to be emitted 4204 if a caller of the function with this attribute does not use its 4205 return value. This is useful for functions where not checking 4206 the result is either a security problem or always a bug, such as 4207 @code{realloc}. 4208 4209 @smallexample 4210 int fn () __attribute__ ((warn_unused_result)); 4211 int foo () 4212 @{ 4213 if (fn () < 0) return -1; 4214 fn (); 4215 return 0; 4216 @} 4217 @end smallexample 4218 4219 @noindent 4220 results in warning on line 5. 4221 4222 @item weak 4223 @cindex @code{weak} function attribute 4224 The @code{weak} attribute causes a declaration of an external symbol 4225 to be emitted as a weak symbol rather than a global. This is primarily 4226 useful in defining library functions that can be overridden in user code, 4227 though it can also be used with non-function declarations. The overriding 4228 symbol must have the same type as the weak symbol. In addition, if it 4229 designates a variable it must also have the same size and alignment as 4230 the weak symbol. Weak symbols are supported for ELF targets, and also 4231 for a.out targets when using the GNU assembler and linker. 4232 4233 @item weakref 4234 @itemx weakref ("@var{target}") 4235 @cindex @code{weakref} function attribute 4236 The @code{weakref} attribute marks a declaration as a weak reference. 4237 Without arguments, it should be accompanied by an @code{alias} attribute 4238 naming the target symbol. Alternatively, @var{target} may be given as 4239 an argument to @code{weakref} itself, naming the target definition of 4240 the alias. The @var{target} must have the same type as the declaration. 4241 In addition, if it designates a variable it must also have the same size 4242 and alignment as the declaration. In either form of the declaration 4243 @code{weakref} implicitly marks the declared symbol as @code{weak}. Without 4244 a @var{target} given as an argument to @code{weakref} or to @code{alias}, 4245 @code{weakref} is equivalent to @code{weak} (in that case the declaration 4246 may be @code{extern}). 4247 4248 @smallexample 4249 /* Given the declaration: */ 4250 extern int y (void); 4251 4252 /* the following... */ 4253 static int x (void) __attribute__ ((weakref ("y"))); 4254 4255 /* is equivalent to... */ 4256 static int x (void) __attribute__ ((weakref, alias ("y"))); 4257 4258 /* or, alternatively, to... */ 4259 static int x (void) __attribute__ ((weakref)); 4260 static int x (void) __attribute__ ((alias ("y"))); 4261 @end smallexample 4262 4263 A weak reference is an alias that does not by itself require a 4264 definition to be given for the target symbol. If the target symbol is 4265 only referenced through weak references, then it becomes a @code{weak} 4266 undefined symbol. If it is directly referenced, however, then such 4267 strong references prevail, and a definition is required for the 4268 symbol, not necessarily in the same translation unit. 4269 4270 The effect is equivalent to moving all references to the alias to a 4271 separate translation unit, renaming the alias to the aliased symbol, 4272 declaring it as weak, compiling the two separate translation units and 4273 performing a link with relocatable output (i.e.@: @code{ld -r}) on them. 4274 4275 A declaration to which @code{weakref} is attached and that is associated 4276 with a named @code{target} must be @code{static}. 4277 4278 @item zero_call_used_regs ("@var{choice}") 4279 @cindex @code{zero_call_used_regs} function attribute 4280 4281 The @code{zero_call_used_regs} attribute causes the compiler to zero 4282 a subset of all call-used registers@footnote{A ``call-used'' register 4283 is a register whose contents can be changed by a function call; 4284 therefore, a caller cannot assume that the register has the same contents 4285 on return from the function as it had before calling the function. Such 4286 registers are also called ``call-clobbered'', ``caller-saved'', or 4287 ``volatile''.} at function return. 4288 This is used to increase program security by either mitigating 4289 Return-Oriented Programming (ROP) attacks or preventing information leakage 4290 through registers. 4291 4292 In order to satisfy users with different security needs and control the 4293 run-time overhead at the same time, the @var{choice} parameter provides a 4294 flexible way to choose the subset of the call-used registers to be zeroed. 4295 The three basic values of @var{choice} are: 4296 4297 @itemize @bullet 4298 @item 4299 @samp{skip} doesn't zero any call-used registers. 4300 4301 @item 4302 @samp{used} only zeros call-used registers that are used in the function. 4303 A ``used'' register is one whose content has been set or referenced in 4304 the function. 4305 4306 @item 4307 @samp{all} zeros all call-used registers. 4308 @end itemize 4309 4310 In addition to these three basic choices, it is possible to modify 4311 @samp{used} or @samp{all} as follows: 4312 4313 @itemize @bullet 4314 @item 4315 Adding @samp{-gpr} restricts the zeroing to general-purpose registers. 4316 4317 @item 4318 Adding @samp{-arg} restricts the zeroing to registers that can sometimes 4319 be used to pass function arguments. This includes all argument registers 4320 defined by the platform's calling conversion, regardless of whether the 4321 function uses those registers for function arguments or not. 4322 @end itemize 4323 4324 The modifiers can be used individually or together. If they are used 4325 together, they must appear in the order above. 4326 4327 The full list of @var{choice}s is therefore: 4328 4329 @table @code 4330 @item skip 4331 doesn't zero any call-used register. 4332 4333 @item used 4334 only zeros call-used registers that are used in the function. 4335 4336 @item used-gpr 4337 only zeros call-used general purpose registers that are used in the function. 4338 4339 @item used-arg 4340 only zeros call-used registers that are used in the function and pass arguments. 4341 4342 @item used-gpr-arg 4343 only zeros call-used general purpose registers that are used in the function 4344 and pass arguments. 4345 4346 @item all 4347 zeros all call-used registers. 4348 4349 @item all-gpr 4350 zeros all call-used general purpose registers. 4351 4352 @item all-arg 4353 zeros all call-used registers that pass arguments. 4354 4355 @item all-gpr-arg 4356 zeros all call-used general purpose registers that pass 4357 arguments. 4358 @end table 4359 4360 Of this list, @samp{used-arg}, @samp{used-gpr-arg}, @samp{all-arg}, 4361 and @samp{all-gpr-arg} are mainly used for ROP mitigation. 4362 4363 The default for the attribute is controlled by @option{-fzero-call-used-regs}. 4364 @end table 4365 4366 @c This is the end of the target-independent attribute table 4367 4368 @node AArch64 Function Attributes 4369 @subsection AArch64 Function Attributes 4370 4371 The following target-specific function attributes are available for the 4372 AArch64 target. For the most part, these options mirror the behavior of 4373 similar command-line options (@pxref{AArch64 Options}), but on a 4374 per-function basis. 4375 4376 @table @code 4377 @item general-regs-only 4378 @cindex @code{general-regs-only} function attribute, AArch64 4379 Indicates that no floating-point or Advanced SIMD registers should be 4380 used when generating code for this function. If the function explicitly 4381 uses floating-point code, then the compiler gives an error. This is 4382 the same behavior as that of the command-line option 4383 @option{-mgeneral-regs-only}. 4384 4385 @item fix-cortex-a53-835769 4386 @cindex @code{fix-cortex-a53-835769} function attribute, AArch64 4387 Indicates that the workaround for the Cortex-A53 erratum 835769 should be 4388 applied to this function. To explicitly disable the workaround for this 4389 function specify the negated form: @code{no-fix-cortex-a53-835769}. 4390 This corresponds to the behavior of the command line options 4391 @option{-mfix-cortex-a53-835769} and @option{-mno-fix-cortex-a53-835769}. 4392 4393 @item cmodel= 4394 @cindex @code{cmodel=} function attribute, AArch64 4395 Indicates that code should be generated for a particular code model for 4396 this function. The behavior and permissible arguments are the same as 4397 for the command line option @option{-mcmodel=}. 4398 4399 @item strict-align 4400 @itemx no-strict-align 4401 @cindex @code{strict-align} function attribute, AArch64 4402 @code{strict-align} indicates that the compiler should not assume that unaligned 4403 memory references are handled by the system. To allow the compiler to assume 4404 that aligned memory references are handled by the system, the inverse attribute 4405 @code{no-strict-align} can be specified. The behavior is same as for the 4406 command-line option @option{-mstrict-align} and @option{-mno-strict-align}. 4407 4408 @item omit-leaf-frame-pointer 4409 @cindex @code{omit-leaf-frame-pointer} function attribute, AArch64 4410 Indicates that the frame pointer should be omitted for a leaf function call. 4411 To keep the frame pointer, the inverse attribute 4412 @code{no-omit-leaf-frame-pointer} can be specified. These attributes have 4413 the same behavior as the command-line options @option{-momit-leaf-frame-pointer} 4414 and @option{-mno-omit-leaf-frame-pointer}. 4415 4416 @item tls-dialect= 4417 @cindex @code{tls-dialect=} function attribute, AArch64 4418 Specifies the TLS dialect to use for this function. The behavior and 4419 permissible arguments are the same as for the command-line option 4420 @option{-mtls-dialect=}. 4421 4422 @item arch= 4423 @cindex @code{arch=} function attribute, AArch64 4424 Specifies the architecture version and architectural extensions to use 4425 for this function. The behavior and permissible arguments are the same as 4426 for the @option{-march=} command-line option. 4427 4428 @item tune= 4429 @cindex @code{tune=} function attribute, AArch64 4430 Specifies the core for which to tune the performance of this function. 4431 The behavior and permissible arguments are the same as for the @option{-mtune=} 4432 command-line option. 4433 4434 @item cpu= 4435 @cindex @code{cpu=} function attribute, AArch64 4436 Specifies the core for which to tune the performance of this function and also 4437 whose architectural features to use. The behavior and valid arguments are the 4438 same as for the @option{-mcpu=} command-line option. 4439 4440 @item sign-return-address 4441 @cindex @code{sign-return-address} function attribute, AArch64 4442 Select the function scope on which return address signing will be applied. The 4443 behavior and permissible arguments are the same as for the command-line option 4444 @option{-msign-return-address=}. The default value is @code{none}. This 4445 attribute is deprecated. The @code{branch-protection} attribute should 4446 be used instead. 4447 4448 @item branch-protection 4449 @cindex @code{branch-protection} function attribute, AArch64 4450 Select the function scope on which branch protection will be applied. The 4451 behavior and permissible arguments are the same as for the command-line option 4452 @option{-mbranch-protection=}. The default value is @code{none}. 4453 4454 @item outline-atomics 4455 @cindex @code{outline-atomics} function attribute, AArch64 4456 Enable or disable calls to out-of-line helpers to implement atomic operations. 4457 This corresponds to the behavior of the command line options 4458 @option{-moutline-atomics} and @option{-mno-outline-atomics}. 4459 4460 @end table 4461 4462 The above target attributes can be specified as follows: 4463 4464 @smallexample 4465 __attribute__((target("@var{attr-string}"))) 4466 int 4467 f (int a) 4468 @{ 4469 return a + 5; 4470 @} 4471 @end smallexample 4472 4473 where @code{@var{attr-string}} is one of the attribute strings specified above. 4474 4475 Additionally, the architectural extension string may be specified on its 4476 own. This can be used to turn on and off particular architectural extensions 4477 without having to specify a particular architecture version or core. Example: 4478 4479 @smallexample 4480 __attribute__((target("+crc+nocrypto"))) 4481 int 4482 foo (int a) 4483 @{ 4484 return a + 5; 4485 @} 4486 @end smallexample 4487 4488 In this example @code{target("+crc+nocrypto")} enables the @code{crc} 4489 extension and disables the @code{crypto} extension for the function @code{foo} 4490 without modifying an existing @option{-march=} or @option{-mcpu} option. 4491 4492 Multiple target function attributes can be specified by separating them with 4493 a comma. For example: 4494 @smallexample 4495 __attribute__((target("arch=armv8-a+crc+crypto,tune=cortex-a53"))) 4496 int 4497 foo (int a) 4498 @{ 4499 return a + 5; 4500 @} 4501 @end smallexample 4502 4503 is valid and compiles function @code{foo} for ARMv8-A with @code{crc} 4504 and @code{crypto} extensions and tunes it for @code{cortex-a53}. 4505 4506 @subsubsection Inlining rules 4507 Specifying target attributes on individual functions or performing link-time 4508 optimization across translation units compiled with different target options 4509 can affect function inlining rules: 4510 4511 In particular, a caller function can inline a callee function only if the 4512 architectural features available to the callee are a subset of the features 4513 available to the caller. 4514 For example: A function @code{foo} compiled with @option{-march=armv8-a+crc}, 4515 or tagged with the equivalent @code{arch=armv8-a+crc} attribute, 4516 can inline a function @code{bar} compiled with @option{-march=armv8-a+nocrc} 4517 because the all the architectural features that function @code{bar} requires 4518 are available to function @code{foo}. Conversely, function @code{bar} cannot 4519 inline function @code{foo}. 4520 4521 Additionally inlining a function compiled with @option{-mstrict-align} into a 4522 function compiled without @code{-mstrict-align} is not allowed. 4523 However, inlining a function compiled without @option{-mstrict-align} into a 4524 function compiled with @option{-mstrict-align} is allowed. 4525 4526 Note that CPU tuning options and attributes such as the @option{-mcpu=}, 4527 @option{-mtune=} do not inhibit inlining unless the CPU specified by the 4528 @option{-mcpu=} option or the @code{cpu=} attribute conflicts with the 4529 architectural feature rules specified above. 4530 4531 @node AMD GCN Function Attributes 4532 @subsection AMD GCN Function Attributes 4533 4534 These function attributes are supported by the AMD GCN back end: 4535 4536 @table @code 4537 @item amdgpu_hsa_kernel 4538 @cindex @code{amdgpu_hsa_kernel} function attribute, AMD GCN 4539 This attribute indicates that the corresponding function should be compiled as 4540 a kernel function, that is an entry point that can be invoked from the host 4541 via the HSA runtime library. By default functions are only callable only from 4542 other GCN functions. 4543 4544 This attribute is implicitly applied to any function named @code{main}, using 4545 default parameters. 4546 4547 Kernel functions may return an integer value, which will be written to a 4548 conventional place within the HSA "kernargs" region. 4549 4550 The attribute parameters configure what values are passed into the kernel 4551 function by the GPU drivers, via the initial register state. Some values are 4552 used by the compiler, and therefore forced on. Enabling other options may 4553 break assumptions in the compiler and/or run-time libraries. 4554 4555 @table @code 4556 @item private_segment_buffer 4557 Set @code{enable_sgpr_private_segment_buffer} flag. Always on (required to 4558 locate the stack). 4559 4560 @item dispatch_ptr 4561 Set @code{enable_sgpr_dispatch_ptr} flag. Always on (required to locate the 4562 launch dimensions). 4563 4564 @item queue_ptr 4565 Set @code{enable_sgpr_queue_ptr} flag. Always on (required to convert address 4566 spaces). 4567 4568 @item kernarg_segment_ptr 4569 Set @code{enable_sgpr_kernarg_segment_ptr} flag. Always on (required to 4570 locate the kernel arguments, "kernargs"). 4571 4572 @item dispatch_id 4573 Set @code{enable_sgpr_dispatch_id} flag. 4574 4575 @item flat_scratch_init 4576 Set @code{enable_sgpr_flat_scratch_init} flag. 4577 4578 @item private_segment_size 4579 Set @code{enable_sgpr_private_segment_size} flag. 4580 4581 @item grid_workgroup_count_X 4582 Set @code{enable_sgpr_grid_workgroup_count_x} flag. Always on (required to 4583 use OpenACC/OpenMP). 4584 4585 @item grid_workgroup_count_Y 4586 Set @code{enable_sgpr_grid_workgroup_count_y} flag. 4587 4588 @item grid_workgroup_count_Z 4589 Set @code{enable_sgpr_grid_workgroup_count_z} flag. 4590 4591 @item workgroup_id_X 4592 Set @code{enable_sgpr_workgroup_id_x} flag. 4593 4594 @item workgroup_id_Y 4595 Set @code{enable_sgpr_workgroup_id_y} flag. 4596 4597 @item workgroup_id_Z 4598 Set @code{enable_sgpr_workgroup_id_z} flag. 4599 4600 @item workgroup_info 4601 Set @code{enable_sgpr_workgroup_info} flag. 4602 4603 @item private_segment_wave_offset 4604 Set @code{enable_sgpr_private_segment_wave_byte_offset} flag. Always on 4605 (required to locate the stack). 4606 4607 @item work_item_id_X 4608 Set @code{enable_vgpr_workitem_id} parameter. Always on (can't be disabled). 4609 4610 @item work_item_id_Y 4611 Set @code{enable_vgpr_workitem_id} parameter. Always on (required to enable 4612 vectorization.) 4613 4614 @item work_item_id_Z 4615 Set @code{enable_vgpr_workitem_id} parameter. Always on (required to use 4616 OpenACC/OpenMP). 4617 4618 @end table 4619 @end table 4620 4621 @node ARC Function Attributes 4622 @subsection ARC Function Attributes 4623 4624 These function attributes are supported by the ARC back end: 4625 4626 @table @code 4627 @item interrupt 4628 @cindex @code{interrupt} function attribute, ARC 4629 Use this attribute to indicate 4630 that the specified function is an interrupt handler. The compiler generates 4631 function entry and exit sequences suitable for use in an interrupt handler 4632 when this attribute is present. 4633 4634 On the ARC, you must specify the kind of interrupt to be handled 4635 in a parameter to the interrupt attribute like this: 4636 4637 @smallexample 4638 void f () __attribute__ ((interrupt ("ilink1"))); 4639 @end smallexample 4640 4641 Permissible values for this parameter are: @w{@code{ilink1}} and 4642 @w{@code{ilink2}} for ARCv1 architecture, and @w{@code{ilink}} and 4643 @w{@code{firq}} for ARCv2 architecture. 4644 4645 @item long_call 4646 @itemx medium_call 4647 @itemx short_call 4648 @cindex @code{long_call} function attribute, ARC 4649 @cindex @code{medium_call} function attribute, ARC 4650 @cindex @code{short_call} function attribute, ARC 4651 @cindex indirect calls, ARC 4652 These attributes specify how a particular function is called. 4653 These attributes override the 4654 @option{-mlong-calls} and @option{-mmedium-calls} (@pxref{ARC Options}) 4655 command-line switches and @code{#pragma long_calls} settings. 4656 4657 For ARC, a function marked with the @code{long_call} attribute is 4658 always called using register-indirect jump-and-link instructions, 4659 thereby enabling the called function to be placed anywhere within the 4660 32-bit address space. A function marked with the @code{medium_call} 4661 attribute will always be close enough to be called with an unconditional 4662 branch-and-link instruction, which has a 25-bit offset from 4663 the call site. A function marked with the @code{short_call} 4664 attribute will always be close enough to be called with a conditional 4665 branch-and-link instruction, which has a 21-bit offset from 4666 the call site. 4667 4668 @item jli_always 4669 @cindex @code{jli_always} function attribute, ARC 4670 Forces a particular function to be called using @code{jli} 4671 instruction. The @code{jli} instruction makes use of a table stored 4672 into @code{.jlitab} section, which holds the location of the functions 4673 which are addressed using this instruction. 4674 4675 @item jli_fixed 4676 @cindex @code{jli_fixed} function attribute, ARC 4677 Identical like the above one, but the location of the function in the 4678 @code{jli} table is known and given as an attribute parameter. 4679 4680 @item secure_call 4681 @cindex @code{secure_call} function attribute, ARC 4682 This attribute allows one to mark secure-code functions that are 4683 callable from normal mode. The location of the secure call function 4684 into the @code{sjli} table needs to be passed as argument. 4685 4686 @item naked 4687 @cindex @code{naked} function attribute, ARC 4688 This attribute allows the compiler to construct the requisite function 4689 declaration, while allowing the body of the function to be assembly 4690 code. The specified function will not have prologue/epilogue 4691 sequences generated by the compiler. Only basic @code{asm} statements 4692 can safely be included in naked functions (@pxref{Basic Asm}). While 4693 using extended @code{asm} or a mixture of basic @code{asm} and C code 4694 may appear to work, they cannot be depended upon to work reliably and 4695 are not supported. 4696 4697 @end table 4698 4699 @node ARM Function Attributes 4700 @subsection ARM Function Attributes 4701 4702 These function attributes are supported for ARM targets: 4703 4704 @table @code 4705 4706 @item general-regs-only 4707 @cindex @code{general-regs-only} function attribute, ARM 4708 Indicates that no floating-point or Advanced SIMD registers should be 4709 used when generating code for this function. If the function explicitly 4710 uses floating-point code, then the compiler gives an error. This is 4711 the same behavior as that of the command-line option 4712 @option{-mgeneral-regs-only}. 4713 4714 @item interrupt 4715 @cindex @code{interrupt} function attribute, ARM 4716 Use this attribute to indicate 4717 that the specified function is an interrupt handler. The compiler generates 4718 function entry and exit sequences suitable for use in an interrupt handler 4719 when this attribute is present. 4720 4721 You can specify the kind of interrupt to be handled by 4722 adding an optional parameter to the interrupt attribute like this: 4723 4724 @smallexample 4725 void f () __attribute__ ((interrupt ("IRQ"))); 4726 @end smallexample 4727 4728 @noindent 4729 Permissible values for this parameter are: @code{IRQ}, @code{FIQ}, 4730 @code{SWI}, @code{ABORT} and @code{UNDEF}. 4731 4732 On ARMv7-M the interrupt type is ignored, and the attribute means the function 4733 may be called with a word-aligned stack pointer. 4734 4735 @item isr 4736 @cindex @code{isr} function attribute, ARM 4737 Use this attribute on ARM to write Interrupt Service Routines. This is an 4738 alias to the @code{interrupt} attribute above. 4739 4740 @item long_call 4741 @itemx short_call 4742 @cindex @code{long_call} function attribute, ARM 4743 @cindex @code{short_call} function attribute, ARM 4744 @cindex indirect calls, ARM 4745 These attributes specify how a particular function is called. 4746 These attributes override the 4747 @option{-mlong-calls} (@pxref{ARM Options}) 4748 command-line switch and @code{#pragma long_calls} settings. For ARM, the 4749 @code{long_call} attribute indicates that the function might be far 4750 away from the call site and require a different (more expensive) 4751 calling sequence. The @code{short_call} attribute always places 4752 the offset to the function from the call site into the @samp{BL} 4753 instruction directly. 4754 4755 @item naked 4756 @cindex @code{naked} function attribute, ARM 4757 This attribute allows the compiler to construct the 4758 requisite function declaration, while allowing the body of the 4759 function to be assembly code. The specified function will not have 4760 prologue/epilogue sequences generated by the compiler. Only basic 4761 @code{asm} statements can safely be included in naked functions 4762 (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of 4763 basic @code{asm} and C code may appear to work, they cannot be 4764 depended upon to work reliably and are not supported. 4765 4766 @item pcs 4767 @cindex @code{pcs} function attribute, ARM 4768 4769 The @code{pcs} attribute can be used to control the calling convention 4770 used for a function on ARM. The attribute takes an argument that specifies 4771 the calling convention to use. 4772 4773 When compiling using the AAPCS ABI (or a variant of it) then valid 4774 values for the argument are @code{"aapcs"} and @code{"aapcs-vfp"}. In 4775 order to use a variant other than @code{"aapcs"} then the compiler must 4776 be permitted to use the appropriate co-processor registers (i.e., the 4777 VFP registers must be available in order to use @code{"aapcs-vfp"}). 4778 For example, 4779 4780 @smallexample 4781 /* Argument passed in r0, and result returned in r0+r1. */ 4782 double f2d (float) __attribute__((pcs("aapcs"))); 4783 @end smallexample 4784 4785 Variadic functions always use the @code{"aapcs"} calling convention and 4786 the compiler rejects attempts to specify an alternative. 4787 4788 @item target (@var{options}) 4789 @cindex @code{target} function attribute 4790 As discussed in @ref{Common Function Attributes}, this attribute 4791 allows specification of target-specific compilation options. 4792 4793 On ARM, the following options are allowed: 4794 4795 @table @samp 4796 @item thumb 4797 @cindex @code{target("thumb")} function attribute, ARM 4798 Force code generation in the Thumb (T16/T32) ISA, depending on the 4799 architecture level. 4800 4801 @item arm 4802 @cindex @code{target("arm")} function attribute, ARM 4803 Force code generation in the ARM (A32) ISA. 4804 4805 Functions from different modes can be inlined in the caller's mode. 4806 4807 @item fpu= 4808 @cindex @code{target("fpu=")} function attribute, ARM 4809 Specifies the fpu for which to tune the performance of this function. 4810 The behavior and permissible arguments are the same as for the @option{-mfpu=} 4811 command-line option. 4812 4813 @item arch= 4814 @cindex @code{arch=} function attribute, ARM 4815 Specifies the architecture version and architectural extensions to use 4816 for this function. The behavior and permissible arguments are the same as 4817 for the @option{-march=} command-line option. 4818 4819 The above target attributes can be specified as follows: 4820 4821 @smallexample 4822 __attribute__((target("arch=armv8-a+crc"))) 4823 int 4824 f (int a) 4825 @{ 4826 return a + 5; 4827 @} 4828 @end smallexample 4829 4830 Additionally, the architectural extension string may be specified on its 4831 own. This can be used to turn on and off particular architectural extensions 4832 without having to specify a particular architecture version or core. Example: 4833 4834 @smallexample 4835 __attribute__((target("+crc+nocrypto"))) 4836 int 4837 foo (int a) 4838 @{ 4839 return a + 5; 4840 @} 4841 @end smallexample 4842 4843 In this example @code{target("+crc+nocrypto")} enables the @code{crc} 4844 extension and disables the @code{crypto} extension for the function @code{foo} 4845 without modifying an existing @option{-march=} or @option{-mcpu} option. 4846 4847 @end table 4848 4849 @end table 4850 4851 @node AVR Function Attributes 4852 @subsection AVR Function Attributes 4853 4854 These function attributes are supported by the AVR back end: 4855 4856 @table @code 4857 @item interrupt 4858 @cindex @code{interrupt} function attribute, AVR 4859 Use this attribute to indicate 4860 that the specified function is an interrupt handler. The compiler generates 4861 function entry and exit sequences suitable for use in an interrupt handler 4862 when this attribute is present. 4863 4864 On the AVR, the hardware globally disables interrupts when an 4865 interrupt is executed. The first instruction of an interrupt handler 4866 declared with this attribute is a @code{SEI} instruction to 4867 re-enable interrupts. See also the @code{signal} function attribute 4868 that does not insert a @code{SEI} instruction. If both @code{signal} and 4869 @code{interrupt} are specified for the same function, @code{signal} 4870 is silently ignored. 4871 4872 @item naked 4873 @cindex @code{naked} function attribute, AVR 4874 This attribute allows the compiler to construct the 4875 requisite function declaration, while allowing the body of the 4876 function to be assembly code. The specified function will not have 4877 prologue/epilogue sequences generated by the compiler. Only basic 4878 @code{asm} statements can safely be included in naked functions 4879 (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of 4880 basic @code{asm} and C code may appear to work, they cannot be 4881 depended upon to work reliably and are not supported. 4882 4883 @item no_gccisr 4884 @cindex @code{no_gccisr} function attribute, AVR 4885 Do not use @code{__gcc_isr} pseudo instructions in a function with 4886 the @code{interrupt} or @code{signal} attribute aka. interrupt 4887 service routine (ISR). 4888 Use this attribute if the preamble of the ISR prologue should always read 4889 @example 4890 push __zero_reg__ 4891 push __tmp_reg__ 4892 in __tmp_reg__, __SREG__ 4893 push __tmp_reg__ 4894 clr __zero_reg__ 4895 @end example 4896 and accordingly for the postamble of the epilogue --- no matter whether 4897 the mentioned registers are actually used in the ISR or not. 4898 Situations where you might want to use this attribute include: 4899 @itemize @bullet 4900 @item 4901 Code that (effectively) clobbers bits of @code{SREG} other than the 4902 @code{I}-flag by writing to the memory location of @code{SREG}. 4903 @item 4904 Code that uses inline assembler to jump to a different function which 4905 expects (parts of) the prologue code as outlined above to be present. 4906 @end itemize 4907 To disable @code{__gcc_isr} generation for the whole compilation unit, 4908 there is option @option{-mno-gas-isr-prologues}, @pxref{AVR Options}. 4909 4910 @item OS_main 4911 @itemx OS_task 4912 @cindex @code{OS_main} function attribute, AVR 4913 @cindex @code{OS_task} function attribute, AVR 4914 On AVR, functions with the @code{OS_main} or @code{OS_task} attribute 4915 do not save/restore any call-saved register in their prologue/epilogue. 4916 4917 The @code{OS_main} attribute can be used when there @emph{is 4918 guarantee} that interrupts are disabled at the time when the function 4919 is entered. This saves resources when the stack pointer has to be 4920 changed to set up a frame for local variables. 4921 4922 The @code{OS_task} attribute can be used when there is @emph{no 4923 guarantee} that interrupts are disabled at that time when the function 4924 is entered like for, e@.g@. task functions in a multi-threading operating 4925 system. In that case, changing the stack pointer register is 4926 guarded by save/clear/restore of the global interrupt enable flag. 4927 4928 The differences to the @code{naked} function attribute are: 4929 @itemize @bullet 4930 @item @code{naked} functions do not have a return instruction whereas 4931 @code{OS_main} and @code{OS_task} functions have a @code{RET} or 4932 @code{RETI} return instruction. 4933 @item @code{naked} functions do not set up a frame for local variables 4934 or a frame pointer whereas @code{OS_main} and @code{OS_task} do this 4935 as needed. 4936 @end itemize 4937 4938 @item signal 4939 @cindex @code{signal} function attribute, AVR 4940 Use this attribute on the AVR to indicate that the specified 4941 function is an interrupt handler. The compiler generates function 4942 entry and exit sequences suitable for use in an interrupt handler when this 4943 attribute is present. 4944 4945 See also the @code{interrupt} function attribute. 4946 4947 The AVR hardware globally disables interrupts when an interrupt is executed. 4948 Interrupt handler functions defined with the @code{signal} attribute 4949 do not re-enable interrupts. It is save to enable interrupts in a 4950 @code{signal} handler. This ``save'' only applies to the code 4951 generated by the compiler and not to the IRQ layout of the 4952 application which is responsibility of the application. 4953 4954 If both @code{signal} and @code{interrupt} are specified for the same 4955 function, @code{signal} is silently ignored. 4956 @end table 4957 4958 @node Blackfin Function Attributes 4959 @subsection Blackfin Function Attributes 4960 4961 These function attributes are supported by the Blackfin back end: 4962 4963 @table @code 4964 4965 @item exception_handler 4966 @cindex @code{exception_handler} function attribute 4967 @cindex exception handler functions, Blackfin 4968 Use this attribute on the Blackfin to indicate that the specified function 4969 is an exception handler. The compiler generates function entry and 4970 exit sequences suitable for use in an exception handler when this 4971 attribute is present. 4972 4973 @item interrupt_handler 4974 @cindex @code{interrupt_handler} function attribute, Blackfin 4975 Use this attribute to 4976 indicate that the specified function is an interrupt handler. The compiler 4977 generates function entry and exit sequences suitable for use in an 4978 interrupt handler when this attribute is present. 4979 4980 @item kspisusp 4981 @cindex @code{kspisusp} function attribute, Blackfin 4982 @cindex User stack pointer in interrupts on the Blackfin 4983 When used together with @code{interrupt_handler}, @code{exception_handler} 4984 or @code{nmi_handler}, code is generated to load the stack pointer 4985 from the USP register in the function prologue. 4986 4987 @item l1_text 4988 @cindex @code{l1_text} function attribute, Blackfin 4989 This attribute specifies a function to be placed into L1 Instruction 4990 SRAM@. The function is put into a specific section named @code{.l1.text}. 4991 With @option{-mfdpic}, function calls with a such function as the callee 4992 or caller uses inlined PLT. 4993 4994 @item l2 4995 @cindex @code{l2} function attribute, Blackfin 4996 This attribute specifies a function to be placed into L2 4997 SRAM. The function is put into a specific section named 4998 @code{.l2.text}. With @option{-mfdpic}, callers of such functions use 4999 an inlined PLT. 5000 5001 @item longcall 5002 @itemx shortcall 5003 @cindex indirect calls, Blackfin 5004 @cindex @code{longcall} function attribute, Blackfin 5005 @cindex @code{shortcall} function attribute, Blackfin 5006 The @code{longcall} attribute 5007 indicates that the function might be far away from the call site and 5008 require a different (more expensive) calling sequence. The 5009 @code{shortcall} attribute indicates that the function is always close 5010 enough for the shorter calling sequence to be used. These attributes 5011 override the @option{-mlongcall} switch. 5012 5013 @item nesting 5014 @cindex @code{nesting} function attribute, Blackfin 5015 @cindex Allow nesting in an interrupt handler on the Blackfin processor 5016 Use this attribute together with @code{interrupt_handler}, 5017 @code{exception_handler} or @code{nmi_handler} to indicate that the function 5018 entry code should enable nested interrupts or exceptions. 5019 5020 @item nmi_handler 5021 @cindex @code{nmi_handler} function attribute, Blackfin 5022 @cindex NMI handler functions on the Blackfin processor 5023 Use this attribute on the Blackfin to indicate that the specified function 5024 is an NMI handler. The compiler generates function entry and 5025 exit sequences suitable for use in an NMI handler when this 5026 attribute is present. 5027 5028 @item saveall 5029 @cindex @code{saveall} function attribute, Blackfin 5030 @cindex save all registers on the Blackfin 5031 Use this attribute to indicate that 5032 all registers except the stack pointer should be saved in the prologue 5033 regardless of whether they are used or not. 5034 @end table 5035 5036 @node BPF Function Attributes 5037 @subsection BPF Function Attributes 5038 5039 These function attributes are supported by the BPF back end: 5040 5041 @table @code 5042 @item kernel_helper 5043 @cindex @code{kernel helper}, function attribute, BPF 5044 use this attribute to indicate the specified function declaration is a 5045 kernel helper. The helper function is passed as an argument to the 5046 attribute. Example: 5047 5048 @smallexample 5049 int bpf_probe_read (void *dst, int size, const void *unsafe_ptr) 5050 __attribute__ ((kernel_helper (4))); 5051 @end smallexample 5052 @end table 5053 5054 @node CR16 Function Attributes 5055 @subsection CR16 Function Attributes 5056 5057 These function attributes are supported by the CR16 back end: 5058 5059 @table @code 5060 @item interrupt 5061 @cindex @code{interrupt} function attribute, CR16 5062 Use this attribute to indicate 5063 that the specified function is an interrupt handler. The compiler generates 5064 function entry and exit sequences suitable for use in an interrupt handler 5065 when this attribute is present. 5066 @end table 5067 5068 @node C-SKY Function Attributes 5069 @subsection C-SKY Function Attributes 5070 5071 These function attributes are supported by the C-SKY back end: 5072 5073 @table @code 5074 @item interrupt 5075 @itemx isr 5076 @cindex @code{interrupt} function attribute, C-SKY 5077 @cindex @code{isr} function attribute, C-SKY 5078 Use these attributes to indicate that the specified function 5079 is an interrupt handler. 5080 The compiler generates function entry and exit sequences suitable for 5081 use in an interrupt handler when either of these attributes are present. 5082 5083 Use of these options requires the @option{-mistack} command-line option 5084 to enable support for the necessary interrupt stack instructions. They 5085 are ignored with a warning otherwise. @xref{C-SKY Options}. 5086 5087 @item naked 5088 @cindex @code{naked} function attribute, C-SKY 5089 This attribute allows the compiler to construct the 5090 requisite function declaration, while allowing the body of the 5091 function to be assembly code. The specified function will not have 5092 prologue/epilogue sequences generated by the compiler. Only basic 5093 @code{asm} statements can safely be included in naked functions 5094 (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of 5095 basic @code{asm} and C code may appear to work, they cannot be 5096 depended upon to work reliably and are not supported. 5097 @end table 5098 5099 5100 @node Epiphany Function Attributes 5101 @subsection Epiphany Function Attributes 5102 5103 These function attributes are supported by the Epiphany back end: 5104 5105 @table @code 5106 @item disinterrupt 5107 @cindex @code{disinterrupt} function attribute, Epiphany 5108 This attribute causes the compiler to emit 5109 instructions to disable interrupts for the duration of the given 5110 function. 5111 5112 @item forwarder_section 5113 @cindex @code{forwarder_section} function attribute, Epiphany 5114 This attribute modifies the behavior of an interrupt handler. 5115 The interrupt handler may be in external memory which cannot be 5116 reached by a branch instruction, so generate a local memory trampoline 5117 to transfer control. The single parameter identifies the section where 5118 the trampoline is placed. 5119 5120 @item interrupt 5121 @cindex @code{interrupt} function attribute, Epiphany 5122 Use this attribute to indicate 5123 that the specified function is an interrupt handler. The compiler generates 5124 function entry and exit sequences suitable for use in an interrupt handler 5125 when this attribute is present. It may also generate 5126 a special section with code to initialize the interrupt vector table. 5127 5128 On Epiphany targets one or more optional parameters can be added like this: 5129 5130 @smallexample 5131 void __attribute__ ((interrupt ("dma0, dma1"))) universal_dma_handler (); 5132 @end smallexample 5133 5134 Permissible values for these parameters are: @w{@code{reset}}, 5135 @w{@code{software_exception}}, @w{@code{page_miss}}, 5136 @w{@code{timer0}}, @w{@code{timer1}}, @w{@code{message}}, 5137 @w{@code{dma0}}, @w{@code{dma1}}, @w{@code{wand}} and @w{@code{swi}}. 5138 Multiple parameters indicate that multiple entries in the interrupt 5139 vector table should be initialized for this function, i.e.@: for each 5140 parameter @w{@var{name}}, a jump to the function is emitted in 5141 the section @w{ivt_entry_@var{name}}. The parameter(s) may be omitted 5142 entirely, in which case no interrupt vector table entry is provided. 5143 5144 Note that interrupts are enabled inside the function 5145 unless the @code{disinterrupt} attribute is also specified. 5146 5147 The following examples are all valid uses of these attributes on 5148 Epiphany targets: 5149 @smallexample 5150 void __attribute__ ((interrupt)) universal_handler (); 5151 void __attribute__ ((interrupt ("dma1"))) dma1_handler (); 5152 void __attribute__ ((interrupt ("dma0, dma1"))) 5153 universal_dma_handler (); 5154 void __attribute__ ((interrupt ("timer0"), disinterrupt)) 5155 fast_timer_handler (); 5156 void __attribute__ ((interrupt ("dma0, dma1"), 5157 forwarder_section ("tramp"))) 5158 external_dma_handler (); 5159 @end smallexample 5160 5161 @item long_call 5162 @itemx short_call 5163 @cindex @code{long_call} function attribute, Epiphany 5164 @cindex @code{short_call} function attribute, Epiphany 5165 @cindex indirect calls, Epiphany 5166 These attributes specify how a particular function is called. 5167 These attributes override the 5168 @option{-mlong-calls} (@pxref{Adapteva Epiphany Options}) 5169 command-line switch and @code{#pragma long_calls} settings. 5170 @end table 5171 5172 5173 @node H8/300 Function Attributes 5174 @subsection H8/300 Function Attributes 5175 5176 These function attributes are available for H8/300 targets: 5177 5178 @table @code 5179 @item function_vector 5180 @cindex @code{function_vector} function attribute, H8/300 5181 Use this attribute on the H8/300, H8/300H, and H8S to indicate 5182 that the specified function should be called through the function vector. 5183 Calling a function through the function vector reduces code size; however, 5184 the function vector has a limited size (maximum 128 entries on the H8/300 5185 and 64 entries on the H8/300H and H8S) 5186 and shares space with the interrupt vector. 5187 5188 @item interrupt_handler 5189 @cindex @code{interrupt_handler} function attribute, H8/300 5190 Use this attribute on the H8/300, H8/300H, and H8S to 5191 indicate that the specified function is an interrupt handler. The compiler 5192 generates function entry and exit sequences suitable for use in an 5193 interrupt handler when this attribute is present. 5194 5195 @item saveall 5196 @cindex @code{saveall} function attribute, H8/300 5197 @cindex save all registers on the H8/300, H8/300H, and H8S 5198 Use this attribute on the H8/300, H8/300H, and H8S to indicate that 5199 all registers except the stack pointer should be saved in the prologue 5200 regardless of whether they are used or not. 5201 @end table 5202 5203 @node IA-64 Function Attributes 5204 @subsection IA-64 Function Attributes 5205 5206 These function attributes are supported on IA-64 targets: 5207 5208 @table @code 5209 @item syscall_linkage 5210 @cindex @code{syscall_linkage} function attribute, IA-64 5211 This attribute is used to modify the IA-64 calling convention by marking 5212 all input registers as live at all function exits. This makes it possible 5213 to restart a system call after an interrupt without having to save/restore 5214 the input registers. This also prevents kernel data from leaking into 5215 application code. 5216 5217 @item version_id 5218 @cindex @code{version_id} function attribute, IA-64 5219 This IA-64 HP-UX attribute, attached to a global variable or function, renames a 5220 symbol to contain a version string, thus allowing for function level 5221 versioning. HP-UX system header files may use function level versioning 5222 for some system calls. 5223 5224 @smallexample 5225 extern int foo () __attribute__((version_id ("20040821"))); 5226 @end smallexample 5227 5228 @noindent 5229 Calls to @code{foo} are mapped to calls to @code{foo@{20040821@}}. 5230 @end table 5231 5232 @node M32C Function Attributes 5233 @subsection M32C Function Attributes 5234 5235 These function attributes are supported by the M32C back end: 5236 5237 @table @code 5238 @item bank_switch 5239 @cindex @code{bank_switch} function attribute, M32C 5240 When added to an interrupt handler with the M32C port, causes the 5241 prologue and epilogue to use bank switching to preserve the registers 5242 rather than saving them on the stack. 5243 5244 @item fast_interrupt 5245 @cindex @code{fast_interrupt} function attribute, M32C 5246 Use this attribute on the M32C port to indicate that the specified 5247 function is a fast interrupt handler. This is just like the 5248 @code{interrupt} attribute, except that @code{freit} is used to return 5249 instead of @code{reit}. 5250 5251 @item function_vector 5252 @cindex @code{function_vector} function attribute, M16C/M32C 5253 On M16C/M32C targets, the @code{function_vector} attribute declares a 5254 special page subroutine call function. Use of this attribute reduces 5255 the code size by 2 bytes for each call generated to the 5256 subroutine. The argument to the attribute is the vector number entry 5257 from the special page vector table which contains the 16 low-order 5258 bits of the subroutine's entry address. Each vector table has special 5259 page number (18 to 255) that is used in @code{jsrs} instructions. 5260 Jump addresses of the routines are generated by adding 0x0F0000 (in 5261 case of M16C targets) or 0xFF0000 (in case of M32C targets), to the 5262 2-byte addresses set in the vector table. Therefore you need to ensure 5263 that all the special page vector routines should get mapped within the 5264 address range 0x0F0000 to 0x0FFFFF (for M16C) and 0xFF0000 to 0xFFFFFF 5265 (for M32C). 5266 5267 In the following example 2 bytes are saved for each call to 5268 function @code{foo}. 5269 5270 @smallexample 5271 void foo (void) __attribute__((function_vector(0x18))); 5272 void foo (void) 5273 @{ 5274 @} 5275 5276 void bar (void) 5277 @{ 5278 foo(); 5279 @} 5280 @end smallexample 5281 5282 If functions are defined in one file and are called in another file, 5283 then be sure to write this declaration in both files. 5284 5285 This attribute is ignored for R8C target. 5286 5287 @item interrupt 5288 @cindex @code{interrupt} function attribute, M32C 5289 Use this attribute to indicate 5290 that the specified function is an interrupt handler. The compiler generates 5291 function entry and exit sequences suitable for use in an interrupt handler 5292 when this attribute is present. 5293 @end table 5294 5295 @node M32R/D Function Attributes 5296 @subsection M32R/D Function Attributes 5297 5298 These function attributes are supported by the M32R/D back end: 5299 5300 @table @code 5301 @item interrupt 5302 @cindex @code{interrupt} function attribute, M32R/D 5303 Use this attribute to indicate 5304 that the specified function is an interrupt handler. The compiler generates 5305 function entry and exit sequences suitable for use in an interrupt handler 5306 when this attribute is present. 5307 5308 @item model (@var{model-name}) 5309 @cindex @code{model} function attribute, M32R/D 5310 @cindex function addressability on the M32R/D 5311 5312 On the M32R/D, use this attribute to set the addressability of an 5313 object, and of the code generated for a function. The identifier 5314 @var{model-name} is one of @code{small}, @code{medium}, or 5315 @code{large}, representing each of the code models. 5316 5317 Small model objects live in the lower 16MB of memory (so that their 5318 addresses can be loaded with the @code{ld24} instruction), and are 5319 callable with the @code{bl} instruction. 5320 5321 Medium model objects may live anywhere in the 32-bit address space (the 5322 compiler generates @code{seth/add3} instructions to load their addresses), 5323 and are callable with the @code{bl} instruction. 5324 5325 Large model objects may live anywhere in the 32-bit address space (the 5326 compiler generates @code{seth/add3} instructions to load their addresses), 5327 and may not be reachable with the @code{bl} instruction (the compiler 5328 generates the much slower @code{seth/add3/jl} instruction sequence). 5329 @end table 5330 5331 @node m68k Function Attributes 5332 @subsection m68k Function Attributes 5333 5334 These function attributes are supported by the m68k back end: 5335 5336 @table @code 5337 @item interrupt 5338 @itemx interrupt_handler 5339 @cindex @code{interrupt} function attribute, m68k 5340 @cindex @code{interrupt_handler} function attribute, m68k 5341 Use this attribute to 5342 indicate that the specified function is an interrupt handler. The compiler 5343 generates function entry and exit sequences suitable for use in an 5344 interrupt handler when this attribute is present. Either name may be used. 5345 5346 @item interrupt_thread 5347 @cindex @code{interrupt_thread} function attribute, fido 5348 Use this attribute on fido, a subarchitecture of the m68k, to indicate 5349 that the specified function is an interrupt handler that is designed 5350 to run as a thread. The compiler omits generate prologue/epilogue 5351 sequences and replaces the return instruction with a @code{sleep} 5352 instruction. This attribute is available only on fido. 5353 @end table 5354 5355 @node MCORE Function Attributes 5356 @subsection MCORE Function Attributes 5357 5358 These function attributes are supported by the MCORE back end: 5359 5360 @table @code 5361 @item naked 5362 @cindex @code{naked} function attribute, MCORE 5363 This attribute allows the compiler to construct the 5364 requisite function declaration, while allowing the body of the 5365 function to be assembly code. The specified function will not have 5366 prologue/epilogue sequences generated by the compiler. Only basic 5367 @code{asm} statements can safely be included in naked functions 5368 (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of 5369 basic @code{asm} and C code may appear to work, they cannot be 5370 depended upon to work reliably and are not supported. 5371 @end table 5372 5373 @node MeP Function Attributes 5374 @subsection MeP Function Attributes 5375 5376 These function attributes are supported by the MeP back end: 5377 5378 @table @code 5379 @item disinterrupt 5380 @cindex @code{disinterrupt} function attribute, MeP 5381 On MeP targets, this attribute causes the compiler to emit 5382 instructions to disable interrupts for the duration of the given 5383 function. 5384 5385 @item interrupt 5386 @cindex @code{interrupt} function attribute, MeP 5387 Use this attribute to indicate 5388 that the specified function is an interrupt handler. The compiler generates 5389 function entry and exit sequences suitable for use in an interrupt handler 5390 when this attribute is present. 5391 5392 @item near 5393 @cindex @code{near} function attribute, MeP 5394 This attribute causes the compiler to assume the called 5395 function is close enough to use the normal calling convention, 5396 overriding the @option{-mtf} command-line option. 5397 5398 @item far 5399 @cindex @code{far} function attribute, MeP 5400 On MeP targets this causes the compiler to use a calling convention 5401 that assumes the called function is too far away for the built-in 5402 addressing modes. 5403 5404 @item vliw 5405 @cindex @code{vliw} function attribute, MeP 5406 The @code{vliw} attribute tells the compiler to emit 5407 instructions in VLIW mode instead of core mode. Note that this 5408 attribute is not allowed unless a VLIW coprocessor has been configured 5409 and enabled through command-line options. 5410 @end table 5411 5412 @node MicroBlaze Function Attributes 5413 @subsection MicroBlaze Function Attributes 5414 5415 These function attributes are supported on MicroBlaze targets: 5416 5417 @table @code 5418 @item save_volatiles 5419 @cindex @code{save_volatiles} function attribute, MicroBlaze 5420 Use this attribute to indicate that the function is 5421 an interrupt handler. All volatile registers (in addition to non-volatile 5422 registers) are saved in the function prologue. If the function is a leaf 5423 function, only volatiles used by the function are saved. A normal function 5424 return is generated instead of a return from interrupt. 5425 5426 @item break_handler 5427 @cindex @code{break_handler} function attribute, MicroBlaze 5428 @cindex break handler functions 5429 Use this attribute to indicate that 5430 the specified function is a break handler. The compiler generates function 5431 entry and exit sequences suitable for use in an break handler when this 5432 attribute is present. The return from @code{break_handler} is done through 5433 the @code{rtbd} instead of @code{rtsd}. 5434 5435 @smallexample 5436 void f () __attribute__ ((break_handler)); 5437 @end smallexample 5438 5439 @item interrupt_handler 5440 @itemx fast_interrupt 5441 @cindex @code{interrupt_handler} function attribute, MicroBlaze 5442 @cindex @code{fast_interrupt} function attribute, MicroBlaze 5443 These attributes indicate that the specified function is an interrupt 5444 handler. Use the @code{fast_interrupt} attribute to indicate handlers 5445 used in low-latency interrupt mode, and @code{interrupt_handler} for 5446 interrupts that do not use low-latency handlers. In both cases, GCC 5447 emits appropriate prologue code and generates a return from the handler 5448 using @code{rtid} instead of @code{rtsd}. 5449 @end table 5450 5451 @node Microsoft Windows Function Attributes 5452 @subsection Microsoft Windows Function Attributes 5453 5454 The following attributes are available on Microsoft Windows and Symbian OS 5455 targets. 5456 5457 @table @code 5458 @item dllexport 5459 @cindex @code{dllexport} function attribute 5460 @cindex @code{__declspec(dllexport)} 5461 On Microsoft Windows targets and Symbian OS targets the 5462 @code{dllexport} attribute causes the compiler to provide a global 5463 pointer to a pointer in a DLL, so that it can be referenced with the 5464 @code{dllimport} attribute. On Microsoft Windows targets, the pointer 5465 name is formed by combining @code{_imp__} and the function or variable 5466 name. 5467 5468 You can use @code{__declspec(dllexport)} as a synonym for 5469 @code{__attribute__ ((dllexport))} for compatibility with other 5470 compilers. 5471 5472 On systems that support the @code{visibility} attribute, this 5473 attribute also implies ``default'' visibility. It is an error to 5474 explicitly specify any other visibility. 5475 5476 GCC's default behavior is to emit all inline functions with the 5477 @code{dllexport} attribute. Since this can cause object file-size bloat, 5478 you can use @option{-fno-keep-inline-dllexport}, which tells GCC to 5479 ignore the attribute for inlined functions unless the 5480 @option{-fkeep-inline-functions} flag is used instead. 5481 5482 The attribute is ignored for undefined symbols. 5483 5484 When applied to C++ classes, the attribute marks defined non-inlined 5485 member functions and static data members as exports. Static consts 5486 initialized in-class are not marked unless they are also defined 5487 out-of-class. 5488 5489 For Microsoft Windows targets there are alternative methods for 5490 including the symbol in the DLL's export table such as using a 5491 @file{.def} file with an @code{EXPORTS} section or, with GNU ld, using 5492 the @option{--export-all} linker flag. 5493 5494 @item dllimport 5495 @cindex @code{dllimport} function attribute 5496 @cindex @code{__declspec(dllimport)} 5497 On Microsoft Windows and Symbian OS targets, the @code{dllimport} 5498 attribute causes the compiler to reference a function or variable via 5499 a global pointer to a pointer that is set up by the DLL exporting the 5500 symbol. The attribute implies @code{extern}. On Microsoft Windows 5501 targets, the pointer name is formed by combining @code{_imp__} and the 5502 function or variable name. 5503 5504 You can use @code{__declspec(dllimport)} as a synonym for 5505 @code{__attribute__ ((dllimport))} for compatibility with other 5506 compilers. 5507 5508 On systems that support the @code{visibility} attribute, this 5509 attribute also implies ``default'' visibility. It is an error to 5510 explicitly specify any other visibility. 5511 5512 Currently, the attribute is ignored for inlined functions. If the 5513 attribute is applied to a symbol @emph{definition}, an error is reported. 5514 If a symbol previously declared @code{dllimport} is later defined, the 5515 attribute is ignored in subsequent references, and a warning is emitted. 5516 The attribute is also overridden by a subsequent declaration as 5517 @code{dllexport}. 5518 5519 When applied to C++ classes, the attribute marks non-inlined 5520 member functions and static data members as imports. However, the 5521 attribute is ignored for virtual methods to allow creation of vtables 5522 using thunks. 5523 5524 On the SH Symbian OS target the @code{dllimport} attribute also has 5525 another affect---it can cause the vtable and run-time type information 5526 for a class to be exported. This happens when the class has a 5527 dllimported constructor or a non-inline, non-pure virtual function 5528 and, for either of those two conditions, the class also has an inline 5529 constructor or destructor and has a key function that is defined in 5530 the current translation unit. 5531 5532 For Microsoft Windows targets the use of the @code{dllimport} 5533 attribute on functions is not necessary, but provides a small 5534 performance benefit by eliminating a thunk in the DLL@. The use of the 5535 @code{dllimport} attribute on imported variables can be avoided by passing the 5536 @option{--enable-auto-import} switch to the GNU linker. As with 5537 functions, using the attribute for a variable eliminates a thunk in 5538 the DLL@. 5539 5540 One drawback to using this attribute is that a pointer to a 5541 @emph{variable} marked as @code{dllimport} cannot be used as a constant 5542 address. However, a pointer to a @emph{function} with the 5543 @code{dllimport} attribute can be used as a constant initializer; in 5544 this case, the address of a stub function in the import lib is 5545 referenced. On Microsoft Windows targets, the attribute can be disabled 5546 for functions by setting the @option{-mnop-fun-dllimport} flag. 5547 @end table 5548 5549 @node MIPS Function Attributes 5550 @subsection MIPS Function Attributes 5551 5552 These function attributes are supported by the MIPS back end: 5553 5554 @table @code 5555 @item interrupt 5556 @cindex @code{interrupt} function attribute, MIPS 5557 Use this attribute to indicate that the specified function is an interrupt 5558 handler. The compiler generates function entry and exit sequences suitable 5559 for use in an interrupt handler when this attribute is present. 5560 An optional argument is supported for the interrupt attribute which allows 5561 the interrupt mode to be described. By default GCC assumes the external 5562 interrupt controller (EIC) mode is in use, this can be explicitly set using 5563 @code{eic}. When interrupts are non-masked then the requested Interrupt 5564 Priority Level (IPL) is copied to the current IPL which has the effect of only 5565 enabling higher priority interrupts. To use vectored interrupt mode use 5566 the argument @code{vector=[sw0|sw1|hw0|hw1|hw2|hw3|hw4|hw5]}, this will change 5567 the behavior of the non-masked interrupt support and GCC will arrange to mask 5568 all interrupts from sw0 up to and including the specified interrupt vector. 5569 5570 You can use the following attributes to modify the behavior 5571 of an interrupt handler: 5572 @table @code 5573 @item use_shadow_register_set 5574 @cindex @code{use_shadow_register_set} function attribute, MIPS 5575 Assume that the handler uses a shadow register set, instead of 5576 the main general-purpose registers. An optional argument @code{intstack} is 5577 supported to indicate that the shadow register set contains a valid stack 5578 pointer. 5579 5580 @item keep_interrupts_masked 5581 @cindex @code{keep_interrupts_masked} function attribute, MIPS 5582 Keep interrupts masked for the whole function. Without this attribute, 5583 GCC tries to reenable interrupts for as much of the function as it can. 5584 5585 @item use_debug_exception_return 5586 @cindex @code{use_debug_exception_return} function attribute, MIPS 5587 Return using the @code{deret} instruction. Interrupt handlers that don't 5588 have this attribute return using @code{eret} instead. 5589 @end table 5590 5591 You can use any combination of these attributes, as shown below: 5592 @smallexample 5593 void __attribute__ ((interrupt)) v0 (); 5594 void __attribute__ ((interrupt, use_shadow_register_set)) v1 (); 5595 void __attribute__ ((interrupt, keep_interrupts_masked)) v2 (); 5596 void __attribute__ ((interrupt, use_debug_exception_return)) v3 (); 5597 void __attribute__ ((interrupt, use_shadow_register_set, 5598 keep_interrupts_masked)) v4 (); 5599 void __attribute__ ((interrupt, use_shadow_register_set, 5600 use_debug_exception_return)) v5 (); 5601 void __attribute__ ((interrupt, keep_interrupts_masked, 5602 use_debug_exception_return)) v6 (); 5603 void __attribute__ ((interrupt, use_shadow_register_set, 5604 keep_interrupts_masked, 5605 use_debug_exception_return)) v7 (); 5606 void __attribute__ ((interrupt("eic"))) v8 (); 5607 void __attribute__ ((interrupt("vector=hw3"))) v9 (); 5608 @end smallexample 5609 5610 @item long_call 5611 @itemx short_call 5612 @itemx near 5613 @itemx far 5614 @cindex indirect calls, MIPS 5615 @cindex @code{long_call} function attribute, MIPS 5616 @cindex @code{short_call} function attribute, MIPS 5617 @cindex @code{near} function attribute, MIPS 5618 @cindex @code{far} function attribute, MIPS 5619 These attributes specify how a particular function is called on MIPS@. 5620 The attributes override the @option{-mlong-calls} (@pxref{MIPS Options}) 5621 command-line switch. The @code{long_call} and @code{far} attributes are 5622 synonyms, and cause the compiler to always call 5623 the function by first loading its address into a register, and then using 5624 the contents of that register. The @code{short_call} and @code{near} 5625 attributes are synonyms, and have the opposite 5626 effect; they specify that non-PIC calls should be made using the more 5627 efficient @code{jal} instruction. 5628 5629 @item mips16 5630 @itemx nomips16 5631 @cindex @code{mips16} function attribute, MIPS 5632 @cindex @code{nomips16} function attribute, MIPS 5633 5634 On MIPS targets, you can use the @code{mips16} and @code{nomips16} 5635 function attributes to locally select or turn off MIPS16 code generation. 5636 A function with the @code{mips16} attribute is emitted as MIPS16 code, 5637 while MIPS16 code generation is disabled for functions with the 5638 @code{nomips16} attribute. These attributes override the 5639 @option{-mips16} and @option{-mno-mips16} options on the command line 5640 (@pxref{MIPS Options}). 5641 5642 When compiling files containing mixed MIPS16 and non-MIPS16 code, the 5643 preprocessor symbol @code{__mips16} reflects the setting on the command line, 5644 not that within individual functions. Mixed MIPS16 and non-MIPS16 code 5645 may interact badly with some GCC extensions such as @code{__builtin_apply} 5646 (@pxref{Constructing Calls}). 5647 5648 @item micromips, MIPS 5649 @itemx nomicromips, MIPS 5650 @cindex @code{micromips} function attribute 5651 @cindex @code{nomicromips} function attribute 5652 5653 On MIPS targets, you can use the @code{micromips} and @code{nomicromips} 5654 function attributes to locally select or turn off microMIPS code generation. 5655 A function with the @code{micromips} attribute is emitted as microMIPS code, 5656 while microMIPS code generation is disabled for functions with the 5657 @code{nomicromips} attribute. These attributes override the 5658 @option{-mmicromips} and @option{-mno-micromips} options on the command line 5659 (@pxref{MIPS Options}). 5660 5661 When compiling files containing mixed microMIPS and non-microMIPS code, the 5662 preprocessor symbol @code{__mips_micromips} reflects the setting on the 5663 command line, 5664 not that within individual functions. Mixed microMIPS and non-microMIPS code 5665 may interact badly with some GCC extensions such as @code{__builtin_apply} 5666 (@pxref{Constructing Calls}). 5667 5668 @item nocompression 5669 @cindex @code{nocompression} function attribute, MIPS 5670 On MIPS targets, you can use the @code{nocompression} function attribute 5671 to locally turn off MIPS16 and microMIPS code generation. This attribute 5672 overrides the @option{-mips16} and @option{-mmicromips} options on the 5673 command line (@pxref{MIPS Options}). 5674 @end table 5675 5676 @node MSP430 Function Attributes 5677 @subsection MSP430 Function Attributes 5678 5679 These function attributes are supported by the MSP430 back end: 5680 5681 @table @code 5682 @item critical 5683 @cindex @code{critical} function attribute, MSP430 5684 Critical functions disable interrupts upon entry and restore the 5685 previous interrupt state upon exit. Critical functions cannot also 5686 have the @code{naked}, @code{reentrant} or @code{interrupt} attributes. 5687 5688 The MSP430 hardware ensures that interrupts are disabled on entry to 5689 @code{interrupt} functions, and restores the previous interrupt state 5690 on exit. The @code{critical} attribute is therefore redundant on 5691 @code{interrupt} functions. 5692 5693 @item interrupt 5694 @cindex @code{interrupt} function attribute, MSP430 5695 Use this attribute to indicate 5696 that the specified function is an interrupt handler. The compiler generates 5697 function entry and exit sequences suitable for use in an interrupt handler 5698 when this attribute is present. 5699 5700 You can provide an argument to the interrupt 5701 attribute which specifies a name or number. If the argument is a 5702 number it indicates the slot in the interrupt vector table (0 - 31) to 5703 which this handler should be assigned. If the argument is a name it 5704 is treated as a symbolic name for the vector slot. These names should 5705 match up with appropriate entries in the linker script. By default 5706 the names @code{watchdog} for vector 26, @code{nmi} for vector 30 and 5707 @code{reset} for vector 31 are recognized. 5708 5709 @item naked 5710 @cindex @code{naked} function attribute, MSP430 5711 This attribute allows the compiler to construct the 5712 requisite function declaration, while allowing the body of the 5713 function to be assembly code. The specified function will not have 5714 prologue/epilogue sequences generated by the compiler. Only basic 5715 @code{asm} statements can safely be included in naked functions 5716 (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of 5717 basic @code{asm} and C code may appear to work, they cannot be 5718 depended upon to work reliably and are not supported. 5719 5720 @item reentrant 5721 @cindex @code{reentrant} function attribute, MSP430 5722 Reentrant functions disable interrupts upon entry and enable them 5723 upon exit. Reentrant functions cannot also have the @code{naked} 5724 or @code{critical} attributes. They can have the @code{interrupt} 5725 attribute. 5726 5727 @item wakeup 5728 @cindex @code{wakeup} function attribute, MSP430 5729 This attribute only applies to interrupt functions. It is silently 5730 ignored if applied to a non-interrupt function. A wakeup interrupt 5731 function will rouse the processor from any low-power state that it 5732 might be in when the function exits. 5733 5734 @item lower 5735 @itemx upper 5736 @itemx either 5737 @cindex @code{lower} function attribute, MSP430 5738 @cindex @code{upper} function attribute, MSP430 5739 @cindex @code{either} function attribute, MSP430 5740 On the MSP430 target these attributes can be used to specify whether 5741 the function or variable should be placed into low memory, high 5742 memory, or the placement should be left to the linker to decide. The 5743 attributes are only significant if compiling for the MSP430X 5744 architecture in the large memory model. 5745 5746 The attributes work in conjunction with a linker script that has been 5747 augmented to specify where to place sections with a @code{.lower} and 5748 a @code{.upper} prefix. So, for example, as well as placing the 5749 @code{.data} section, the script also specifies the placement of a 5750 @code{.lower.data} and a @code{.upper.data} section. The intention 5751 is that @code{lower} sections are placed into a small but easier to 5752 access memory region and the upper sections are placed into a larger, but 5753 slower to access, region. 5754 5755 The @code{either} attribute is special. It tells the linker to place 5756 the object into the corresponding @code{lower} section if there is 5757 room for it. If there is insufficient room then the object is placed 5758 into the corresponding @code{upper} section instead. Note that the 5759 placement algorithm is not very sophisticated. It does not attempt to 5760 find an optimal packing of the @code{lower} sections. It just makes 5761 one pass over the objects and does the best that it can. Using the 5762 @option{-ffunction-sections} and @option{-fdata-sections} command-line 5763 options can help the packing, however, since they produce smaller, 5764 easier to pack regions. 5765 @end table 5766 5767 @node NDS32 Function Attributes 5768 @subsection NDS32 Function Attributes 5769 5770 These function attributes are supported by the NDS32 back end: 5771 5772 @table @code 5773 @item exception 5774 @cindex @code{exception} function attribute 5775 @cindex exception handler functions, NDS32 5776 Use this attribute on the NDS32 target to indicate that the specified function 5777 is an exception handler. The compiler will generate corresponding sections 5778 for use in an exception handler. 5779 5780 @item interrupt 5781 @cindex @code{interrupt} function attribute, NDS32 5782 On NDS32 target, this attribute indicates that the specified function 5783 is an interrupt handler. The compiler generates corresponding sections 5784 for use in an interrupt handler. You can use the following attributes 5785 to modify the behavior: 5786 @table @code 5787 @item nested 5788 @cindex @code{nested} function attribute, NDS32 5789 This interrupt service routine is interruptible. 5790 @item not_nested 5791 @cindex @code{not_nested} function attribute, NDS32 5792 This interrupt service routine is not interruptible. 5793 @item nested_ready 5794 @cindex @code{nested_ready} function attribute, NDS32 5795 This interrupt service routine is interruptible after @code{PSW.GIE} 5796 (global interrupt enable) is set. This allows interrupt service routine to 5797 finish some short critical code before enabling interrupts. 5798 @item save_all 5799 @cindex @code{save_all} function attribute, NDS32 5800 The system will help save all registers into stack before entering 5801 interrupt handler. 5802 @item partial_save 5803 @cindex @code{partial_save} function attribute, NDS32 5804 The system will help save caller registers into stack before entering 5805 interrupt handler. 5806 @end table 5807 5808 @item naked 5809 @cindex @code{naked} function attribute, NDS32 5810 This attribute allows the compiler to construct the 5811 requisite function declaration, while allowing the body of the 5812 function to be assembly code. The specified function will not have 5813 prologue/epilogue sequences generated by the compiler. Only basic 5814 @code{asm} statements can safely be included in naked functions 5815 (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of 5816 basic @code{asm} and C code may appear to work, they cannot be 5817 depended upon to work reliably and are not supported. 5818 5819 @item reset 5820 @cindex @code{reset} function attribute, NDS32 5821 @cindex reset handler functions 5822 Use this attribute on the NDS32 target to indicate that the specified function 5823 is a reset handler. The compiler will generate corresponding sections 5824 for use in a reset handler. You can use the following attributes 5825 to provide extra exception handling: 5826 @table @code 5827 @item nmi 5828 @cindex @code{nmi} function attribute, NDS32 5829 Provide a user-defined function to handle NMI exception. 5830 @item warm 5831 @cindex @code{warm} function attribute, NDS32 5832 Provide a user-defined function to handle warm reset exception. 5833 @end table 5834 @end table 5835 5836 @node Nios II Function Attributes 5837 @subsection Nios II Function Attributes 5838 5839 These function attributes are supported by the Nios II back end: 5840 5841 @table @code 5842 @item target (@var{options}) 5843 @cindex @code{target} function attribute 5844 As discussed in @ref{Common Function Attributes}, this attribute 5845 allows specification of target-specific compilation options. 5846 5847 When compiling for Nios II, the following options are allowed: 5848 5849 @table @samp 5850 @item custom-@var{insn}=@var{N} 5851 @itemx no-custom-@var{insn} 5852 @cindex @code{target("custom-@var{insn}=@var{N}")} function attribute, Nios II 5853 @cindex @code{target("no-custom-@var{insn}")} function attribute, Nios II 5854 Each @samp{custom-@var{insn}=@var{N}} attribute locally enables use of a 5855 custom instruction with encoding @var{N} when generating code that uses 5856 @var{insn}. Similarly, @samp{no-custom-@var{insn}} locally inhibits use of 5857 the custom instruction @var{insn}. 5858 These target attributes correspond to the 5859 @option{-mcustom-@var{insn}=@var{N}} and @option{-mno-custom-@var{insn}} 5860 command-line options, and support the same set of @var{insn} keywords. 5861 @xref{Nios II Options}, for more information. 5862 5863 @item custom-fpu-cfg=@var{name} 5864 @cindex @code{target("custom-fpu-cfg=@var{name}")} function attribute, Nios II 5865 This attribute corresponds to the @option{-mcustom-fpu-cfg=@var{name}} 5866 command-line option, to select a predefined set of custom instructions 5867 named @var{name}. 5868 @xref{Nios II Options}, for more information. 5869 @end table 5870 @end table 5871 5872 @node Nvidia PTX Function Attributes 5873 @subsection Nvidia PTX Function Attributes 5874 5875 These function attributes are supported by the Nvidia PTX back end: 5876 5877 @table @code 5878 @item kernel 5879 @cindex @code{kernel} attribute, Nvidia PTX 5880 This attribute indicates that the corresponding function should be compiled 5881 as a kernel function, which can be invoked from the host via the CUDA RT 5882 library. 5883 By default functions are only callable only from other PTX functions. 5884 5885 Kernel functions must have @code{void} return type. 5886 @end table 5887 5888 @node PowerPC Function Attributes 5889 @subsection PowerPC Function Attributes 5890 5891 These function attributes are supported by the PowerPC back end: 5892 5893 @table @code 5894 @item longcall 5895 @itemx shortcall 5896 @cindex indirect calls, PowerPC 5897 @cindex @code{longcall} function attribute, PowerPC 5898 @cindex @code{shortcall} function attribute, PowerPC 5899 The @code{longcall} attribute 5900 indicates that the function might be far away from the call site and 5901 require a different (more expensive) calling sequence. The 5902 @code{shortcall} attribute indicates that the function is always close 5903 enough for the shorter calling sequence to be used. These attributes 5904 override both the @option{-mlongcall} switch and 5905 the @code{#pragma longcall} setting. 5906 5907 @xref{RS/6000 and PowerPC Options}, for more information on whether long 5908 calls are necessary. 5909 5910 @item target (@var{options}) 5911 @cindex @code{target} function attribute 5912 As discussed in @ref{Common Function Attributes}, this attribute 5913 allows specification of target-specific compilation options. 5914 5915 On the PowerPC, the following options are allowed: 5916 5917 @table @samp 5918 @item altivec 5919 @itemx no-altivec 5920 @cindex @code{target("altivec")} function attribute, PowerPC 5921 Generate code that uses (does not use) AltiVec instructions. In 5922 32-bit code, you cannot enable AltiVec instructions unless 5923 @option{-mabi=altivec} is used on the command line. 5924 5925 @item cmpb 5926 @itemx no-cmpb 5927 @cindex @code{target("cmpb")} function attribute, PowerPC 5928 Generate code that uses (does not use) the compare bytes instruction 5929 implemented on the POWER6 processor and other processors that support 5930 the PowerPC V2.05 architecture. 5931 5932 @item dlmzb 5933 @itemx no-dlmzb 5934 @cindex @code{target("dlmzb")} function attribute, PowerPC 5935 Generate code that uses (does not use) the string-search @samp{dlmzb} 5936 instruction on the IBM 405, 440, 464 and 476 processors. This instruction is 5937 generated by default when targeting those processors. 5938 5939 @item fprnd 5940 @itemx no-fprnd 5941 @cindex @code{target("fprnd")} function attribute, PowerPC 5942 Generate code that uses (does not use) the FP round to integer 5943 instructions implemented on the POWER5+ processor and other processors 5944 that support the PowerPC V2.03 architecture. 5945 5946 @item hard-dfp 5947 @itemx no-hard-dfp 5948 @cindex @code{target("hard-dfp")} function attribute, PowerPC 5949 Generate code that uses (does not use) the decimal floating-point 5950 instructions implemented on some POWER processors. 5951 5952 @item isel 5953 @itemx no-isel 5954 @cindex @code{target("isel")} function attribute, PowerPC 5955 Generate code that uses (does not use) ISEL instruction. 5956 5957 @item mfcrf 5958 @itemx no-mfcrf 5959 @cindex @code{target("mfcrf")} function attribute, PowerPC 5960 Generate code that uses (does not use) the move from condition 5961 register field instruction implemented on the POWER4 processor and 5962 other processors that support the PowerPC V2.01 architecture. 5963 5964 @item mulhw 5965 @itemx no-mulhw 5966 @cindex @code{target("mulhw")} function attribute, PowerPC 5967 Generate code that uses (does not use) the half-word multiply and 5968 multiply-accumulate instructions on the IBM 405, 440, 464 and 476 processors. 5969 These instructions are generated by default when targeting those 5970 processors. 5971 5972 @item multiple 5973 @itemx no-multiple 5974 @cindex @code{target("multiple")} function attribute, PowerPC 5975 Generate code that uses (does not use) the load multiple word 5976 instructions and the store multiple word instructions. 5977 5978 @item update 5979 @itemx no-update 5980 @cindex @code{target("update")} function attribute, PowerPC 5981 Generate code that uses (does not use) the load or store instructions 5982 that update the base register to the address of the calculated memory 5983 location. 5984 5985 @item popcntb 5986 @itemx no-popcntb 5987 @cindex @code{target("popcntb")} function attribute, PowerPC 5988 Generate code that uses (does not use) the popcount and double-precision 5989 FP reciprocal estimate instruction implemented on the POWER5 5990 processor and other processors that support the PowerPC V2.02 5991 architecture. 5992 5993 @item popcntd 5994 @itemx no-popcntd 5995 @cindex @code{target("popcntd")} function attribute, PowerPC 5996 Generate code that uses (does not use) the popcount instruction 5997 implemented on the POWER7 processor and other processors that support 5998 the PowerPC V2.06 architecture. 5999 6000 @item powerpc-gfxopt 6001 @itemx no-powerpc-gfxopt 6002 @cindex @code{target("powerpc-gfxopt")} function attribute, PowerPC 6003 Generate code that uses (does not use) the optional PowerPC 6004 architecture instructions in the Graphics group, including 6005 floating-point select. 6006 6007 @item powerpc-gpopt 6008 @itemx no-powerpc-gpopt 6009 @cindex @code{target("powerpc-gpopt")} function attribute, PowerPC 6010 Generate code that uses (does not use) the optional PowerPC 6011 architecture instructions in the General Purpose group, including 6012 floating-point square root. 6013 6014 @item recip-precision 6015 @itemx no-recip-precision 6016 @cindex @code{target("recip-precision")} function attribute, PowerPC 6017 Assume (do not assume) that the reciprocal estimate instructions 6018 provide higher-precision estimates than is mandated by the PowerPC 6019 ABI. 6020 6021 @item string 6022 @itemx no-string 6023 @cindex @code{target("string")} function attribute, PowerPC 6024 Generate code that uses (does not use) the load string instructions 6025 and the store string word instructions to save multiple registers and 6026 do small block moves. 6027 6028 @item vsx 6029 @itemx no-vsx 6030 @cindex @code{target("vsx")} function attribute, PowerPC 6031 Generate code that uses (does not use) vector/scalar (VSX) 6032 instructions, and also enable the use of built-in functions that allow 6033 more direct access to the VSX instruction set. In 32-bit code, you 6034 cannot enable VSX or AltiVec instructions unless 6035 @option{-mabi=altivec} is used on the command line. 6036 6037 @item friz 6038 @itemx no-friz 6039 @cindex @code{target("friz")} function attribute, PowerPC 6040 Generate (do not generate) the @code{friz} instruction when the 6041 @option{-funsafe-math-optimizations} option is used to optimize 6042 rounding a floating-point value to 64-bit integer and back to floating 6043 point. The @code{friz} instruction does not return the same value if 6044 the floating-point number is too large to fit in an integer. 6045 6046 @item avoid-indexed-addresses 6047 @itemx no-avoid-indexed-addresses 6048 @cindex @code{target("avoid-indexed-addresses")} function attribute, PowerPC 6049 Generate code that tries to avoid (not avoid) the use of indexed load 6050 or store instructions. 6051 6052 @item paired 6053 @itemx no-paired 6054 @cindex @code{target("paired")} function attribute, PowerPC 6055 Generate code that uses (does not use) the generation of PAIRED simd 6056 instructions. 6057 6058 @item longcall 6059 @itemx no-longcall 6060 @cindex @code{target("longcall")} function attribute, PowerPC 6061 Generate code that assumes (does not assume) that all calls are far 6062 away so that a longer more expensive calling sequence is required. 6063 6064 @item cpu=@var{CPU} 6065 @cindex @code{target("cpu=@var{CPU}")} function attribute, PowerPC 6066 Specify the architecture to generate code for when compiling the 6067 function. If you select the @code{target("cpu=power7")} attribute when 6068 generating 32-bit code, VSX and AltiVec instructions are not generated 6069 unless you use the @option{-mabi=altivec} option on the command line. 6070 6071 @item tune=@var{TUNE} 6072 @cindex @code{target("tune=@var{TUNE}")} function attribute, PowerPC 6073 Specify the architecture to tune for when compiling the function. If 6074 you do not specify the @code{target("tune=@var{TUNE}")} attribute and 6075 you do specify the @code{target("cpu=@var{CPU}")} attribute, 6076 compilation tunes for the @var{CPU} architecture, and not the 6077 default tuning specified on the command line. 6078 @end table 6079 6080 On the PowerPC, the inliner does not inline a 6081 function that has different target options than the caller, unless the 6082 callee has a subset of the target options of the caller. 6083 @end table 6084 6085 @node RISC-V Function Attributes 6086 @subsection RISC-V Function Attributes 6087 6088 These function attributes are supported by the RISC-V back end: 6089 6090 @table @code 6091 @item naked 6092 @cindex @code{naked} function attribute, RISC-V 6093 This attribute allows the compiler to construct the 6094 requisite function declaration, while allowing the body of the 6095 function to be assembly code. The specified function will not have 6096 prologue/epilogue sequences generated by the compiler. Only basic 6097 @code{asm} statements can safely be included in naked functions 6098 (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of 6099 basic @code{asm} and C code may appear to work, they cannot be 6100 depended upon to work reliably and are not supported. 6101 6102 @item interrupt 6103 @cindex @code{interrupt} function attribute, RISC-V 6104 Use this attribute to indicate that the specified function is an interrupt 6105 handler. The compiler generates function entry and exit sequences suitable 6106 for use in an interrupt handler when this attribute is present. 6107 6108 You can specify the kind of interrupt to be handled by adding an optional 6109 parameter to the interrupt attribute like this: 6110 6111 @smallexample 6112 void f (void) __attribute__ ((interrupt ("user"))); 6113 @end smallexample 6114 6115 Permissible values for this parameter are @code{user}, @code{supervisor}, 6116 and @code{machine}. If there is no parameter, then it defaults to 6117 @code{machine}. 6118 @end table 6119 6120 @node RL78 Function Attributes 6121 @subsection RL78 Function Attributes 6122 6123 These function attributes are supported by the RL78 back end: 6124 6125 @table @code 6126 @item interrupt 6127 @itemx brk_interrupt 6128 @cindex @code{interrupt} function attribute, RL78 6129 @cindex @code{brk_interrupt} function attribute, RL78 6130 These attributes indicate 6131 that the specified function is an interrupt handler. The compiler generates 6132 function entry and exit sequences suitable for use in an interrupt handler 6133 when this attribute is present. 6134 6135 Use @code{brk_interrupt} instead of @code{interrupt} for 6136 handlers intended to be used with the @code{BRK} opcode (i.e.@: those 6137 that must end with @code{RETB} instead of @code{RETI}). 6138 6139 @item naked 6140 @cindex @code{naked} function attribute, RL78 6141 This attribute allows the compiler to construct the 6142 requisite function declaration, while allowing the body of the 6143 function to be assembly code. The specified function will not have 6144 prologue/epilogue sequences generated by the compiler. Only basic 6145 @code{asm} statements can safely be included in naked functions 6146 (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of 6147 basic @code{asm} and C code may appear to work, they cannot be 6148 depended upon to work reliably and are not supported. 6149 @end table 6150 6151 @node RX Function Attributes 6152 @subsection RX Function Attributes 6153 6154 These function attributes are supported by the RX back end: 6155 6156 @table @code 6157 @item fast_interrupt 6158 @cindex @code{fast_interrupt} function attribute, RX 6159 Use this attribute on the RX port to indicate that the specified 6160 function is a fast interrupt handler. This is just like the 6161 @code{interrupt} attribute, except that @code{freit} is used to return 6162 instead of @code{reit}. 6163 6164 @item interrupt 6165 @cindex @code{interrupt} function attribute, RX 6166 Use this attribute to indicate 6167 that the specified function is an interrupt handler. The compiler generates 6168 function entry and exit sequences suitable for use in an interrupt handler 6169 when this attribute is present. 6170 6171 On RX and RL78 targets, you may specify one or more vector numbers as arguments 6172 to the attribute, as well as naming an alternate table name. 6173 Parameters are handled sequentially, so one handler can be assigned to 6174 multiple entries in multiple tables. One may also pass the magic 6175 string @code{"$default"} which causes the function to be used for any 6176 unfilled slots in the current table. 6177 6178 This example shows a simple assignment of a function to one vector in 6179 the default table (note that preprocessor macros may be used for 6180 chip-specific symbolic vector names): 6181 @smallexample 6182 void __attribute__ ((interrupt (5))) txd1_handler (); 6183 @end smallexample 6184 6185 This example assigns a function to two slots in the default table 6186 (using preprocessor macros defined elsewhere) and makes it the default 6187 for the @code{dct} table: 6188 @smallexample 6189 void __attribute__ ((interrupt (RXD1_VECT,RXD2_VECT,"dct","$default"))) 6190 txd1_handler (); 6191 @end smallexample 6192 6193 @item naked 6194 @cindex @code{naked} function attribute, RX 6195 This attribute allows the compiler to construct the 6196 requisite function declaration, while allowing the body of the 6197 function to be assembly code. The specified function will not have 6198 prologue/epilogue sequences generated by the compiler. Only basic 6199 @code{asm} statements can safely be included in naked functions 6200 (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of 6201 basic @code{asm} and C code may appear to work, they cannot be 6202 depended upon to work reliably and are not supported. 6203 6204 @item vector 6205 @cindex @code{vector} function attribute, RX 6206 This RX attribute is similar to the @code{interrupt} attribute, including its 6207 parameters, but does not make the function an interrupt-handler type 6208 function (i.e.@: it retains the normal C function calling ABI). See the 6209 @code{interrupt} attribute for a description of its arguments. 6210 @end table 6211 6212 @node S/390 Function Attributes 6213 @subsection S/390 Function Attributes 6214 6215 These function attributes are supported on the S/390: 6216 6217 @table @code 6218 @item hotpatch (@var{halfwords-before-function-label},@var{halfwords-after-function-label}) 6219 @cindex @code{hotpatch} function attribute, S/390 6220 6221 On S/390 System z targets, you can use this function attribute to 6222 make GCC generate a ``hot-patching'' function prologue. If the 6223 @option{-mhotpatch=} command-line option is used at the same time, 6224 the @code{hotpatch} attribute takes precedence. The first of the 6225 two arguments specifies the number of halfwords to be added before 6226 the function label. A second argument can be used to specify the 6227 number of halfwords to be added after the function label. For 6228 both arguments the maximum allowed value is 1000000. 6229 6230 If both arguments are zero, hotpatching is disabled. 6231 6232 @item target (@var{options}) 6233 @cindex @code{target} function attribute 6234 As discussed in @ref{Common Function Attributes}, this attribute 6235 allows specification of target-specific compilation options. 6236 6237 On S/390, the following options are supported: 6238 6239 @table @samp 6240 @item arch= 6241 @item tune= 6242 @item stack-guard= 6243 @item stack-size= 6244 @item branch-cost= 6245 @item warn-framesize= 6246 @item backchain 6247 @itemx no-backchain 6248 @item hard-dfp 6249 @itemx no-hard-dfp 6250 @item hard-float 6251 @itemx soft-float 6252 @item htm 6253 @itemx no-htm 6254 @item vx 6255 @itemx no-vx 6256 @item packed-stack 6257 @itemx no-packed-stack 6258 @item small-exec 6259 @itemx no-small-exec 6260 @item mvcle 6261 @itemx no-mvcle 6262 @item warn-dynamicstack 6263 @itemx no-warn-dynamicstack 6264 @end table 6265 6266 The options work exactly like the S/390 specific command line 6267 options (without the prefix @option{-m}) except that they do not 6268 change any feature macros. For example, 6269 6270 @smallexample 6271 @code{target("no-vx")} 6272 @end smallexample 6273 6274 does not undefine the @code{__VEC__} macro. 6275 @end table 6276 6277 @node SH Function Attributes 6278 @subsection SH Function Attributes 6279 6280 These function attributes are supported on the SH family of processors: 6281 6282 @table @code 6283 @item function_vector 6284 @cindex @code{function_vector} function attribute, SH 6285 @cindex calling functions through the function vector on SH2A 6286 On SH2A targets, this attribute declares a function to be called using the 6287 TBR relative addressing mode. The argument to this attribute is the entry 6288 number of the same function in a vector table containing all the TBR 6289 relative addressable functions. For correct operation the TBR must be setup 6290 accordingly to point to the start of the vector table before any functions with 6291 this attribute are invoked. Usually a good place to do the initialization is 6292 the startup routine. The TBR relative vector table can have at max 256 function 6293 entries. The jumps to these functions are generated using a SH2A specific, 6294 non delayed branch instruction JSR/N @@(disp8,TBR). You must use GAS and GLD 6295 from GNU binutils version 2.7 or later for this attribute to work correctly. 6296 6297 In an application, for a function being called once, this attribute 6298 saves at least 8 bytes of code; and if other successive calls are being 6299 made to the same function, it saves 2 bytes of code per each of these 6300 calls. 6301 6302 @item interrupt_handler 6303 @cindex @code{interrupt_handler} function attribute, SH 6304 Use this attribute to 6305 indicate that the specified function is an interrupt handler. The compiler 6306 generates function entry and exit sequences suitable for use in an 6307 interrupt handler when this attribute is present. 6308 6309 @item nosave_low_regs 6310 @cindex @code{nosave_low_regs} function attribute, SH 6311 Use this attribute on SH targets to indicate that an @code{interrupt_handler} 6312 function should not save and restore registers R0..R7. This can be used on SH3* 6313 and SH4* targets that have a second R0..R7 register bank for non-reentrant 6314 interrupt handlers. 6315 6316 @item renesas 6317 @cindex @code{renesas} function attribute, SH 6318 On SH targets this attribute specifies that the function or struct follows the 6319 Renesas ABI. 6320 6321 @item resbank 6322 @cindex @code{resbank} function attribute, SH 6323 On the SH2A target, this attribute enables the high-speed register 6324 saving and restoration using a register bank for @code{interrupt_handler} 6325 routines. Saving to the bank is performed automatically after the CPU 6326 accepts an interrupt that uses a register bank. 6327 6328 The nineteen 32-bit registers comprising general register R0 to R14, 6329 control register GBR, and system registers MACH, MACL, and PR and the 6330 vector table address offset are saved into a register bank. Register 6331 banks are stacked in first-in last-out (FILO) sequence. Restoration 6332 from the bank is executed by issuing a RESBANK instruction. 6333 6334 @item sp_switch 6335 @cindex @code{sp_switch} function attribute, SH 6336 Use this attribute on the SH to indicate an @code{interrupt_handler} 6337 function should switch to an alternate stack. It expects a string 6338 argument that names a global variable holding the address of the 6339 alternate stack. 6340 6341 @smallexample 6342 void *alt_stack; 6343 void f () __attribute__ ((interrupt_handler, 6344 sp_switch ("alt_stack"))); 6345 @end smallexample 6346 6347 @item trap_exit 6348 @cindex @code{trap_exit} function attribute, SH 6349 Use this attribute on the SH for an @code{interrupt_handler} to return using 6350 @code{trapa} instead of @code{rte}. This attribute expects an integer 6351 argument specifying the trap number to be used. 6352 6353 @item trapa_handler 6354 @cindex @code{trapa_handler} function attribute, SH 6355 On SH targets this function attribute is similar to @code{interrupt_handler} 6356 but it does not save and restore all registers. 6357 @end table 6358 6359 @node Symbian OS Function Attributes 6360 @subsection Symbian OS Function Attributes 6361 6362 @xref{Microsoft Windows Function Attributes}, for discussion of the 6363 @code{dllexport} and @code{dllimport} attributes. 6364 6365 @node V850 Function Attributes 6366 @subsection V850 Function Attributes 6367 6368 The V850 back end supports these function attributes: 6369 6370 @table @code 6371 @item interrupt 6372 @itemx interrupt_handler 6373 @cindex @code{interrupt} function attribute, V850 6374 @cindex @code{interrupt_handler} function attribute, V850 6375 Use these attributes to indicate 6376 that the specified function is an interrupt handler. The compiler generates 6377 function entry and exit sequences suitable for use in an interrupt handler 6378 when either attribute is present. 6379 @end table 6380 6381 @node Visium Function Attributes 6382 @subsection Visium Function Attributes 6383 6384 These function attributes are supported by the Visium back end: 6385 6386 @table @code 6387 @item interrupt 6388 @cindex @code{interrupt} function attribute, Visium 6389 Use this attribute to indicate 6390 that the specified function is an interrupt handler. The compiler generates 6391 function entry and exit sequences suitable for use in an interrupt handler 6392 when this attribute is present. 6393 @end table 6394 6395 @node x86 Function Attributes 6396 @subsection x86 Function Attributes 6397 6398 These function attributes are supported by the x86 back end: 6399 6400 @table @code 6401 @item cdecl 6402 @cindex @code{cdecl} function attribute, x86-32 6403 @cindex functions that pop the argument stack on x86-32 6404 @opindex mrtd 6405 On the x86-32 targets, the @code{cdecl} attribute causes the compiler to 6406 assume that the calling function pops off the stack space used to 6407 pass arguments. This is 6408 useful to override the effects of the @option{-mrtd} switch. 6409 6410 @item fastcall 6411 @cindex @code{fastcall} function attribute, x86-32 6412 @cindex functions that pop the argument stack on x86-32 6413 On x86-32 targets, the @code{fastcall} attribute causes the compiler to 6414 pass the first argument (if of integral type) in the register ECX and 6415 the second argument (if of integral type) in the register EDX@. Subsequent 6416 and other typed arguments are passed on the stack. The called function 6417 pops the arguments off the stack. If the number of arguments is variable all 6418 arguments are pushed on the stack. 6419 6420 @item thiscall 6421 @cindex @code{thiscall} function attribute, x86-32 6422 @cindex functions that pop the argument stack on x86-32 6423 On x86-32 targets, the @code{thiscall} attribute causes the compiler to 6424 pass the first argument (if of integral type) in the register ECX. 6425 Subsequent and other typed arguments are passed on the stack. The called 6426 function pops the arguments off the stack. 6427 If the number of arguments is variable all arguments are pushed on the 6428 stack. 6429 The @code{thiscall} attribute is intended for C++ non-static member functions. 6430 As a GCC extension, this calling convention can be used for C functions 6431 and for static member methods. 6432 6433 @item ms_abi 6434 @itemx sysv_abi 6435 @cindex @code{ms_abi} function attribute, x86 6436 @cindex @code{sysv_abi} function attribute, x86 6437 6438 On 32-bit and 64-bit x86 targets, you can use an ABI attribute 6439 to indicate which calling convention should be used for a function. The 6440 @code{ms_abi} attribute tells the compiler to use the Microsoft ABI, 6441 while the @code{sysv_abi} attribute tells the compiler to use the System V 6442 ELF ABI, which is used on GNU/Linux and other systems. The default is to use 6443 the Microsoft ABI when targeting Windows. On all other systems, the default 6444 is the System V ELF ABI. 6445 6446 Note, the @code{ms_abi} attribute for Microsoft Windows 64-bit targets currently 6447 requires the @option{-maccumulate-outgoing-args} option. 6448 6449 @item callee_pop_aggregate_return (@var{number}) 6450 @cindex @code{callee_pop_aggregate_return} function attribute, x86 6451 6452 On x86-32 targets, you can use this attribute to control how 6453 aggregates are returned in memory. If the caller is responsible for 6454 popping the hidden pointer together with the rest of the arguments, specify 6455 @var{number} equal to zero. If callee is responsible for popping the 6456 hidden pointer, specify @var{number} equal to one. 6457 6458 The default x86-32 ABI assumes that the callee pops the 6459 stack for hidden pointer. However, on x86-32 Microsoft Windows targets, 6460 the compiler assumes that the 6461 caller pops the stack for hidden pointer. 6462 6463 @item ms_hook_prologue 6464 @cindex @code{ms_hook_prologue} function attribute, x86 6465 6466 On 32-bit and 64-bit x86 targets, you can use 6467 this function attribute to make GCC generate the ``hot-patching'' function 6468 prologue used in Win32 API functions in Microsoft Windows XP Service Pack 2 6469 and newer. 6470 6471 @item naked 6472 @cindex @code{naked} function attribute, x86 6473 This attribute allows the compiler to construct the 6474 requisite function declaration, while allowing the body of the 6475 function to be assembly code. The specified function will not have 6476 prologue/epilogue sequences generated by the compiler. Only basic 6477 @code{asm} statements can safely be included in naked functions 6478 (@pxref{Basic Asm}). While using extended @code{asm} or a mixture of 6479 basic @code{asm} and C code may appear to work, they cannot be 6480 depended upon to work reliably and are not supported. 6481 6482 @item regparm (@var{number}) 6483 @cindex @code{regparm} function attribute, x86 6484 @cindex functions that are passed arguments in registers on x86-32 6485 On x86-32 targets, the @code{regparm} attribute causes the compiler to 6486 pass arguments number one to @var{number} if they are of integral type 6487 in registers EAX, EDX, and ECX instead of on the stack. Functions that 6488 take a variable number of arguments continue to be passed all of their 6489 arguments on the stack. 6490 6491 Beware that on some ELF systems this attribute is unsuitable for 6492 global functions in shared libraries with lazy binding (which is the 6493 default). Lazy binding sends the first call via resolving code in 6494 the loader, which might assume EAX, EDX and ECX can be clobbered, as 6495 per the standard calling conventions. Solaris 8 is affected by this. 6496 Systems with the GNU C Library version 2.1 or higher 6497 and FreeBSD are believed to be 6498 safe since the loaders there save EAX, EDX and ECX. (Lazy binding can be 6499 disabled with the linker or the loader if desired, to avoid the 6500 problem.) 6501 6502 @item sseregparm 6503 @cindex @code{sseregparm} function attribute, x86 6504 On x86-32 targets with SSE support, the @code{sseregparm} attribute 6505 causes the compiler to pass up to 3 floating-point arguments in 6506 SSE registers instead of on the stack. Functions that take a 6507 variable number of arguments continue to pass all of their 6508 floating-point arguments on the stack. 6509 6510 @item force_align_arg_pointer 6511 @cindex @code{force_align_arg_pointer} function attribute, x86 6512 On x86 targets, the @code{force_align_arg_pointer} attribute may be 6513 applied to individual function definitions, generating an alternate 6514 prologue and epilogue that realigns the run-time stack if necessary. 6515 This supports mixing legacy codes that run with a 4-byte aligned stack 6516 with modern codes that keep a 16-byte stack for SSE compatibility. 6517 6518 @item stdcall 6519 @cindex @code{stdcall} function attribute, x86-32 6520 @cindex functions that pop the argument stack on x86-32 6521 On x86-32 targets, the @code{stdcall} attribute causes the compiler to 6522 assume that the called function pops off the stack space used to 6523 pass arguments, unless it takes a variable number of arguments. 6524 6525 @item no_caller_saved_registers 6526 @cindex @code{no_caller_saved_registers} function attribute, x86 6527 Use this attribute to indicate that the specified function has no 6528 caller-saved registers. That is, all registers are callee-saved. For 6529 example, this attribute can be used for a function called from an 6530 interrupt handler. The compiler generates proper function entry and 6531 exit sequences to save and restore any modified registers, except for 6532 the EFLAGS register. Since GCC doesn't preserve SSE, MMX nor x87 6533 states, the GCC option @option{-mgeneral-regs-only} should be used to 6534 compile functions with @code{no_caller_saved_registers} attribute. 6535 6536 @item interrupt 6537 @cindex @code{interrupt} function attribute, x86 6538 Use this attribute to indicate that the specified function is an 6539 interrupt handler or an exception handler (depending on parameters passed 6540 to the function, explained further). The compiler generates function 6541 entry and exit sequences suitable for use in an interrupt handler when 6542 this attribute is present. The @code{IRET} instruction, instead of the 6543 @code{RET} instruction, is used to return from interrupt handlers. All 6544 registers, except for the EFLAGS register which is restored by the 6545 @code{IRET} instruction, are preserved by the compiler. Since GCC 6546 doesn't preserve SSE, MMX nor x87 states, the GCC option 6547 @option{-mgeneral-regs-only} should be used to compile interrupt and 6548 exception handlers. 6549 6550 Any interruptible-without-stack-switch code must be compiled with 6551 @option{-mno-red-zone} since interrupt handlers can and will, because 6552 of the hardware design, touch the red zone. 6553 6554 An interrupt handler must be declared with a mandatory pointer 6555 argument: 6556 6557 @smallexample 6558 struct interrupt_frame; 6559 6560 __attribute__ ((interrupt)) 6561 void 6562 f (struct interrupt_frame *frame) 6563 @{ 6564 @} 6565 @end smallexample 6566 6567 @noindent 6568 and you must define @code{struct interrupt_frame} as described in the 6569 processor's manual. 6570 6571 Exception handlers differ from interrupt handlers because the system 6572 pushes an error code on the stack. An exception handler declaration is 6573 similar to that for an interrupt handler, but with a different mandatory 6574 function signature. The compiler arranges to pop the error code off the 6575 stack before the @code{IRET} instruction. 6576 6577 @smallexample 6578 #ifdef __x86_64__ 6579 typedef unsigned long long int uword_t; 6580 #else 6581 typedef unsigned int uword_t; 6582 #endif 6583 6584 struct interrupt_frame; 6585 6586 __attribute__ ((interrupt)) 6587 void 6588 f (struct interrupt_frame *frame, uword_t error_code) 6589 @{ 6590 ... 6591 @} 6592 @end smallexample 6593 6594 Exception handlers should only be used for exceptions that push an error 6595 code; you should use an interrupt handler in other cases. The system 6596 will crash if the wrong kind of handler is used. 6597 6598 @item target (@var{options}) 6599 @cindex @code{target} function attribute 6600 As discussed in @ref{Common Function Attributes}, this attribute 6601 allows specification of target-specific compilation options. 6602 6603 On the x86, the following options are allowed: 6604 @table @samp 6605 @item 3dnow 6606 @itemx no-3dnow 6607 @cindex @code{target("3dnow")} function attribute, x86 6608 Enable/disable the generation of the 3DNow!@: instructions. 6609 6610 @item 3dnowa 6611 @itemx no-3dnowa 6612 @cindex @code{target("3dnowa")} function attribute, x86 6613 Enable/disable the generation of the enhanced 3DNow!@: instructions. 6614 6615 @item abm 6616 @itemx no-abm 6617 @cindex @code{target("abm")} function attribute, x86 6618 Enable/disable the generation of the advanced bit instructions. 6619 6620 @item adx 6621 @itemx no-adx 6622 @cindex @code{target("adx")} function attribute, x86 6623 Enable/disable the generation of the ADX instructions. 6624 6625 @item aes 6626 @itemx no-aes 6627 @cindex @code{target("aes")} function attribute, x86 6628 Enable/disable the generation of the AES instructions. 6629 6630 @item avx 6631 @itemx no-avx 6632 @cindex @code{target("avx")} function attribute, x86 6633 Enable/disable the generation of the AVX instructions. 6634 6635 @item avx2 6636 @itemx no-avx2 6637 @cindex @code{target("avx2")} function attribute, x86 6638 Enable/disable the generation of the AVX2 instructions. 6639 6640 @item avx5124fmaps 6641 @itemx no-avx5124fmaps 6642 @cindex @code{target("avx5124fmaps")} function attribute, x86 6643 Enable/disable the generation of the AVX5124FMAPS instructions. 6644 6645 @item avx5124vnniw 6646 @itemx no-avx5124vnniw 6647 @cindex @code{target("avx5124vnniw")} function attribute, x86 6648 Enable/disable the generation of the AVX5124VNNIW instructions. 6649 6650 @item avx512bitalg 6651 @itemx no-avx512bitalg 6652 @cindex @code{target("avx512bitalg")} function attribute, x86 6653 Enable/disable the generation of the AVX512BITALG instructions. 6654 6655 @item avx512bw 6656 @itemx no-avx512bw 6657 @cindex @code{target("avx512bw")} function attribute, x86 6658 Enable/disable the generation of the AVX512BW instructions. 6659 6660 @item avx512cd 6661 @itemx no-avx512cd 6662 @cindex @code{target("avx512cd")} function attribute, x86 6663 Enable/disable the generation of the AVX512CD instructions. 6664 6665 @item avx512dq 6666 @itemx no-avx512dq 6667 @cindex @code{target("avx512dq")} function attribute, x86 6668 Enable/disable the generation of the AVX512DQ instructions. 6669 6670 @item avx512er 6671 @itemx no-avx512er 6672 @cindex @code{target("avx512er")} function attribute, x86 6673 Enable/disable the generation of the AVX512ER instructions. 6674 6675 @item avx512f 6676 @itemx no-avx512f 6677 @cindex @code{target("avx512f")} function attribute, x86 6678 Enable/disable the generation of the AVX512F instructions. 6679 6680 @item avx512ifma 6681 @itemx no-avx512ifma 6682 @cindex @code{target("avx512ifma")} function attribute, x86 6683 Enable/disable the generation of the AVX512IFMA instructions. 6684 6685 @item avx512pf 6686 @itemx no-avx512pf 6687 @cindex @code{target("avx512pf")} function attribute, x86 6688 Enable/disable the generation of the AVX512PF instructions. 6689 6690 @item avx512vbmi 6691 @itemx no-avx512vbmi 6692 @cindex @code{target("avx512vbmi")} function attribute, x86 6693 Enable/disable the generation of the AVX512VBMI instructions. 6694 6695 @item avx512vbmi2 6696 @itemx no-avx512vbmi2 6697 @cindex @code{target("avx512vbmi2")} function attribute, x86 6698 Enable/disable the generation of the AVX512VBMI2 instructions. 6699 6700 @item avx512vl 6701 @itemx no-avx512vl 6702 @cindex @code{target("avx512vl")} function attribute, x86 6703 Enable/disable the generation of the AVX512VL instructions. 6704 6705 @item avx512vnni 6706 @itemx no-avx512vnni 6707 @cindex @code{target("avx512vnni")} function attribute, x86 6708 Enable/disable the generation of the AVX512VNNI instructions. 6709 6710 @item avx512vpopcntdq 6711 @itemx no-avx512vpopcntdq 6712 @cindex @code{target("avx512vpopcntdq")} function attribute, x86 6713 Enable/disable the generation of the AVX512VPOPCNTDQ instructions. 6714 6715 @item bmi 6716 @itemx no-bmi 6717 @cindex @code{target("bmi")} function attribute, x86 6718 Enable/disable the generation of the BMI instructions. 6719 6720 @item bmi2 6721 @itemx no-bmi2 6722 @cindex @code{target("bmi2")} function attribute, x86 6723 Enable/disable the generation of the BMI2 instructions. 6724 6725 @item cldemote 6726 @itemx no-cldemote 6727 @cindex @code{target("cldemote")} function attribute, x86 6728 Enable/disable the generation of the CLDEMOTE instructions. 6729 6730 @item clflushopt 6731 @itemx no-clflushopt 6732 @cindex @code{target("clflushopt")} function attribute, x86 6733 Enable/disable the generation of the CLFLUSHOPT instructions. 6734 6735 @item clwb 6736 @itemx no-clwb 6737 @cindex @code{target("clwb")} function attribute, x86 6738 Enable/disable the generation of the CLWB instructions. 6739 6740 @item clzero 6741 @itemx no-clzero 6742 @cindex @code{target("clzero")} function attribute, x86 6743 Enable/disable the generation of the CLZERO instructions. 6744 6745 @item crc32 6746 @itemx no-crc32 6747 @cindex @code{target("crc32")} function attribute, x86 6748 Enable/disable the generation of the CRC32 instructions. 6749 6750 @item cx16 6751 @itemx no-cx16 6752 @cindex @code{target("cx16")} function attribute, x86 6753 Enable/disable the generation of the CMPXCHG16B instructions. 6754 6755 @item default 6756 @cindex @code{target("default")} function attribute, x86 6757 @xref{Function Multiversioning}, where it is used to specify the 6758 default function version. 6759 6760 @item f16c 6761 @itemx no-f16c 6762 @cindex @code{target("f16c")} function attribute, x86 6763 Enable/disable the generation of the F16C instructions. 6764 6765 @item fma 6766 @itemx no-fma 6767 @cindex @code{target("fma")} function attribute, x86 6768 Enable/disable the generation of the FMA instructions. 6769 6770 @item fma4 6771 @itemx no-fma4 6772 @cindex @code{target("fma4")} function attribute, x86 6773 Enable/disable the generation of the FMA4 instructions. 6774 6775 @item fsgsbase 6776 @itemx no-fsgsbase 6777 @cindex @code{target("fsgsbase")} function attribute, x86 6778 Enable/disable the generation of the FSGSBASE instructions. 6779 6780 @item fxsr 6781 @itemx no-fxsr 6782 @cindex @code{target("fxsr")} function attribute, x86 6783 Enable/disable the generation of the FXSR instructions. 6784 6785 @item gfni 6786 @itemx no-gfni 6787 @cindex @code{target("gfni")} function attribute, x86 6788 Enable/disable the generation of the GFNI instructions. 6789 6790 @item hle 6791 @itemx no-hle 6792 @cindex @code{target("hle")} function attribute, x86 6793 Enable/disable the generation of the HLE instruction prefixes. 6794 6795 @item lwp 6796 @itemx no-lwp 6797 @cindex @code{target("lwp")} function attribute, x86 6798 Enable/disable the generation of the LWP instructions. 6799 6800 @item lzcnt 6801 @itemx no-lzcnt 6802 @cindex @code{target("lzcnt")} function attribute, x86 6803 Enable/disable the generation of the LZCNT instructions. 6804 6805 @item mmx 6806 @itemx no-mmx 6807 @cindex @code{target("mmx")} function attribute, x86 6808 Enable/disable the generation of the MMX instructions. 6809 6810 @item movbe 6811 @itemx no-movbe 6812 @cindex @code{target("movbe")} function attribute, x86 6813 Enable/disable the generation of the MOVBE instructions. 6814 6815 @item movdir64b 6816 @itemx no-movdir64b 6817 @cindex @code{target("movdir64b")} function attribute, x86 6818 Enable/disable the generation of the MOVDIR64B instructions. 6819 6820 @item movdiri 6821 @itemx no-movdiri 6822 @cindex @code{target("movdiri")} function attribute, x86 6823 Enable/disable the generation of the MOVDIRI instructions. 6824 6825 @item mwait 6826 @itemx no-mwait 6827 @cindex @code{target("mwait")} function attribute, x86 6828 Enable/disable the generation of the MWAIT and MONITOR instructions. 6829 6830 @item mwaitx 6831 @itemx no-mwaitx 6832 @cindex @code{target("mwaitx")} function attribute, x86 6833 Enable/disable the generation of the MWAITX instructions. 6834 6835 @item pclmul 6836 @itemx no-pclmul 6837 @cindex @code{target("pclmul")} function attribute, x86 6838 Enable/disable the generation of the PCLMUL instructions. 6839 6840 @item pconfig 6841 @itemx no-pconfig 6842 @cindex @code{target("pconfig")} function attribute, x86 6843 Enable/disable the generation of the PCONFIG instructions. 6844 6845 @item pku 6846 @itemx no-pku 6847 @cindex @code{target("pku")} function attribute, x86 6848 Enable/disable the generation of the PKU instructions. 6849 6850 @item popcnt 6851 @itemx no-popcnt 6852 @cindex @code{target("popcnt")} function attribute, x86 6853 Enable/disable the generation of the POPCNT instruction. 6854 6855 @item prefetchwt1 6856 @itemx no-prefetchwt1 6857 @cindex @code{target("prefetchwt1")} function attribute, x86 6858 Enable/disable the generation of the PREFETCHWT1 instructions. 6859 6860 @item prfchw 6861 @itemx no-prfchw 6862 @cindex @code{target("prfchw")} function attribute, x86 6863 Enable/disable the generation of the PREFETCHW instruction. 6864 6865 @item ptwrite 6866 @itemx no-ptwrite 6867 @cindex @code{target("ptwrite")} function attribute, x86 6868 Enable/disable the generation of the PTWRITE instructions. 6869 6870 @item rdpid 6871 @itemx no-rdpid 6872 @cindex @code{target("rdpid")} function attribute, x86 6873 Enable/disable the generation of the RDPID instructions. 6874 6875 @item rdrnd 6876 @itemx no-rdrnd 6877 @cindex @code{target("rdrnd")} function attribute, x86 6878 Enable/disable the generation of the RDRND instructions. 6879 6880 @item rdseed 6881 @itemx no-rdseed 6882 @cindex @code{target("rdseed")} function attribute, x86 6883 Enable/disable the generation of the RDSEED instructions. 6884 6885 @item rtm 6886 @itemx no-rtm 6887 @cindex @code{target("rtm")} function attribute, x86 6888 Enable/disable the generation of the RTM instructions. 6889 6890 @item sahf 6891 @itemx no-sahf 6892 @cindex @code{target("sahf")} function attribute, x86 6893 Enable/disable the generation of the SAHF instructions. 6894 6895 @item sgx 6896 @itemx no-sgx 6897 @cindex @code{target("sgx")} function attribute, x86 6898 Enable/disable the generation of the SGX instructions. 6899 6900 @item sha 6901 @itemx no-sha 6902 @cindex @code{target("sha")} function attribute, x86 6903 Enable/disable the generation of the SHA instructions. 6904 6905 @item shstk 6906 @itemx no-shstk 6907 @cindex @code{target("shstk")} function attribute, x86 6908 Enable/disable the shadow stack built-in functions from CET. 6909 6910 @item sse 6911 @itemx no-sse 6912 @cindex @code{target("sse")} function attribute, x86 6913 Enable/disable the generation of the SSE instructions. 6914 6915 @item sse2 6916 @itemx no-sse2 6917 @cindex @code{target("sse2")} function attribute, x86 6918 Enable/disable the generation of the SSE2 instructions. 6919 6920 @item sse3 6921 @itemx no-sse3 6922 @cindex @code{target("sse3")} function attribute, x86 6923 Enable/disable the generation of the SSE3 instructions. 6924 6925 @item sse4 6926 @itemx no-sse4 6927 @cindex @code{target("sse4")} function attribute, x86 6928 Enable/disable the generation of the SSE4 instructions (both SSE4.1 6929 and SSE4.2). 6930 6931 @item sse4.1 6932 @itemx no-sse4.1 6933 @cindex @code{target("sse4.1")} function attribute, x86 6934 Enable/disable the generation of the SSE4.1 instructions. 6935 6936 @item sse4.2 6937 @itemx no-sse4.2 6938 @cindex @code{target("sse4.2")} function attribute, x86 6939 Enable/disable the generation of the SSE4.2 instructions. 6940 6941 @item sse4a 6942 @itemx no-sse4a 6943 @cindex @code{target("sse4a")} function attribute, x86 6944 Enable/disable the generation of the SSE4A instructions. 6945 6946 @item ssse3 6947 @itemx no-ssse3 6948 @cindex @code{target("ssse3")} function attribute, x86 6949 Enable/disable the generation of the SSSE3 instructions. 6950 6951 @item tbm 6952 @itemx no-tbm 6953 @cindex @code{target("tbm")} function attribute, x86 6954 Enable/disable the generation of the TBM instructions. 6955 6956 @item vaes 6957 @itemx no-vaes 6958 @cindex @code{target("vaes")} function attribute, x86 6959 Enable/disable the generation of the VAES instructions. 6960 6961 @item vpclmulqdq 6962 @itemx no-vpclmulqdq 6963 @cindex @code{target("vpclmulqdq")} function attribute, x86 6964 Enable/disable the generation of the VPCLMULQDQ instructions. 6965 6966 @item waitpkg 6967 @itemx no-waitpkg 6968 @cindex @code{target("waitpkg")} function attribute, x86 6969 Enable/disable the generation of the WAITPKG instructions. 6970 6971 @item wbnoinvd 6972 @itemx no-wbnoinvd 6973 @cindex @code{target("wbnoinvd")} function attribute, x86 6974 Enable/disable the generation of the WBNOINVD instructions. 6975 6976 @item xop 6977 @itemx no-xop 6978 @cindex @code{target("xop")} function attribute, x86 6979 Enable/disable the generation of the XOP instructions. 6980 6981 @item xsave 6982 @itemx no-xsave 6983 @cindex @code{target("xsave")} function attribute, x86 6984 Enable/disable the generation of the XSAVE instructions. 6985 6986 @item xsavec 6987 @itemx no-xsavec 6988 @cindex @code{target("xsavec")} function attribute, x86 6989 Enable/disable the generation of the XSAVEC instructions. 6990 6991 @item xsaveopt 6992 @itemx no-xsaveopt 6993 @cindex @code{target("xsaveopt")} function attribute, x86 6994 Enable/disable the generation of the XSAVEOPT instructions. 6995 6996 @item xsaves 6997 @itemx no-xsaves 6998 @cindex @code{target("xsaves")} function attribute, x86 6999 Enable/disable the generation of the XSAVES instructions. 7000 7001 @item amx-tile 7002 @itemx no-amx-tile 7003 @cindex @code{target("amx-tile")} function attribute, x86 7004 Enable/disable the generation of the AMX-TILE instructions. 7005 7006 @item amx-int8 7007 @itemx no-amx-int8 7008 @cindex @code{target("amx-int8")} function attribute, x86 7009 Enable/disable the generation of the AMX-INT8 instructions. 7010 7011 @item amx-bf16 7012 @itemx no-amx-bf16 7013 @cindex @code{target("amx-bf16")} function attribute, x86 7014 Enable/disable the generation of the AMX-BF16 instructions. 7015 7016 @item uintr 7017 @itemx no-uintr 7018 @cindex @code{target("uintr")} function attribute, x86 7019 Enable/disable the generation of the UINTR instructions. 7020 7021 @item hreset 7022 @itemx no-hreset 7023 @cindex @code{target("hreset")} function attribute, x86 7024 Enable/disable the generation of the HRESET instruction. 7025 7026 @item kl 7027 @itemx no-kl 7028 @cindex @code{target("kl")} function attribute, x86 7029 Enable/disable the generation of the KEYLOCKER instructions. 7030 7031 @item widekl 7032 @itemx no-widekl 7033 @cindex @code{target("widekl")} function attribute, x86 7034 Enable/disable the generation of the WIDEKL instructions. 7035 7036 @item avxvnni 7037 @itemx no-avxvnni 7038 @cindex @code{target("avxvnni")} function attribute, x86 7039 Enable/disable the generation of the AVXVNNI instructions. 7040 7041 @item cld 7042 @itemx no-cld 7043 @cindex @code{target("cld")} function attribute, x86 7044 Enable/disable the generation of the CLD before string moves. 7045 7046 @item fancy-math-387 7047 @itemx no-fancy-math-387 7048 @cindex @code{target("fancy-math-387")} function attribute, x86 7049 Enable/disable the generation of the @code{sin}, @code{cos}, and 7050 @code{sqrt} instructions on the 387 floating-point unit. 7051 7052 @item ieee-fp 7053 @itemx no-ieee-fp 7054 @cindex @code{target("ieee-fp")} function attribute, x86 7055 Enable/disable the generation of floating point that depends on IEEE arithmetic. 7056 7057 @item inline-all-stringops 7058 @itemx no-inline-all-stringops 7059 @cindex @code{target("inline-all-stringops")} function attribute, x86 7060 Enable/disable inlining of string operations. 7061 7062 @item inline-stringops-dynamically 7063 @itemx no-inline-stringops-dynamically 7064 @cindex @code{target("inline-stringops-dynamically")} function attribute, x86 7065 Enable/disable the generation of the inline code to do small string 7066 operations and calling the library routines for large operations. 7067 7068 @item align-stringops 7069 @itemx no-align-stringops 7070 @cindex @code{target("align-stringops")} function attribute, x86 7071 Do/do not align destination of inlined string operations. 7072 7073 @item recip 7074 @itemx no-recip 7075 @cindex @code{target("recip")} function attribute, x86 7076 Enable/disable the generation of RCPSS, RCPPS, RSQRTSS and RSQRTPS 7077 instructions followed an additional Newton-Raphson step instead of 7078 doing a floating-point division. 7079 7080 @item general-regs-only 7081 @cindex @code{target("general-regs-only")} function attribute, x86 7082 Generate code which uses only the general registers. 7083 7084 @item arch=@var{ARCH} 7085 @cindex @code{target("arch=@var{ARCH}")} function attribute, x86 7086 Specify the architecture to generate code for in compiling the function. 7087 7088 @item tune=@var{TUNE} 7089 @cindex @code{target("tune=@var{TUNE}")} function attribute, x86 7090 Specify the architecture to tune for in compiling the function. 7091 7092 @item fpmath=@var{FPMATH} 7093 @cindex @code{target("fpmath=@var{FPMATH}")} function attribute, x86 7094 Specify which floating-point unit to use. You must specify the 7095 @code{target("fpmath=sse,387")} option as 7096 @code{target("fpmath=sse+387")} because the comma would separate 7097 different options. 7098 7099 @item prefer-vector-width=@var{OPT} 7100 @cindex @code{prefer-vector-width} function attribute, x86 7101 On x86 targets, the @code{prefer-vector-width} attribute informs the 7102 compiler to use @var{OPT}-bit vector width in instructions 7103 instead of the default on the selected platform. 7104 7105 Valid @var{OPT} values are: 7106 7107 @table @samp 7108 @item none 7109 No extra limitations applied to GCC other than defined by the selected platform. 7110 7111 @item 128 7112 Prefer 128-bit vector width for instructions. 7113 7114 @item 256 7115 Prefer 256-bit vector width for instructions. 7116 7117 @item 512 7118 Prefer 512-bit vector width for instructions. 7119 @end table 7120 7121 On the x86, the inliner does not inline a 7122 function that has different target options than the caller, unless the 7123 callee has a subset of the target options of the caller. For example 7124 a function declared with @code{target("sse3")} can inline a function 7125 with @code{target("sse2")}, since @code{-msse3} implies @code{-msse2}. 7126 @end table 7127 7128 @item indirect_branch("@var{choice}") 7129 @cindex @code{indirect_branch} function attribute, x86 7130 On x86 targets, the @code{indirect_branch} attribute causes the compiler 7131 to convert indirect call and jump with @var{choice}. @samp{keep} 7132 keeps indirect call and jump unmodified. @samp{thunk} converts indirect 7133 call and jump to call and return thunk. @samp{thunk-inline} converts 7134 indirect call and jump to inlined call and return thunk. 7135 @samp{thunk-extern} converts indirect call and jump to external call 7136 and return thunk provided in a separate object file. 7137 7138 @item function_return("@var{choice}") 7139 @cindex @code{function_return} function attribute, x86 7140 On x86 targets, the @code{function_return} attribute causes the compiler 7141 to convert function return with @var{choice}. @samp{keep} keeps function 7142 return unmodified. @samp{thunk} converts function return to call and 7143 return thunk. @samp{thunk-inline} converts function return to inlined 7144 call and return thunk. @samp{thunk-extern} converts function return to 7145 external call and return thunk provided in a separate object file. 7146 7147 @item nocf_check 7148 @cindex @code{nocf_check} function attribute 7149 The @code{nocf_check} attribute on a function is used to inform the 7150 compiler that the function's prologue should not be instrumented when 7151 compiled with the @option{-fcf-protection=branch} option. The 7152 compiler assumes that the function's address is a valid target for a 7153 control-flow transfer. 7154 7155 The @code{nocf_check} attribute on a type of pointer to function is 7156 used to inform the compiler that a call through the pointer should 7157 not be instrumented when compiled with the 7158 @option{-fcf-protection=branch} option. The compiler assumes 7159 that the function's address from the pointer is a valid target for 7160 a control-flow transfer. A direct function call through a function 7161 name is assumed to be a safe call thus direct calls are not 7162 instrumented by the compiler. 7163 7164 The @code{nocf_check} attribute is applied to an object's type. 7165 In case of assignment of a function address or a function pointer to 7166 another pointer, the attribute is not carried over from the right-hand 7167 object's type; the type of left-hand object stays unchanged. The 7168 compiler checks for @code{nocf_check} attribute mismatch and reports 7169 a warning in case of mismatch. 7170 7171 @smallexample 7172 @{ 7173 int foo (void) __attribute__(nocf_check); 7174 void (*foo1)(void) __attribute__(nocf_check); 7175 void (*foo2)(void); 7176 7177 /* foo's address is assumed to be valid. */ 7178 int 7179 foo (void) 7180 7181 /* This call site is not checked for control-flow 7182 validity. */ 7183 (*foo1)(); 7184 7185 /* A warning is issued about attribute mismatch. */ 7186 foo1 = foo2; 7187 7188 /* This call site is still not checked. */ 7189 (*foo1)(); 7190 7191 /* This call site is checked. */ 7192 (*foo2)(); 7193 7194 /* A warning is issued about attribute mismatch. */ 7195 foo2 = foo1; 7196 7197 /* This call site is still checked. */ 7198 (*foo2)(); 7199 7200 return 0; 7201 @} 7202 @end smallexample 7203 7204 @item cf_check 7205 @cindex @code{cf_check} function attribute, x86 7206 7207 The @code{cf_check} attribute on a function is used to inform the 7208 compiler that ENDBR instruction should be placed at the function 7209 entry when @option{-fcf-protection=branch} is enabled. 7210 7211 @item indirect_return 7212 @cindex @code{indirect_return} function attribute, x86 7213 7214 The @code{indirect_return} attribute can be applied to a function, 7215 as well as variable or type of function pointer to inform the 7216 compiler that the function may return via indirect branch. 7217 7218 @item fentry_name("@var{name}") 7219 @cindex @code{fentry_name} function attribute, x86 7220 On x86 targets, the @code{fentry_name} attribute sets the function to 7221 call on function entry when function instrumentation is enabled 7222 with @option{-pg -mfentry}. When @var{name} is nop then a 5 byte 7223 nop sequence is generated. 7224 7225 @item fentry_section("@var{name}") 7226 @cindex @code{fentry_section} function attribute, x86 7227 On x86 targets, the @code{fentry_section} attribute sets the name 7228 of the section to record function entry instrumentation calls in when 7229 enabled with @option{-pg -mrecord-mcount} 7230 7231 @item nodirect_extern_access 7232 @cindex @code{nodirect_extern_access} function attribute 7233 @opindex mno-direct-extern-access 7234 This attribute, attached to a global variable or function, is the 7235 counterpart to option @option{-mno-direct-extern-access}. 7236 7237 @end table 7238 7239 @node Xstormy16 Function Attributes 7240 @subsection Xstormy16 Function Attributes 7241 7242 These function attributes are supported by the Xstormy16 back end: 7243 7244 @table @code 7245 @item interrupt 7246 @cindex @code{interrupt} function attribute, Xstormy16 7247 Use this attribute to indicate 7248 that the specified function is an interrupt handler. The compiler generates 7249 function entry and exit sequences suitable for use in an interrupt handler 7250 when this attribute is present. 7251 @end table 7252 7253 @node Variable Attributes 7254 @section Specifying Attributes of Variables 7255 @cindex attribute of variables 7256 @cindex variable attributes 7257 7258 The keyword @code{__attribute__} allows you to specify special properties 7259 of variables, function parameters, or structure, union, and, in C++, class 7260 members. This @code{__attribute__} keyword is followed by an attribute 7261 specification enclosed in double parentheses. Some attributes are currently 7262 defined generically for variables. Other attributes are defined for 7263 variables on particular target systems. Other attributes are available 7264 for functions (@pxref{Function Attributes}), labels (@pxref{Label Attributes}), 7265 enumerators (@pxref{Enumerator Attributes}), statements 7266 (@pxref{Statement Attributes}), and for types (@pxref{Type Attributes}). 7267 Other front ends might define more attributes 7268 (@pxref{C++ Extensions,,Extensions to the C++ Language}). 7269 7270 @xref{Attribute Syntax}, for details of the exact syntax for using 7271 attributes. 7272 7273 @menu 7274 * Common Variable Attributes:: 7275 * ARC Variable Attributes:: 7276 * AVR Variable Attributes:: 7277 * Blackfin Variable Attributes:: 7278 * H8/300 Variable Attributes:: 7279 * IA-64 Variable Attributes:: 7280 * M32R/D Variable Attributes:: 7281 * MeP Variable Attributes:: 7282 * Microsoft Windows Variable Attributes:: 7283 * MSP430 Variable Attributes:: 7284 * Nvidia PTX Variable Attributes:: 7285 * PowerPC Variable Attributes:: 7286 * RL78 Variable Attributes:: 7287 * V850 Variable Attributes:: 7288 * x86 Variable Attributes:: 7289 * Xstormy16 Variable Attributes:: 7290 @end menu 7291 7292 @node Common Variable Attributes 7293 @subsection Common Variable Attributes 7294 7295 The following attributes are supported on most targets. 7296 7297 @table @code 7298 7299 @item alias ("@var{target}") 7300 @cindex @code{alias} variable attribute 7301 The @code{alias} variable attribute causes the declaration to be emitted 7302 as an alias for another symbol known as an @dfn{alias target}. Except 7303 for top-level qualifiers the alias target must have the same type as 7304 the alias. For instance, the following 7305 7306 @smallexample 7307 int var_target; 7308 extern int __attribute__ ((alias ("var_target"))) var_alias; 7309 @end smallexample 7310 7311 @noindent 7312 defines @code{var_alias} to be an alias for the @code{var_target} variable. 7313 7314 It is an error if the alias target is not defined in the same translation 7315 unit as the alias. 7316 7317 Note that in the absence of the attribute GCC assumes that distinct 7318 declarations with external linkage denote distinct objects. Using both 7319 the alias and the alias target to access the same object is undefined 7320 in a translation unit without a declaration of the alias with the attribute. 7321 7322 This attribute requires assembler and object file support, and may not be 7323 available on all targets. 7324 7325 @cindex @code{aligned} variable attribute 7326 @item aligned 7327 @itemx aligned (@var{alignment}) 7328 The @code{aligned} attribute specifies a minimum alignment for the variable 7329 or structure field, measured in bytes. When specified, @var{alignment} must 7330 be an integer constant power of 2. Specifying no @var{alignment} argument 7331 implies the maximum alignment for the target, which is often, but by no 7332 means always, 8 or 16 bytes. 7333 7334 For example, the declaration: 7335 7336 @smallexample 7337 int x __attribute__ ((aligned (16))) = 0; 7338 @end smallexample 7339 7340 @noindent 7341 causes the compiler to allocate the global variable @code{x} on a 7342 16-byte boundary. On a 68040, this could be used in conjunction with 7343 an @code{asm} expression to access the @code{move16} instruction which 7344 requires 16-byte aligned operands. 7345 7346 You can also specify the alignment of structure fields. For example, to 7347 create a double-word aligned @code{int} pair, you could write: 7348 7349 @smallexample 7350 struct foo @{ int x[2] __attribute__ ((aligned (8))); @}; 7351 @end smallexample 7352 7353 @noindent 7354 This is an alternative to creating a union with a @code{double} member, 7355 which forces the union to be double-word aligned. 7356 7357 As in the preceding examples, you can explicitly specify the alignment 7358 (in bytes) that you wish the compiler to use for a given variable or 7359 structure field. Alternatively, you can leave out the alignment factor 7360 and just ask the compiler to align a variable or field to the 7361 default alignment for the target architecture you are compiling for. 7362 The default alignment is sufficient for all scalar types, but may not be 7363 enough for all vector types on a target that supports vector operations. 7364 The default alignment is fixed for a particular target ABI. 7365 7366 GCC also provides a target specific macro @code{__BIGGEST_ALIGNMENT__}, 7367 which is the largest alignment ever used for any data type on the 7368 target machine you are compiling for. For example, you could write: 7369 7370 @smallexample 7371 short array[3] __attribute__ ((aligned (__BIGGEST_ALIGNMENT__))); 7372 @end smallexample 7373 7374 The compiler automatically sets the alignment for the declared 7375 variable or field to @code{__BIGGEST_ALIGNMENT__}. Doing this can 7376 often make copy operations more efficient, because the compiler can 7377 use whatever instructions copy the biggest chunks of memory when 7378 performing copies to or from the variables or fields that you have 7379 aligned this way. Note that the value of @code{__BIGGEST_ALIGNMENT__} 7380 may change depending on command-line options. 7381 7382 When used on a struct, or struct member, the @code{aligned} attribute can 7383 only increase the alignment; in order to decrease it, the @code{packed} 7384 attribute must be specified as well. When used as part of a typedef, the 7385 @code{aligned} attribute can both increase and decrease alignment, and 7386 specifying the @code{packed} attribute generates a warning. 7387 7388 Note that the effectiveness of @code{aligned} attributes for static 7389 variables may be limited by inherent limitations in the system linker 7390 and/or object file format. On some systems, the linker is 7391 only able to arrange for variables to be aligned up to a certain maximum 7392 alignment. (For some linkers, the maximum supported alignment may 7393 be very very small.) If your linker is only able to align variables 7394 up to a maximum of 8-byte alignment, then specifying @code{aligned(16)} 7395 in an @code{__attribute__} still only provides you with 8-byte 7396 alignment. See your linker documentation for further information. 7397 7398 Stack variables are not affected by linker restrictions; GCC can properly 7399 align them on any target. 7400 7401 The @code{aligned} attribute can also be used for functions 7402 (@pxref{Common Function Attributes}.) 7403 7404 @cindex @code{warn_if_not_aligned} variable attribute 7405 @item warn_if_not_aligned (@var{alignment}) 7406 This attribute specifies a threshold for the structure field, measured 7407 in bytes. If the structure field is aligned below the threshold, a 7408 warning will be issued. For example, the declaration: 7409 7410 @smallexample 7411 struct foo 7412 @{ 7413 int i1; 7414 int i2; 7415 unsigned long long x __attribute__ ((warn_if_not_aligned (16))); 7416 @}; 7417 @end smallexample 7418 7419 @noindent 7420 causes the compiler to issue an warning on @code{struct foo}, like 7421 @samp{warning: alignment 8 of 'struct foo' is less than 16}. 7422 The compiler also issues a warning, like @samp{warning: 'x' offset 7423 8 in 'struct foo' isn't aligned to 16}, when the structure field has 7424 the misaligned offset: 7425 7426 @smallexample 7427 struct __attribute__ ((aligned (16))) foo 7428 @{ 7429 int i1; 7430 int i2; 7431 unsigned long long x __attribute__ ((warn_if_not_aligned (16))); 7432 @}; 7433 @end smallexample 7434 7435 This warning can be disabled by @option{-Wno-if-not-aligned}. 7436 The @code{warn_if_not_aligned} attribute can also be used for types 7437 (@pxref{Common Type Attributes}.) 7438 7439 @item alloc_size (@var{position}) 7440 @itemx alloc_size (@var{position-1}, @var{position-2}) 7441 @cindex @code{alloc_size} variable attribute 7442 The @code{alloc_size} variable attribute may be applied to the declaration 7443 of a pointer to a function that returns a pointer and takes at least one 7444 argument of an integer type. It indicates that the returned pointer points 7445 to an object whose size is given by the function argument at @var{position}, 7446 or by the product of the arguments at @var{position-1} and @var{position-2}. 7447 Meaningful sizes are positive values less than @code{PTRDIFF_MAX}. Other 7448 sizes are diagnosed when detected. GCC uses this information to improve 7449 the results of @code{__builtin_object_size}. 7450 7451 For instance, the following declarations 7452 7453 @smallexample 7454 typedef __attribute__ ((alloc_size (1, 2))) void* 7455 (*calloc_ptr) (size_t, size_t); 7456 typedef __attribute__ ((alloc_size (1))) void* 7457 (*malloc_ptr) (size_t); 7458 @end smallexample 7459 7460 @noindent 7461 specify that @code{calloc_ptr} is a pointer of a function that, like 7462 the standard C function @code{calloc}, returns an object whose size 7463 is given by the product of arguments 1 and 2, and similarly, that 7464 @code{malloc_ptr}, like the standard C function @code{malloc}, 7465 returns an object whose size is given by argument 1 to the function. 7466 7467 @item cleanup (@var{cleanup_function}) 7468 @cindex @code{cleanup} variable attribute 7469 The @code{cleanup} attribute runs a function when the variable goes 7470 out of scope. This attribute can only be applied to auto function 7471 scope variables; it may not be applied to parameters or variables 7472 with static storage duration. The function must take one parameter, 7473 a pointer to a type compatible with the variable. The return value 7474 of the function (if any) is ignored. 7475 7476 If @option{-fexceptions} is enabled, then @var{cleanup_function} 7477 is run during the stack unwinding that happens during the 7478 processing of the exception. Note that the @code{cleanup} attribute 7479 does not allow the exception to be caught, only to perform an action. 7480 It is undefined what happens if @var{cleanup_function} does not 7481 return normally. 7482 7483 @item common 7484 @itemx nocommon 7485 @cindex @code{common} variable attribute 7486 @cindex @code{nocommon} variable attribute 7487 @opindex fcommon 7488 @opindex fno-common 7489 The @code{common} attribute requests GCC to place a variable in 7490 ``common'' storage. The @code{nocommon} attribute requests the 7491 opposite---to allocate space for it directly. 7492 7493 These attributes override the default chosen by the 7494 @option{-fno-common} and @option{-fcommon} flags respectively. 7495 7496 @item copy 7497 @itemx copy (@var{variable}) 7498 @cindex @code{copy} variable attribute 7499 The @code{copy} attribute applies the set of attributes with which 7500 @var{variable} has been declared to the declaration of the variable 7501 to which the attribute is applied. The attribute is designed for 7502 libraries that define aliases that are expected to specify the same 7503 set of attributes as the aliased symbols. The @code{copy} attribute 7504 can be used with variables, functions or types. However, the kind 7505 of symbol to which the attribute is applied (either varible or 7506 function) must match the kind of symbol to which the argument refers. 7507 The @code{copy} attribute copies only syntactic and semantic attributes 7508 but not attributes that affect a symbol's linkage or visibility such as 7509 @code{alias}, @code{visibility}, or @code{weak}. The @code{deprecated} 7510 attribute is also not copied. @xref{Common Function Attributes}. 7511 @xref{Common Type Attributes}. 7512 7513 @item deprecated 7514 @itemx deprecated (@var{msg}) 7515 @cindex @code{deprecated} variable attribute 7516 The @code{deprecated} attribute results in a warning if the variable 7517 is used anywhere in the source file. This is useful when identifying 7518 variables that are expected to be removed in a future version of a 7519 program. The warning also includes the location of the declaration 7520 of the deprecated variable, to enable users to easily find further 7521 information about why the variable is deprecated, or what they should 7522 do instead. Note that the warning only occurs for uses: 7523 7524 @smallexample 7525 extern int old_var __attribute__ ((deprecated)); 7526 extern int old_var; 7527 int new_fn () @{ return old_var; @} 7528 @end smallexample 7529 7530 @noindent 7531 results in a warning on line 3 but not line 2. The optional @var{msg} 7532 argument, which must be a string, is printed in the warning if 7533 present. 7534 7535 The @code{deprecated} attribute can also be used for functions and 7536 types (@pxref{Common Function Attributes}, 7537 @pxref{Common Type Attributes}). 7538 7539 The message attached to the attribute is affected by the setting of 7540 the @option{-fmessage-length} option. 7541 7542 @item unavailable 7543 @itemx unavailable (@var{msg}) 7544 @cindex @code{unavailable} variable attribute 7545 The @code{unavailable} attribute indicates that the variable so marked 7546 is not available, if it is used anywhere in the source file. It behaves 7547 in the same manner as the @code{deprecated} attribute except that the 7548 compiler will emit an error rather than a warning. 7549 7550 It is expected that items marked as @code{deprecated} will eventually be 7551 withdrawn from interfaces, and then become unavailable. This attribute 7552 allows for marking them appropriately. 7553 7554 The @code{unavailable} attribute can also be used for functions and 7555 types (@pxref{Common Function Attributes}, 7556 @pxref{Common Type Attributes}). 7557 7558 @item mode (@var{mode}) 7559 @cindex @code{mode} variable attribute 7560 This attribute specifies the data type for the declaration---whichever 7561 type corresponds to the mode @var{mode}. This in effect lets you 7562 request an integer or floating-point type according to its width. 7563 7564 @xref{Machine Modes,,, gccint, GNU Compiler Collection (GCC) Internals}, 7565 for a list of the possible keywords for @var{mode}. 7566 You may also specify a mode of @code{byte} or @code{__byte__} to 7567 indicate the mode corresponding to a one-byte integer, @code{word} or 7568 @code{__word__} for the mode of a one-word integer, and @code{pointer} 7569 or @code{__pointer__} for the mode used to represent pointers. 7570 7571 @item nonstring 7572 @cindex @code{nonstring} variable attribute 7573 The @code{nonstring} variable attribute specifies that an object or member 7574 declaration with type array of @code{char}, @code{signed char}, or 7575 @code{unsigned char}, or pointer to such a type is intended to store 7576 character arrays that do not necessarily contain a terminating @code{NUL}. 7577 This is useful in detecting uses of such arrays or pointers with functions 7578 that expect @code{NUL}-terminated strings, and to avoid warnings when such 7579 an array or pointer is used as an argument to a bounded string manipulation 7580 function such as @code{strncpy}. For example, without the attribute, GCC 7581 will issue a warning for the @code{strncpy} call below because it may 7582 truncate the copy without appending the terminating @code{NUL} character. 7583 Using the attribute makes it possible to suppress the warning. However, 7584 when the array is declared with the attribute the call to @code{strlen} is 7585 diagnosed because when the array doesn't contain a @code{NUL}-terminated 7586 string the call is undefined. To copy, compare, of search non-string 7587 character arrays use the @code{memcpy}, @code{memcmp}, @code{memchr}, 7588 and other functions that operate on arrays of bytes. In addition, 7589 calling @code{strnlen} and @code{strndup} with such arrays is safe 7590 provided a suitable bound is specified, and not diagnosed. 7591 7592 @smallexample 7593 struct Data 7594 @{ 7595 char name [32] __attribute__ ((nonstring)); 7596 @}; 7597 7598 int f (struct Data *pd, const char *s) 7599 @{ 7600 strncpy (pd->name, s, sizeof pd->name); 7601 @dots{} 7602 return strlen (pd->name); // unsafe, gets a warning 7603 @} 7604 @end smallexample 7605 7606 @item packed 7607 @cindex @code{packed} variable attribute 7608 The @code{packed} attribute specifies that a structure member should have 7609 the smallest possible alignment---one bit for a bit-field and one byte 7610 otherwise, unless a larger value is specified with the @code{aligned} 7611 attribute. The attribute does not apply to non-member objects. 7612 7613 For example in the structure below, the member array @code{x} is packed 7614 so that it immediately follows @code{a} with no intervening padding: 7615 7616 @smallexample 7617 struct foo 7618 @{ 7619 char a; 7620 int x[2] __attribute__ ((packed)); 7621 @}; 7622 @end smallexample 7623 7624 @emph{Note:} The 4.1, 4.2 and 4.3 series of GCC ignore the 7625 @code{packed} attribute on bit-fields of type @code{char}. This has 7626 been fixed in GCC 4.4 but the change can lead to differences in the 7627 structure layout. See the documentation of 7628 @option{-Wpacked-bitfield-compat} for more information. 7629 7630 @item section ("@var{section-name}") 7631 @cindex @code{section} variable attribute 7632 Normally, the compiler places the objects it generates in sections like 7633 @code{data} and @code{bss}. Sometimes, however, you need additional sections, 7634 or you need certain particular variables to appear in special sections, 7635 for example to map to special hardware. The @code{section} 7636 attribute specifies that a variable (or function) lives in a particular 7637 section. For example, this small program uses several specific section names: 7638 7639 @smallexample 7640 struct duart a __attribute__ ((section ("DUART_A"))) = @{ 0 @}; 7641 struct duart b __attribute__ ((section ("DUART_B"))) = @{ 0 @}; 7642 char stack[10000] __attribute__ ((section ("STACK"))) = @{ 0 @}; 7643 int init_data __attribute__ ((section ("INITDATA"))); 7644 7645 main() 7646 @{ 7647 /* @r{Initialize stack pointer} */ 7648 init_sp (stack + sizeof (stack)); 7649 7650 /* @r{Initialize initialized data} */ 7651 memcpy (&init_data, &data, &edata - &data); 7652 7653 /* @r{Turn on the serial ports} */ 7654 init_duart (&a); 7655 init_duart (&b); 7656 @} 7657 @end smallexample 7658 7659 @noindent 7660 Use the @code{section} attribute with 7661 @emph{global} variables and not @emph{local} variables, 7662 as shown in the example. 7663 7664 You may use the @code{section} attribute with initialized or 7665 uninitialized global variables but the linker requires 7666 each object be defined once, with the exception that uninitialized 7667 variables tentatively go in the @code{common} (or @code{bss}) section 7668 and can be multiply ``defined''. Using the @code{section} attribute 7669 changes what section the variable goes into and may cause the 7670 linker to issue an error if an uninitialized variable has multiple 7671 definitions. You can force a variable to be initialized with the 7672 @option{-fno-common} flag or the @code{nocommon} attribute. 7673 7674 Some file formats do not support arbitrary sections so the @code{section} 7675 attribute is not available on all platforms. 7676 If you need to map the entire contents of a module to a particular 7677 section, consider using the facilities of the linker instead. 7678 7679 @item tls_model ("@var{tls_model}") 7680 @cindex @code{tls_model} variable attribute 7681 The @code{tls_model} attribute sets thread-local storage model 7682 (@pxref{Thread-Local}) of a particular @code{__thread} variable, 7683 overriding @option{-ftls-model=} command-line switch on a per-variable 7684 basis. 7685 The @var{tls_model} argument should be one of @code{global-dynamic}, 7686 @code{local-dynamic}, @code{initial-exec} or @code{local-exec}. 7687 7688 Not all targets support this attribute. 7689 7690 @item unused 7691 @cindex @code{unused} variable attribute 7692 This attribute, attached to a variable or structure field, means that 7693 the variable or field is meant to be possibly unused. GCC does not 7694 produce a warning for this variable or field. 7695 7696 @item used 7697 @cindex @code{used} variable attribute 7698 This attribute, attached to a variable with static storage, means that 7699 the variable must be emitted even if it appears that the variable is not 7700 referenced. 7701 7702 When applied to a static data member of a C++ class template, the 7703 attribute also means that the member is instantiated if the 7704 class itself is instantiated. 7705 7706 @item retain 7707 @cindex @code{retain} variable attribute 7708 For ELF targets that support the GNU or FreeBSD OSABIs, this attribute 7709 will save the variable from linker garbage collection. To support 7710 this behavior, variables that have not been placed in specific sections 7711 (e.g. by the @code{section} attribute, or the @code{-fdata-sections} option), 7712 will be placed in new, unique sections. 7713 7714 This additional functionality requires Binutils version 2.36 or later. 7715 7716 @item uninitialized 7717 @cindex @code{uninitialized} variable attribute 7718 This attribute, attached to a variable with automatic storage, means that 7719 the variable should not be automatically initialized by the compiler when 7720 the option @code{-ftrivial-auto-var-init} presents. 7721 7722 With the option @code{-ftrivial-auto-var-init}, all the automatic variables 7723 that do not have explicit initializers will be initialized by the compiler. 7724 These additional compiler initializations might incur run-time overhead, 7725 sometimes dramatically. This attribute can be used to mark some variables 7726 to be excluded from such automatical initialization in order to reduce runtime 7727 overhead. 7728 7729 This attribute has no effect when the option @code{-ftrivial-auto-var-init} 7730 does not present. 7731 7732 @item vector_size (@var{bytes}) 7733 @cindex @code{vector_size} variable attribute 7734 This attribute specifies the vector size for the type of the declared 7735 variable, measured in bytes. The type to which it applies is known as 7736 the @dfn{base type}. The @var{bytes} argument must be a positive 7737 power-of-two multiple of the base type size. For example, the declaration: 7738 7739 @smallexample 7740 int foo __attribute__ ((vector_size (16))); 7741 @end smallexample 7742 7743 @noindent 7744 causes the compiler to set the mode for @code{foo}, to be 16 bytes, 7745 divided into @code{int} sized units. Assuming a 32-bit @code{int}, 7746 @code{foo}'s type is a vector of four units of four bytes each, and 7747 the corresponding mode of @code{foo} is @code{V4SI}. 7748 @xref{Vector Extensions}, for details of manipulating vector variables. 7749 7750 This attribute is only applicable to integral and floating scalars, 7751 although arrays, pointers, and function return values are allowed in 7752 conjunction with this construct. 7753 7754 Aggregates with this attribute are invalid, even if they are of the same 7755 size as a corresponding scalar. For example, the declaration: 7756 7757 @smallexample 7758 struct S @{ int a; @}; 7759 struct S __attribute__ ((vector_size (16))) foo; 7760 @end smallexample 7761 7762 @noindent 7763 is invalid even if the size of the structure is the same as the size of 7764 the @code{int}. 7765 7766 @item visibility ("@var{visibility_type}") 7767 @cindex @code{visibility} variable attribute 7768 This attribute affects the linkage of the declaration to which it is attached. 7769 The @code{visibility} attribute is described in 7770 @ref{Common Function Attributes}. 7771 7772 @item weak 7773 @cindex @code{weak} variable attribute 7774 The @code{weak} attribute is described in 7775 @ref{Common Function Attributes}. 7776 7777 @item noinit 7778 @cindex @code{noinit} variable attribute 7779 Any data with the @code{noinit} attribute will not be initialized by 7780 the C runtime startup code, or the program loader. Not initializing 7781 data in this way can reduce program startup times. 7782 7783 This attribute is specific to ELF targets and relies on the linker 7784 script to place sections with the @code{.noinit} prefix in the right 7785 location. 7786 7787 @item persistent 7788 @cindex @code{persistent} variable attribute 7789 Any data with the @code{persistent} attribute will not be initialized by 7790 the C runtime startup code, but will be initialized by the program 7791 loader. This enables the value of the variable to @samp{persist} 7792 between processor resets. 7793 7794 This attribute is specific to ELF targets and relies on the linker 7795 script to place the sections with the @code{.persistent} prefix in the 7796 right location. Specifically, some type of non-volatile, writeable 7797 memory is required. 7798 7799 @item objc_nullability (@var{nullability kind}) @r{(Objective-C and Objective-C++ only)} 7800 @cindex @code{objc_nullability} variable attribute 7801 This attribute applies to pointer variables only. It allows marking the 7802 pointer with one of four possible values describing the conditions under 7803 which the pointer might have a @code{nil} value. In most cases, the 7804 attribute is intended to be an internal representation for property and 7805 method nullability (specified by language keywords); it is not recommended 7806 to use it directly. 7807 7808 When @var{nullability kind} is @code{"unspecified"} or @code{0}, nothing is 7809 known about the conditions in which the pointer might be @code{nil}. Making 7810 this state specific serves to avoid false positives in diagnostics. 7811 7812 When @var{nullability kind} is @code{"nonnull"} or @code{1}, the pointer has 7813 no meaning if it is @code{nil} and thus the compiler is free to emit 7814 diagnostics if it can be determined that the value will be @code{nil}. 7815 7816 When @var{nullability kind} is @code{"nullable"} or @code{2}, the pointer might 7817 be @code{nil} and carry meaning as such. 7818 7819 When @var{nullability kind} is @code{"resettable"} or @code{3} (used only in 7820 the context of property attribute lists) this describes the case in which a 7821 property setter may take the value @code{nil} (which perhaps causes the 7822 property to be reset in some manner to a default) but for which the property 7823 getter will never validly return @code{nil}. 7824 7825 @end table 7826 7827 @node ARC Variable Attributes 7828 @subsection ARC Variable Attributes 7829 7830 @table @code 7831 @item aux 7832 @cindex @code{aux} variable attribute, ARC 7833 The @code{aux} attribute is used to directly access the ARC's 7834 auxiliary register space from C. The auxilirary register number is 7835 given via attribute argument. 7836 7837 @end table 7838 7839 @node AVR Variable Attributes 7840 @subsection AVR Variable Attributes 7841 7842 @table @code 7843 @item progmem 7844 @cindex @code{progmem} variable attribute, AVR 7845 The @code{progmem} attribute is used on the AVR to place read-only 7846 data in the non-volatile program memory (flash). The @code{progmem} 7847 attribute accomplishes this by putting respective variables into a 7848 section whose name starts with @code{.progmem}. 7849 7850 This attribute works similar to the @code{section} attribute 7851 but adds additional checking. 7852 7853 @table @asis 7854 @item @bullet{}@tie{} Ordinary AVR cores with 32 general purpose registers: 7855 @code{progmem} affects the location 7856 of the data but not how this data is accessed. 7857 In order to read data located with the @code{progmem} attribute 7858 (inline) assembler must be used. 7859 @smallexample 7860 /* Use custom macros from @w{@uref{http://nongnu.org/avr-libc/user-manual/,AVR-LibC}} */ 7861 #include <avr/pgmspace.h> 7862 7863 /* Locate var in flash memory */ 7864 const int var[2] PROGMEM = @{ 1, 2 @}; 7865 7866 int read_var (int i) 7867 @{ 7868 /* Access var[] by accessor macro from avr/pgmspace.h */ 7869 return (int) pgm_read_word (& var[i]); 7870 @} 7871 @end smallexample 7872 7873 AVR is a Harvard architecture processor and data and read-only data 7874 normally resides in the data memory (RAM). 7875 7876 See also the @ref{AVR Named Address Spaces} section for 7877 an alternate way to locate and access data in flash memory. 7878 7879 @item @bullet{}@tie{} AVR cores with flash memory visible in the RAM address range: 7880 On such devices, there is no need for attribute @code{progmem} or 7881 @ref{AVR Named Address Spaces,,@code{__flash}} qualifier at all. 7882 Just use standard C / C++. The compiler will generate @code{LD*} 7883 instructions. As flash memory is visible in the RAM address range, 7884 and the default linker script does @emph{not} locate @code{.rodata} in 7885 RAM, no special features are needed in order not to waste RAM for 7886 read-only data or to read from flash. You might even get slightly better 7887 performance by 7888 avoiding @code{progmem} and @code{__flash}. This applies to devices from 7889 families @code{avrtiny} and @code{avrxmega3}, see @ref{AVR Options} for 7890 an overview. 7891 7892 @item @bullet{}@tie{}Reduced AVR Tiny cores like ATtiny40: 7893 The compiler adds @code{0x4000} 7894 to the addresses of objects and declarations in @code{progmem} and locates 7895 the objects in flash memory, namely in section @code{.progmem.data}. 7896 The offset is needed because the flash memory is visible in the RAM 7897 address space starting at address @code{0x4000}. 7898 7899 Data in @code{progmem} can be accessed by means of ordinary C@tie{}code, 7900 no special functions or macros are needed. 7901 7902 @smallexample 7903 /* var is located in flash memory */ 7904 extern const int var[2] __attribute__((progmem)); 7905 7906 int read_var (int i) 7907 @{ 7908 return var[i]; 7909 @} 7910 @end smallexample 7911 7912 Please notice that on these devices, there is no need for @code{progmem} 7913 at all. 7914 7915 @end table 7916 7917 @item io 7918 @itemx io (@var{addr}) 7919 @cindex @code{io} variable attribute, AVR 7920 Variables with the @code{io} attribute are used to address 7921 memory-mapped peripherals in the io address range. 7922 If an address is specified, the variable 7923 is assigned that address, and the value is interpreted as an 7924 address in the data address space. 7925 Example: 7926 7927 @smallexample 7928 volatile int porta __attribute__((io (0x22))); 7929 @end smallexample 7930 7931 The address specified in the address in the data address range. 7932 7933 Otherwise, the variable it is not assigned an address, but the 7934 compiler will still use in/out instructions where applicable, 7935 assuming some other module assigns an address in the io address range. 7936 Example: 7937 7938 @smallexample 7939 extern volatile int porta __attribute__((io)); 7940 @end smallexample 7941 7942 @item io_low 7943 @itemx io_low (@var{addr}) 7944 @cindex @code{io_low} variable attribute, AVR 7945 This is like the @code{io} attribute, but additionally it informs the 7946 compiler that the object lies in the lower half of the I/O area, 7947 allowing the use of @code{cbi}, @code{sbi}, @code{sbic} and @code{sbis} 7948 instructions. 7949 7950 @item address 7951 @itemx address (@var{addr}) 7952 @cindex @code{address} variable attribute, AVR 7953 Variables with the @code{address} attribute are used to address 7954 memory-mapped peripherals that may lie outside the io address range. 7955 7956 @smallexample 7957 volatile int porta __attribute__((address (0x600))); 7958 @end smallexample 7959 7960 @item absdata 7961 @cindex @code{absdata} variable attribute, AVR 7962 Variables in static storage and with the @code{absdata} attribute can 7963 be accessed by the @code{LDS} and @code{STS} instructions which take 7964 absolute addresses. 7965 7966 @itemize @bullet 7967 @item 7968 This attribute is only supported for the reduced AVR Tiny core 7969 like ATtiny40. 7970 7971 @item 7972 You must make sure that respective data is located in the 7973 address range @code{0x40}@dots{}@code{0xbf} accessible by 7974 @code{LDS} and @code{STS}. One way to achieve this as an 7975 appropriate linker description file. 7976 7977 @item 7978 If the location does not fit the address range of @code{LDS} 7979 and @code{STS}, there is currently (Binutils 2.26) just an unspecific 7980 warning like 7981 @quotation 7982 @code{module.cc:(.text+0x1c): warning: internal error: out of range error} 7983 @end quotation 7984 7985 @end itemize 7986 7987 See also the @option{-mabsdata} @ref{AVR Options,command-line option}. 7988 7989 @end table 7990 7991 @node Blackfin Variable Attributes 7992 @subsection Blackfin Variable Attributes 7993 7994 Three attributes are currently defined for the Blackfin. 7995 7996 @table @code 7997 @item l1_data 7998 @itemx l1_data_A 7999 @itemx l1_data_B 8000 @cindex @code{l1_data} variable attribute, Blackfin 8001 @cindex @code{l1_data_A} variable attribute, Blackfin 8002 @cindex @code{l1_data_B} variable attribute, Blackfin 8003 Use these attributes on the Blackfin to place the variable into L1 Data SRAM. 8004 Variables with @code{l1_data} attribute are put into the specific section 8005 named @code{.l1.data}. Those with @code{l1_data_A} attribute are put into 8006 the specific section named @code{.l1.data.A}. Those with @code{l1_data_B} 8007 attribute are put into the specific section named @code{.l1.data.B}. 8008 8009 @item l2 8010 @cindex @code{l2} variable attribute, Blackfin 8011 Use this attribute on the Blackfin to place the variable into L2 SRAM. 8012 Variables with @code{l2} attribute are put into the specific section 8013 named @code{.l2.data}. 8014 @end table 8015 8016 @node H8/300 Variable Attributes 8017 @subsection H8/300 Variable Attributes 8018 8019 These variable attributes are available for H8/300 targets: 8020 8021 @table @code 8022 @item eightbit_data 8023 @cindex @code{eightbit_data} variable attribute, H8/300 8024 @cindex eight-bit data on the H8/300, H8/300H, and H8S 8025 Use this attribute on the H8/300, H8/300H, and H8S to indicate that the specified 8026 variable should be placed into the eight-bit data section. 8027 The compiler generates more efficient code for certain operations 8028 on data in the eight-bit data area. Note the eight-bit data area is limited to 8029 256 bytes of data. 8030 8031 You must use GAS and GLD from GNU binutils version 2.7 or later for 8032 this attribute to work correctly. 8033 8034 @item tiny_data 8035 @cindex @code{tiny_data} variable attribute, H8/300 8036 @cindex tiny data section on the H8/300H and H8S 8037 Use this attribute on the H8/300H and H8S to indicate that the specified 8038 variable should be placed into the tiny data section. 8039 The compiler generates more efficient code for loads and stores 8040 on data in the tiny data section. Note the tiny data area is limited to 8041 slightly under 32KB of data. 8042 8043 @end table 8044 8045 @node IA-64 Variable Attributes 8046 @subsection IA-64 Variable Attributes 8047 8048 The IA-64 back end supports the following variable attribute: 8049 8050 @table @code 8051 @item model (@var{model-name}) 8052 @cindex @code{model} variable attribute, IA-64 8053 8054 On IA-64, use this attribute to set the addressability of an object. 8055 At present, the only supported identifier for @var{model-name} is 8056 @code{small}, indicating addressability via ``small'' (22-bit) 8057 addresses (so that their addresses can be loaded with the @code{addl} 8058 instruction). Caveat: such addressing is by definition not position 8059 independent and hence this attribute must not be used for objects 8060 defined by shared libraries. 8061 8062 @end table 8063 8064 @node M32R/D Variable Attributes 8065 @subsection M32R/D Variable Attributes 8066 8067 One attribute is currently defined for the M32R/D@. 8068 8069 @table @code 8070 @item model (@var{model-name}) 8071 @cindex @code{model-name} variable attribute, M32R/D 8072 @cindex variable addressability on the M32R/D 8073 Use this attribute on the M32R/D to set the addressability of an object. 8074 The identifier @var{model-name} is one of @code{small}, @code{medium}, 8075 or @code{large}, representing each of the code models. 8076 8077 Small model objects live in the lower 16MB of memory (so that their 8078 addresses can be loaded with the @code{ld24} instruction). 8079 8080 Medium and large model objects may live anywhere in the 32-bit address space 8081 (the compiler generates @code{seth/add3} instructions to load their 8082 addresses). 8083 @end table 8084 8085 @node MeP Variable Attributes 8086 @subsection MeP Variable Attributes 8087 8088 The MeP target has a number of addressing modes and busses. The 8089 @code{near} space spans the standard memory space's first 16 megabytes 8090 (24 bits). The @code{far} space spans the entire 32-bit memory space. 8091 The @code{based} space is a 128-byte region in the memory space that 8092 is addressed relative to the @code{$tp} register. The @code{tiny} 8093 space is a 65536-byte region relative to the @code{$gp} register. In 8094 addition to these memory regions, the MeP target has a separate 16-bit 8095 control bus which is specified with @code{cb} attributes. 8096 8097 @table @code 8098 8099 @item based 8100 @cindex @code{based} variable attribute, MeP 8101 Any variable with the @code{based} attribute is assigned to the 8102 @code{.based} section, and is accessed with relative to the 8103 @code{$tp} register. 8104 8105 @item tiny 8106 @cindex @code{tiny} variable attribute, MeP 8107 Likewise, the @code{tiny} attribute assigned variables to the 8108 @code{.tiny} section, relative to the @code{$gp} register. 8109 8110 @item near 8111 @cindex @code{near} variable attribute, MeP 8112 Variables with the @code{near} attribute are assumed to have addresses 8113 that fit in a 24-bit addressing mode. This is the default for large 8114 variables (@code{-mtiny=4} is the default) but this attribute can 8115 override @code{-mtiny=} for small variables, or override @code{-ml}. 8116 8117 @item far 8118 @cindex @code{far} variable attribute, MeP 8119 Variables with the @code{far} attribute are addressed using a full 8120 32-bit address. Since this covers the entire memory space, this 8121 allows modules to make no assumptions about where variables might be 8122 stored. 8123 8124 @item io 8125 @cindex @code{io} variable attribute, MeP 8126 @itemx io (@var{addr}) 8127 Variables with the @code{io} attribute are used to address 8128 memory-mapped peripherals. If an address is specified, the variable 8129 is assigned that address, else it is not assigned an address (it is 8130 assumed some other module assigns an address). Example: 8131 8132 @smallexample 8133 int timer_count __attribute__((io(0x123))); 8134 @end smallexample 8135 8136 @item cb 8137 @itemx cb (@var{addr}) 8138 @cindex @code{cb} variable attribute, MeP 8139 Variables with the @code{cb} attribute are used to access the control 8140 bus, using special instructions. @code{addr} indicates the control bus 8141 address. Example: 8142 8143 @smallexample 8144 int cpu_clock __attribute__((cb(0x123))); 8145 @end smallexample 8146 8147 @end table 8148 8149 @node Microsoft Windows Variable Attributes 8150 @subsection Microsoft Windows Variable Attributes 8151 8152 You can use these attributes on Microsoft Windows targets. 8153 @ref{x86 Variable Attributes} for additional Windows compatibility 8154 attributes available on all x86 targets. 8155 8156 @table @code 8157 @item dllimport 8158 @itemx dllexport 8159 @cindex @code{dllimport} variable attribute 8160 @cindex @code{dllexport} variable attribute 8161 The @code{dllimport} and @code{dllexport} attributes are described in 8162 @ref{Microsoft Windows Function Attributes}. 8163 8164 @item selectany 8165 @cindex @code{selectany} variable attribute 8166 The @code{selectany} attribute causes an initialized global variable to 8167 have link-once semantics. When multiple definitions of the variable are 8168 encountered by the linker, the first is selected and the remainder are 8169 discarded. Following usage by the Microsoft compiler, the linker is told 8170 @emph{not} to warn about size or content differences of the multiple 8171 definitions. 8172 8173 Although the primary usage of this attribute is for POD types, the 8174 attribute can also be applied to global C++ objects that are initialized 8175 by a constructor. In this case, the static initialization and destruction 8176 code for the object is emitted in each translation defining the object, 8177 but the calls to the constructor and destructor are protected by a 8178 link-once guard variable. 8179 8180 The @code{selectany} attribute is only available on Microsoft Windows 8181 targets. You can use @code{__declspec (selectany)} as a synonym for 8182 @code{__attribute__ ((selectany))} for compatibility with other 8183 compilers. 8184 8185 @item shared 8186 @cindex @code{shared} variable attribute 8187 On Microsoft Windows, in addition to putting variable definitions in a named 8188 section, the section can also be shared among all running copies of an 8189 executable or DLL@. For example, this small program defines shared data 8190 by putting it in a named section @code{shared} and marking the section 8191 shareable: 8192 8193 @smallexample 8194 int foo __attribute__((section ("shared"), shared)) = 0; 8195 8196 int 8197 main() 8198 @{ 8199 /* @r{Read and write foo. All running 8200 copies see the same value.} */ 8201 return 0; 8202 @} 8203 @end smallexample 8204 8205 @noindent 8206 You may only use the @code{shared} attribute along with @code{section} 8207 attribute with a fully-initialized global definition because of the way 8208 linkers work. See @code{section} attribute for more information. 8209 8210 The @code{shared} attribute is only available on Microsoft Windows@. 8211 8212 @end table 8213 8214 @node MSP430 Variable Attributes 8215 @subsection MSP430 Variable Attributes 8216 8217 @table @code 8218 @item upper 8219 @itemx either 8220 @cindex @code{upper} variable attribute, MSP430 8221 @cindex @code{either} variable attribute, MSP430 8222 These attributes are the same as the MSP430 function attributes of the 8223 same name (@pxref{MSP430 Function Attributes}). 8224 8225 @item lower 8226 @cindex @code{lower} variable attribute, MSP430 8227 This option behaves mostly the same as the MSP430 function attribute of the 8228 same name (@pxref{MSP430 Function Attributes}), but it has some additional 8229 functionality. 8230 8231 If @option{-mdata-region=}@{@code{upper,either,none}@} has been passed, or 8232 the @code{section} attribute is applied to a variable, the compiler will 8233 generate 430X instructions to handle it. This is because the compiler has 8234 to assume that the variable could get placed in the upper memory region 8235 (above address 0xFFFF). Marking the variable with the @code{lower} attribute 8236 informs the compiler that the variable will be placed in lower memory so it 8237 is safe to use 430 instructions to handle it. 8238 8239 In the case of the @code{section} attribute, the section name given 8240 will be used, and the @code{.lower} prefix will not be added. 8241 8242 @end table 8243 8244 @node Nvidia PTX Variable Attributes 8245 @subsection Nvidia PTX Variable Attributes 8246 8247 These variable attributes are supported by the Nvidia PTX back end: 8248 8249 @table @code 8250 @item shared 8251 @cindex @code{shared} attribute, Nvidia PTX 8252 Use this attribute to place a variable in the @code{.shared} memory space. 8253 This memory space is private to each cooperative thread array; only threads 8254 within one thread block refer to the same instance of the variable. 8255 The runtime does not initialize variables in this memory space. 8256 @end table 8257 8258 @node PowerPC Variable Attributes 8259 @subsection PowerPC Variable Attributes 8260 8261 Three attributes currently are defined for PowerPC configurations: 8262 @code{altivec}, @code{ms_struct} and @code{gcc_struct}. 8263 8264 @cindex @code{ms_struct} variable attribute, PowerPC 8265 @cindex @code{gcc_struct} variable attribute, PowerPC 8266 For full documentation of the struct attributes please see the 8267 documentation in @ref{x86 Variable Attributes}. 8268 8269 @cindex @code{altivec} variable attribute, PowerPC 8270 For documentation of @code{altivec} attribute please see the 8271 documentation in @ref{PowerPC Type Attributes}. 8272 8273 @node RL78 Variable Attributes 8274 @subsection RL78 Variable Attributes 8275 8276 @cindex @code{saddr} variable attribute, RL78 8277 The RL78 back end supports the @code{saddr} variable attribute. This 8278 specifies placement of the corresponding variable in the SADDR area, 8279 which can be accessed more efficiently than the default memory region. 8280 8281 @node V850 Variable Attributes 8282 @subsection V850 Variable Attributes 8283 8284 These variable attributes are supported by the V850 back end: 8285 8286 @table @code 8287 8288 @item sda 8289 @cindex @code{sda} variable attribute, V850 8290 Use this attribute to explicitly place a variable in the small data area, 8291 which can hold up to 64 kilobytes. 8292 8293 @item tda 8294 @cindex @code{tda} variable attribute, V850 8295 Use this attribute to explicitly place a variable in the tiny data area, 8296 which can hold up to 256 bytes in total. 8297 8298 @item zda 8299 @cindex @code{zda} variable attribute, V850 8300 Use this attribute to explicitly place a variable in the first 32 kilobytes 8301 of memory. 8302 @end table 8303 8304 @node x86 Variable Attributes 8305 @subsection x86 Variable Attributes 8306 8307 Two attributes are currently defined for x86 configurations: 8308 @code{ms_struct} and @code{gcc_struct}. 8309 8310 @table @code 8311 @item ms_struct 8312 @itemx gcc_struct 8313 @cindex @code{ms_struct} variable attribute, x86 8314 @cindex @code{gcc_struct} variable attribute, x86 8315 8316 If @code{packed} is used on a structure, or if bit-fields are used, 8317 it may be that the Microsoft ABI lays out the structure differently 8318 than the way GCC normally does. Particularly when moving packed 8319 data between functions compiled with GCC and the native Microsoft compiler 8320 (either via function call or as data in a file), it may be necessary to access 8321 either format. 8322 8323 The @code{ms_struct} and @code{gcc_struct} attributes correspond 8324 to the @option{-mms-bitfields} and @option{-mno-ms-bitfields} 8325 command-line options, respectively; 8326 see @ref{x86 Options}, for details of how structure layout is affected. 8327 @xref{x86 Type Attributes}, for information about the corresponding 8328 attributes on types. 8329 8330 @end table 8331 8332 @node Xstormy16 Variable Attributes 8333 @subsection Xstormy16 Variable Attributes 8334 8335 One attribute is currently defined for xstormy16 configurations: 8336 @code{below100}. 8337 8338 @table @code 8339 @item below100 8340 @cindex @code{below100} variable attribute, Xstormy16 8341 8342 If a variable has the @code{below100} attribute (@code{BELOW100} is 8343 allowed also), GCC places the variable in the first 0x100 bytes of 8344 memory and use special opcodes to access it. Such variables are 8345 placed in either the @code{.bss_below100} section or the 8346 @code{.data_below100} section. 8347 8348 @end table 8349 8350 @node Type Attributes 8351 @section Specifying Attributes of Types 8352 @cindex attribute of types 8353 @cindex type attributes 8354 8355 The keyword @code{__attribute__} allows you to specify various special 8356 properties of types. Some type attributes apply only to structure and 8357 union types, and in C++, also class types, while others can apply to 8358 any type defined via a @code{typedef} declaration. Unless otherwise 8359 specified, the same restrictions and effects apply to attributes regardless 8360 of whether a type is a trivial structure or a C++ class with user-defined 8361 constructors, destructors, or a copy assignment. 8362 8363 Other attributes are defined for functions (@pxref{Function Attributes}), 8364 labels (@pxref{Label Attributes}), enumerators (@pxref{Enumerator 8365 Attributes}), statements (@pxref{Statement Attributes}), and for variables 8366 (@pxref{Variable Attributes}). 8367 8368 The @code{__attribute__} keyword is followed by an attribute specification 8369 enclosed in double parentheses. 8370 8371 You may specify type attributes in an enum, struct or union type 8372 declaration or definition by placing them immediately after the 8373 @code{struct}, @code{union} or @code{enum} keyword. You can also place 8374 them just past the closing curly brace of the definition, but this is less 8375 preferred because logically the type should be fully defined at 8376 the closing brace. 8377 8378 You can also include type attributes in a @code{typedef} declaration. 8379 @xref{Attribute Syntax}, for details of the exact syntax for using 8380 attributes. 8381 8382 @menu 8383 * Common Type Attributes:: 8384 * ARC Type Attributes:: 8385 * ARM Type Attributes:: 8386 * BPF Type Attributes:: 8387 * MeP Type Attributes:: 8388 * PowerPC Type Attributes:: 8389 * x86 Type Attributes:: 8390 @end menu 8391 8392 @node Common Type Attributes 8393 @subsection Common Type Attributes 8394 8395 The following type attributes are supported on most targets. 8396 8397 @table @code 8398 @cindex @code{aligned} type attribute 8399 @item aligned 8400 @itemx aligned (@var{alignment}) 8401 The @code{aligned} attribute specifies a minimum alignment (in bytes) for 8402 variables of the specified type. When specified, @var{alignment} must be 8403 a power of 2. Specifying no @var{alignment} argument implies the maximum 8404 alignment for the target, which is often, but by no means always, 8 or 16 8405 bytes. For example, the declarations: 8406 8407 @smallexample 8408 struct __attribute__ ((aligned (8))) S @{ short f[3]; @}; 8409 typedef int more_aligned_int __attribute__ ((aligned (8))); 8410 @end smallexample 8411 8412 @noindent 8413 force the compiler to ensure (as far as it can) that each variable whose 8414 type is @code{struct S} or @code{more_aligned_int} is allocated and 8415 aligned @emph{at least} on a 8-byte boundary. On a SPARC, having all 8416 variables of type @code{struct S} aligned to 8-byte boundaries allows 8417 the compiler to use the @code{ldd} and @code{std} (doubleword load and 8418 store) instructions when copying one variable of type @code{struct S} to 8419 another, thus improving run-time efficiency. 8420 8421 Note that the alignment of any given @code{struct} or @code{union} type 8422 is required by the ISO C standard to be at least a perfect multiple of 8423 the lowest common multiple of the alignments of all of the members of 8424 the @code{struct} or @code{union} in question. This means that you @emph{can} 8425 effectively adjust the alignment of a @code{struct} or @code{union} 8426 type by attaching an @code{aligned} attribute to any one of the members 8427 of such a type, but the notation illustrated in the example above is a 8428 more obvious, intuitive, and readable way to request the compiler to 8429 adjust the alignment of an entire @code{struct} or @code{union} type. 8430 8431 As in the preceding example, you can explicitly specify the alignment 8432 (in bytes) that you wish the compiler to use for a given @code{struct} 8433 or @code{union} type. Alternatively, you can leave out the alignment factor 8434 and just ask the compiler to align a type to the maximum 8435 useful alignment for the target machine you are compiling for. For 8436 example, you could write: 8437 8438 @smallexample 8439 struct __attribute__ ((aligned)) S @{ short f[3]; @}; 8440 @end smallexample 8441 8442 Whenever you leave out the alignment factor in an @code{aligned} 8443 attribute specification, the compiler automatically sets the alignment 8444 for the type to the largest alignment that is ever used for any data 8445 type on the target machine you are compiling for. Doing this can often 8446 make copy operations more efficient, because the compiler can use 8447 whatever instructions copy the biggest chunks of memory when performing 8448 copies to or from the variables that have types that you have aligned 8449 this way. 8450 8451 In the example above, if the size of each @code{short} is 2 bytes, then 8452 the size of the entire @code{struct S} type is 6 bytes. The smallest 8453 power of two that is greater than or equal to that is 8, so the 8454 compiler sets the alignment for the entire @code{struct S} type to 8 8455 bytes. 8456 8457 Note that although you can ask the compiler to select a time-efficient 8458 alignment for a given type and then declare only individual stand-alone 8459 objects of that type, the compiler's ability to select a time-efficient 8460 alignment is primarily useful only when you plan to create arrays of 8461 variables having the relevant (efficiently aligned) type. If you 8462 declare or use arrays of variables of an efficiently-aligned type, then 8463 it is likely that your program also does pointer arithmetic (or 8464 subscripting, which amounts to the same thing) on pointers to the 8465 relevant type, and the code that the compiler generates for these 8466 pointer arithmetic operations is often more efficient for 8467 efficiently-aligned types than for other types. 8468 8469 Note that the effectiveness of @code{aligned} attributes may be limited 8470 by inherent limitations in your linker. On many systems, the linker is 8471 only able to arrange for variables to be aligned up to a certain maximum 8472 alignment. (For some linkers, the maximum supported alignment may 8473 be very very small.) If your linker is only able to align variables 8474 up to a maximum of 8-byte alignment, then specifying @code{aligned (16)} 8475 in an @code{__attribute__} still only provides you with 8-byte 8476 alignment. See your linker documentation for further information. 8477 8478 When used on a struct, or struct member, the @code{aligned} attribute can 8479 only increase the alignment; in order to decrease it, the @code{packed} 8480 attribute must be specified as well. When used as part of a typedef, the 8481 @code{aligned} attribute can both increase and decrease alignment, and 8482 specifying the @code{packed} attribute generates a warning. 8483 8484 @cindex @code{warn_if_not_aligned} type attribute 8485 @item warn_if_not_aligned (@var{alignment}) 8486 This attribute specifies a threshold for the structure field, measured 8487 in bytes. If the structure field is aligned below the threshold, a 8488 warning will be issued. For example, the declaration: 8489 8490 @smallexample 8491 typedef unsigned long long __u64 8492 __attribute__((aligned (4), warn_if_not_aligned (8))); 8493 8494 struct foo 8495 @{ 8496 int i1; 8497 int i2; 8498 __u64 x; 8499 @}; 8500 @end smallexample 8501 8502 @noindent 8503 causes the compiler to issue an warning on @code{struct foo}, like 8504 @samp{warning: alignment 4 of 'struct foo' is less than 8}. 8505 It is used to define @code{struct foo} in such a way that 8506 @code{struct foo} has the same layout and the structure field @code{x} 8507 has the same alignment when @code{__u64} is aligned at either 4 or 8508 8 bytes. Align @code{struct foo} to 8 bytes: 8509 8510 @smallexample 8511 struct __attribute__ ((aligned (8))) foo 8512 @{ 8513 int i1; 8514 int i2; 8515 __u64 x; 8516 @}; 8517 @end smallexample 8518 8519 @noindent 8520 silences the warning. The compiler also issues a warning, like 8521 @samp{warning: 'x' offset 12 in 'struct foo' isn't aligned to 8}, 8522 when the structure field has the misaligned offset: 8523 8524 @smallexample 8525 struct __attribute__ ((aligned (8))) foo 8526 @{ 8527 int i1; 8528 int i2; 8529 int i3; 8530 __u64 x; 8531 @}; 8532 @end smallexample 8533 8534 This warning can be disabled by @option{-Wno-if-not-aligned}. 8535 8536 @item alloc_size (@var{position}) 8537 @itemx alloc_size (@var{position-1}, @var{position-2}) 8538 @cindex @code{alloc_size} type attribute 8539 The @code{alloc_size} type attribute may be applied to the definition 8540 of a type of a function that returns a pointer and takes at least one 8541 argument of an integer type. It indicates that the returned pointer 8542 points to an object whose size is given by the function argument at 8543 @var{position-1}, or by the product of the arguments at @var{position-1} 8544 and @var{position-2}. Meaningful sizes are positive values less than 8545 @code{PTRDIFF_MAX}. Other sizes are disagnosed when detected. GCC uses 8546 this information to improve the results of @code{__builtin_object_size}. 8547 8548 For instance, the following declarations 8549 8550 @smallexample 8551 typedef __attribute__ ((alloc_size (1, 2))) void* 8552 calloc_type (size_t, size_t); 8553 typedef __attribute__ ((alloc_size (1))) void* 8554 malloc_type (size_t); 8555 @end smallexample 8556 8557 @noindent 8558 specify that @code{calloc_type} is a type of a function that, like 8559 the standard C function @code{calloc}, returns an object whose size 8560 is given by the product of arguments 1 and 2, and that 8561 @code{malloc_type}, like the standard C function @code{malloc}, 8562 returns an object whose size is given by argument 1 to the function. 8563 8564 @item copy 8565 @itemx copy (@var{expression}) 8566 @cindex @code{copy} type attribute 8567 The @code{copy} attribute applies the set of attributes with which 8568 the type of the @var{expression} has been declared to the declaration 8569 of the type to which the attribute is applied. The attribute is 8570 designed for libraries that define aliases that are expected to 8571 specify the same set of attributes as the aliased symbols. 8572 The @code{copy} attribute can be used with types, variables, or 8573 functions. However, the kind of symbol to which the attribute is 8574 applied (either varible or function) must match the kind of symbol 8575 to which the argument refers. 8576 The @code{copy} attribute copies only syntactic and semantic attributes 8577 but not attributes that affect a symbol's linkage or visibility such as 8578 @code{alias}, @code{visibility}, or @code{weak}. The @code{deprecated} 8579 attribute is also not copied. @xref{Common Function Attributes}. 8580 @xref{Common Variable Attributes}. 8581 8582 For example, suppose @code{struct A} below is defined in some third 8583 party library header to have the alignment requirement @code{N} and 8584 to force a warning whenever a variable of the type is not so aligned 8585 due to attribute @code{packed}. Specifying the @code{copy} attribute 8586 on the definition on the unrelated @code{struct B} has the effect of 8587 copying all relevant attributes from the type referenced by the pointer 8588 expression to @code{struct B}. 8589 8590 @smallexample 8591 struct __attribute__ ((aligned (N), warn_if_not_aligned (N))) 8592 A @{ /* @r{@dots{}} */ @}; 8593 struct __attribute__ ((copy ( (struct A *)0)) B @{ /* @r{@dots{}} */ @}; 8594 @end smallexample 8595 8596 @item deprecated 8597 @itemx deprecated (@var{msg}) 8598 @cindex @code{deprecated} type attribute 8599 The @code{deprecated} attribute results in a warning if the type 8600 is used anywhere in the source file. This is useful when identifying 8601 types that are expected to be removed in a future version of a program. 8602 If possible, the warning also includes the location of the declaration 8603 of the deprecated type, to enable users to easily find further 8604 information about why the type is deprecated, or what they should do 8605 instead. Note that the warnings only occur for uses and then only 8606 if the type is being applied to an identifier that itself is not being 8607 declared as deprecated. 8608 8609 @smallexample 8610 typedef int T1 __attribute__ ((deprecated)); 8611 T1 x; 8612 typedef T1 T2; 8613 T2 y; 8614 typedef T1 T3 __attribute__ ((deprecated)); 8615 T3 z __attribute__ ((deprecated)); 8616 @end smallexample 8617 8618 @noindent 8619 results in a warning on line 2 and 3 but not lines 4, 5, or 6. No 8620 warning is issued for line 4 because T2 is not explicitly 8621 deprecated. Line 5 has no warning because T3 is explicitly 8622 deprecated. Similarly for line 6. The optional @var{msg} 8623 argument, which must be a string, is printed in the warning if 8624 present. Control characters in the string will be replaced with 8625 escape sequences, and if the @option{-fmessage-length} option is set 8626 to 0 (its default value) then any newline characters will be ignored. 8627 8628 The @code{deprecated} attribute can also be used for functions and 8629 variables (@pxref{Function Attributes}, @pxref{Variable Attributes}.) 8630 8631 The message attached to the attribute is affected by the setting of 8632 the @option{-fmessage-length} option. 8633 8634 @item unavailable 8635 @itemx unavailable (@var{msg}) 8636 @cindex @code{unavailable} type attribute 8637 The @code{unavailable} attribute behaves in the same manner as the 8638 @code{deprecated} one, but emits an error rather than a warning. It is 8639 used to indicate that a (perhaps previously @code{deprecated}) type is 8640 no longer usable. 8641 8642 The @code{unavailable} attribute can also be used for functions and 8643 variables (@pxref{Function Attributes}, @pxref{Variable Attributes}.) 8644 8645 @item designated_init 8646 @cindex @code{designated_init} type attribute 8647 This attribute may only be applied to structure types. It indicates 8648 that any initialization of an object of this type must use designated 8649 initializers rather than positional initializers. The intent of this 8650 attribute is to allow the programmer to indicate that a structure's 8651 layout may change, and that therefore relying on positional 8652 initialization will result in future breakage. 8653 8654 GCC emits warnings based on this attribute by default; use 8655 @option{-Wno-designated-init} to suppress them. 8656 8657 @item may_alias 8658 @cindex @code{may_alias} type attribute 8659 Accesses through pointers to types with this attribute are not subject 8660 to type-based alias analysis, but are instead assumed to be able to alias 8661 any other type of objects. 8662 In the context of section 6.5 paragraph 7 of the C99 standard, 8663 an lvalue expression 8664 dereferencing such a pointer is treated like having a character type. 8665 See @option{-fstrict-aliasing} for more information on aliasing issues. 8666 This extension exists to support some vector APIs, in which pointers to 8667 one vector type are permitted to alias pointers to a different vector type. 8668 8669 Note that an object of a type with this attribute does not have any 8670 special semantics. 8671 8672 Example of use: 8673 8674 @smallexample 8675 typedef short __attribute__ ((__may_alias__)) short_a; 8676 8677 int 8678 main (void) 8679 @{ 8680 int a = 0x12345678; 8681 short_a *b = (short_a *) &a; 8682 8683 b[1] = 0; 8684 8685 if (a == 0x12345678) 8686 abort(); 8687 8688 exit(0); 8689 @} 8690 @end smallexample 8691 8692 @noindent 8693 If you replaced @code{short_a} with @code{short} in the variable 8694 declaration, the above program would abort when compiled with 8695 @option{-fstrict-aliasing}, which is on by default at @option{-O2} or 8696 above. 8697 8698 @item mode (@var{mode}) 8699 @cindex @code{mode} type attribute 8700 This attribute specifies the data type for the declaration---whichever 8701 type corresponds to the mode @var{mode}. This in effect lets you 8702 request an integer or floating-point type according to its width. 8703 8704 @xref{Machine Modes,,, gccint, GNU Compiler Collection (GCC) Internals}, 8705 for a list of the possible keywords for @var{mode}. 8706 You may also specify a mode of @code{byte} or @code{__byte__} to 8707 indicate the mode corresponding to a one-byte integer, @code{word} or 8708 @code{__word__} for the mode of a one-word integer, and @code{pointer} 8709 or @code{__pointer__} for the mode used to represent pointers. 8710 8711 @item packed 8712 @cindex @code{packed} type attribute 8713 This attribute, attached to a @code{struct}, @code{union}, or C++ @code{class} 8714 type definition, specifies that each of its members (other than zero-width 8715 bit-fields) is placed to minimize the memory required. This is equivalent 8716 to specifying the @code{packed} attribute on each of the members. 8717 8718 @opindex fshort-enums 8719 When attached to an @code{enum} definition, the @code{packed} attribute 8720 indicates that the smallest integral type should be used. 8721 Specifying the @option{-fshort-enums} flag on the command line 8722 is equivalent to specifying the @code{packed} 8723 attribute on all @code{enum} definitions. 8724 8725 In the following example @code{struct my_packed_struct}'s members are 8726 packed closely together, but the internal layout of its @code{s} member 8727 is not packed---to do that, @code{struct my_unpacked_struct} needs to 8728 be packed too. 8729 8730 @smallexample 8731 struct my_unpacked_struct 8732 @{ 8733 char c; 8734 int i; 8735 @}; 8736 8737 struct __attribute__ ((__packed__)) my_packed_struct 8738 @{ 8739 char c; 8740 int i; 8741 struct my_unpacked_struct s; 8742 @}; 8743 @end smallexample 8744 8745 You may only specify the @code{packed} attribute on the definition 8746 of an @code{enum}, @code{struct}, @code{union}, or @code{class}, 8747 not on a @code{typedef} that does not also define the enumerated type, 8748 structure, union, or class. 8749 8750 @item scalar_storage_order ("@var{endianness}") 8751 @cindex @code{scalar_storage_order} type attribute 8752 When attached to a @code{union} or a @code{struct}, this attribute sets 8753 the storage order, aka endianness, of the scalar fields of the type, as 8754 well as the array fields whose component is scalar. The supported 8755 endiannesses are @code{big-endian} and @code{little-endian}. The attribute 8756 has no effects on fields which are themselves a @code{union}, a @code{struct} 8757 or an array whose component is a @code{union} or a @code{struct}, and it is 8758 possible for these fields to have a different scalar storage order than the 8759 enclosing type. 8760 8761 Note that neither pointer nor vector fields are considered scalar fields in 8762 this context, so the attribute has no effects on these fields. 8763 8764 This attribute is supported only for targets that use a uniform default 8765 scalar storage order (fortunately, most of them), i.e.@: targets that store 8766 the scalars either all in big-endian or all in little-endian. 8767 8768 Additional restrictions are enforced for types with the reverse scalar 8769 storage order with regard to the scalar storage order of the target: 8770 8771 @itemize 8772 @item Taking the address of a scalar field of a @code{union} or a 8773 @code{struct} with reverse scalar storage order is not permitted and yields 8774 an error. 8775 @item Taking the address of an array field, whose component is scalar, of 8776 a @code{union} or a @code{struct} with reverse scalar storage order is 8777 permitted but yields a warning, unless @option{-Wno-scalar-storage-order} 8778 is specified. 8779 @item Taking the address of a @code{union} or a @code{struct} with reverse 8780 scalar storage order is permitted. 8781 @end itemize 8782 8783 These restrictions exist because the storage order attribute is lost when 8784 the address of a scalar or the address of an array with scalar component is 8785 taken, so storing indirectly through this address generally does not work. 8786 The second case is nevertheless allowed to be able to perform a block copy 8787 from or to the array. 8788 8789 Moreover, the use of type punning or aliasing to toggle the storage order 8790 is not supported; that is to say, if a given scalar object can be accessed 8791 through distinct types that assign a different storage order to it, then the 8792 behavior is undefined. 8793 8794 @item transparent_union 8795 @cindex @code{transparent_union} type attribute 8796 8797 This attribute, attached to a @code{union} type definition, indicates 8798 that any function parameter having that union type causes calls to that 8799 function to be treated in a special way. 8800 8801 First, the argument corresponding to a transparent union type can be of 8802 any type in the union; no cast is required. Also, if the union contains 8803 a pointer type, the corresponding argument can be a null pointer 8804 constant or a void pointer expression; and if the union contains a void 8805 pointer type, the corresponding argument can be any pointer expression. 8806 If the union member type is a pointer, qualifiers like @code{const} on 8807 the referenced type must be respected, just as with normal pointer 8808 conversions. 8809 8810 Second, the argument is passed to the function using the calling 8811 conventions of the first member of the transparent union, not the calling 8812 conventions of the union itself. All members of the union must have the 8813 same machine representation; this is necessary for this argument passing 8814 to work properly. 8815 8816 Transparent unions are designed for library functions that have multiple 8817 interfaces for compatibility reasons. For example, suppose the 8818 @code{wait} function must accept either a value of type @code{int *} to 8819 comply with POSIX, or a value of type @code{union wait *} to comply with 8820 the 4.1BSD interface. If @code{wait}'s parameter were @code{void *}, 8821 @code{wait} would accept both kinds of arguments, but it would also 8822 accept any other pointer type and this would make argument type checking 8823 less useful. Instead, @code{<sys/wait.h>} might define the interface 8824 as follows: 8825 8826 @smallexample 8827 typedef union __attribute__ ((__transparent_union__)) 8828 @{ 8829 int *__ip; 8830 union wait *__up; 8831 @} wait_status_ptr_t; 8832 8833 pid_t wait (wait_status_ptr_t); 8834 @end smallexample 8835 8836 @noindent 8837 This interface allows either @code{int *} or @code{union wait *} 8838 arguments to be passed, using the @code{int *} calling convention. 8839 The program can call @code{wait} with arguments of either type: 8840 8841 @smallexample 8842 int w1 () @{ int w; return wait (&w); @} 8843 int w2 () @{ union wait w; return wait (&w); @} 8844 @end smallexample 8845 8846 @noindent 8847 With this interface, @code{wait}'s implementation might look like this: 8848 8849 @smallexample 8850 pid_t wait (wait_status_ptr_t p) 8851 @{ 8852 return waitpid (-1, p.__ip, 0); 8853 @} 8854 @end smallexample 8855 8856 @item unused 8857 @cindex @code{unused} type attribute 8858 When attached to a type (including a @code{union} or a @code{struct}), 8859 this attribute means that variables of that type are meant to appear 8860 possibly unused. GCC does not produce a warning for any variables of 8861 that type, even if the variable appears to do nothing. This is often 8862 the case with lock or thread classes, which are usually defined and then 8863 not referenced, but contain constructors and destructors that have 8864 nontrivial bookkeeping functions. 8865 8866 @item vector_size (@var{bytes}) 8867 @cindex @code{vector_size} type attribute 8868 This attribute specifies the vector size for the type, measured in bytes. 8869 The type to which it applies is known as the @dfn{base type}. The @var{bytes} 8870 argument must be a positive power-of-two multiple of the base type size. For 8871 example, the following declarations: 8872 8873 @smallexample 8874 typedef __attribute__ ((vector_size (32))) int int_vec32_t ; 8875 typedef __attribute__ ((vector_size (32))) int* int_vec32_ptr_t; 8876 typedef __attribute__ ((vector_size (32))) int int_vec32_arr3_t[3]; 8877 @end smallexample 8878 8879 @noindent 8880 define @code{int_vec32_t} to be a 32-byte vector type composed of @code{int} 8881 sized units. With @code{int} having a size of 4 bytes, the type defines 8882 a vector of eight units, four bytes each. The mode of variables of type 8883 @code{int_vec32_t} is @code{V8SI}. @code{int_vec32_ptr_t} is then defined 8884 to be a pointer to such a vector type, and @code{int_vec32_arr3_t} to be 8885 an array of three such vectors. @xref{Vector Extensions}, for details of 8886 manipulating objects of vector types. 8887 8888 This attribute is only applicable to integral and floating scalar types. 8889 In function declarations the attribute applies to the function return 8890 type. 8891 8892 For example, the following: 8893 @smallexample 8894 __attribute__ ((vector_size (16))) float get_flt_vec16 (void); 8895 @end smallexample 8896 declares @code{get_flt_vec16} to be a function returning a 16-byte vector 8897 with the base type @code{float}. 8898 8899 @item visibility 8900 @cindex @code{visibility} type attribute 8901 In C++, attribute visibility (@pxref{Function Attributes}) can also be 8902 applied to class, struct, union and enum types. Unlike other type 8903 attributes, the attribute must appear between the initial keyword and 8904 the name of the type; it cannot appear after the body of the type. 8905 8906 Note that the type visibility is applied to vague linkage entities 8907 associated with the class (vtable, typeinfo node, etc.). In 8908 particular, if a class is thrown as an exception in one shared object 8909 and caught in another, the class must have default visibility. 8910 Otherwise the two shared objects are unable to use the same 8911 typeinfo node and exception handling will break. 8912 8913 @item objc_root_class @r{(Objective-C and Objective-C++ only)} 8914 @cindex @code{objc_root_class} type attribute 8915 This attribute marks a class as being a root class, and thus allows 8916 the compiler to elide any warnings about a missing superclass and to 8917 make additional checks for mandatory methods as needed. 8918 8919 @end table 8920 8921 To specify multiple attributes, separate them by commas within the 8922 double parentheses: for example, @samp{__attribute__ ((aligned (16), 8923 packed))}. 8924 8925 @node ARC Type Attributes 8926 @subsection ARC Type Attributes 8927 8928 @cindex @code{uncached} type attribute, ARC 8929 Declaring objects with @code{uncached} allows you to exclude 8930 data-cache participation in load and store operations on those objects 8931 without involving the additional semantic implications of 8932 @code{volatile}. The @code{.di} instruction suffix is used for all 8933 loads and stores of data declared @code{uncached}. 8934 8935 @node ARM Type Attributes 8936 @subsection ARM Type Attributes 8937 8938 @cindex @code{notshared} type attribute, ARM 8939 On those ARM targets that support @code{dllimport} (such as Symbian 8940 OS), you can use the @code{notshared} attribute to indicate that the 8941 virtual table and other similar data for a class should not be 8942 exported from a DLL@. For example: 8943 8944 @smallexample 8945 class __declspec(notshared) C @{ 8946 public: 8947 __declspec(dllimport) C(); 8948 virtual void f(); 8949 @} 8950 8951 __declspec(dllexport) 8952 C::C() @{@} 8953 @end smallexample 8954 8955 @noindent 8956 In this code, @code{C::C} is exported from the current DLL, but the 8957 virtual table for @code{C} is not exported. (You can use 8958 @code{__attribute__} instead of @code{__declspec} if you prefer, but 8959 most Symbian OS code uses @code{__declspec}.) 8960 8961 @node BPF Type Attributes 8962 @subsection BPF Type Attributes 8963 8964 @cindex @code{preserve_access_index} type attribute, BPF 8965 BPF Compile Once - Run Everywhere (CO-RE) support. When attached to a 8966 @code{struct} or @code{union} type definition, indicates that CO-RE 8967 relocation information should be generated for any access to a variable 8968 of that type. The behavior is equivalent to the programmer manually 8969 wrapping every such access with @code{__builtin_preserve_access_index}. 8970 8971 8972 @node MeP Type Attributes 8973 @subsection MeP Type Attributes 8974 8975 @cindex @code{based} type attribute, MeP 8976 @cindex @code{tiny} type attribute, MeP 8977 @cindex @code{near} type attribute, MeP 8978 @cindex @code{far} type attribute, MeP 8979 Many of the MeP variable attributes may be applied to types as well. 8980 Specifically, the @code{based}, @code{tiny}, @code{near}, and 8981 @code{far} attributes may be applied to either. The @code{io} and 8982 @code{cb} attributes may not be applied to types. 8983 8984 @node PowerPC Type Attributes 8985 @subsection PowerPC Type Attributes 8986 8987 Three attributes currently are defined for PowerPC configurations: 8988 @code{altivec}, @code{ms_struct} and @code{gcc_struct}. 8989 8990 @cindex @code{ms_struct} type attribute, PowerPC 8991 @cindex @code{gcc_struct} type attribute, PowerPC 8992 For full documentation of the @code{ms_struct} and @code{gcc_struct} 8993 attributes please see the documentation in @ref{x86 Type Attributes}. 8994 8995 @cindex @code{altivec} type attribute, PowerPC 8996 The @code{altivec} attribute allows one to declare AltiVec vector data 8997 types supported by the AltiVec Programming Interface Manual. The 8998 attribute requires an argument to specify one of three vector types: 8999 @code{vector__}, @code{pixel__} (always followed by unsigned short), 9000 and @code{bool__} (always followed by unsigned). 9001 9002 @smallexample 9003 __attribute__((altivec(vector__))) 9004 __attribute__((altivec(pixel__))) unsigned short 9005 __attribute__((altivec(bool__))) unsigned 9006 @end smallexample 9007 9008 These attributes mainly are intended to support the @code{__vector}, 9009 @code{__pixel}, and @code{__bool} AltiVec keywords. 9010 9011 @node x86 Type Attributes 9012 @subsection x86 Type Attributes 9013 9014 Two attributes are currently defined for x86 configurations: 9015 @code{ms_struct} and @code{gcc_struct}. 9016 9017 @table @code 9018 9019 @item ms_struct 9020 @itemx gcc_struct 9021 @cindex @code{ms_struct} type attribute, x86 9022 @cindex @code{gcc_struct} type attribute, x86 9023 9024 If @code{packed} is used on a structure, or if bit-fields are used 9025 it may be that the Microsoft ABI packs them differently 9026 than GCC normally packs them. Particularly when moving packed 9027 data between functions compiled with GCC and the native Microsoft compiler 9028 (either via function call or as data in a file), it may be necessary to access 9029 either format. 9030 9031 The @code{ms_struct} and @code{gcc_struct} attributes correspond 9032 to the @option{-mms-bitfields} and @option{-mno-ms-bitfields} 9033 command-line options, respectively; 9034 see @ref{x86 Options}, for details of how structure layout is affected. 9035 @xref{x86 Variable Attributes}, for information about the corresponding 9036 attributes on variables. 9037 9038 @end table 9039 9040 @node Label Attributes 9041 @section Label Attributes 9042 @cindex Label Attributes 9043 9044 GCC allows attributes to be set on C labels. @xref{Attribute Syntax}, for 9045 details of the exact syntax for using attributes. Other attributes are 9046 available for functions (@pxref{Function Attributes}), variables 9047 (@pxref{Variable Attributes}), enumerators (@pxref{Enumerator Attributes}), 9048 statements (@pxref{Statement Attributes}), and for types 9049 (@pxref{Type Attributes}). A label attribute followed 9050 by a declaration appertains to the label and not the declaration. 9051 9052 This example uses the @code{cold} label attribute to indicate the 9053 @code{ErrorHandling} branch is unlikely to be taken and that the 9054 @code{ErrorHandling} label is unused: 9055 9056 @smallexample 9057 9058 asm goto ("some asm" : : : : NoError); 9059 9060 /* This branch (the fall-through from the asm) is less commonly used */ 9061 ErrorHandling: 9062 __attribute__((cold, unused)); /* Semi-colon is required here */ 9063 printf("error\n"); 9064 return 0; 9065 9066 NoError: 9067 printf("no error\n"); 9068 return 1; 9069 @end smallexample 9070 9071 @table @code 9072 @item unused 9073 @cindex @code{unused} label attribute 9074 This feature is intended for program-generated code that may contain 9075 unused labels, but which is compiled with @option{-Wall}. It is 9076 not normally appropriate to use in it human-written code, though it 9077 could be useful in cases where the code that jumps to the label is 9078 contained within an @code{#ifdef} conditional. 9079 9080 @item hot 9081 @cindex @code{hot} label attribute 9082 The @code{hot} attribute on a label is used to inform the compiler that 9083 the path following the label is more likely than paths that are not so 9084 annotated. This attribute is used in cases where @code{__builtin_expect} 9085 cannot be used, for instance with computed goto or @code{asm goto}. 9086 9087 @item cold 9088 @cindex @code{cold} label attribute 9089 The @code{cold} attribute on labels is used to inform the compiler that 9090 the path following the label is unlikely to be executed. This attribute 9091 is used in cases where @code{__builtin_expect} cannot be used, for instance 9092 with computed goto or @code{asm goto}. 9093 9094 @end table 9095 9096 @node Enumerator Attributes 9097 @section Enumerator Attributes 9098 @cindex Enumerator Attributes 9099 9100 GCC allows attributes to be set on enumerators. @xref{Attribute Syntax}, for 9101 details of the exact syntax for using attributes. Other attributes are 9102 available for functions (@pxref{Function Attributes}), variables 9103 (@pxref{Variable Attributes}), labels (@pxref{Label Attributes}), statements 9104 (@pxref{Statement Attributes}), and for types (@pxref{Type Attributes}). 9105 9106 This example uses the @code{deprecated} enumerator attribute to indicate the 9107 @code{oldval} enumerator is deprecated: 9108 9109 @smallexample 9110 enum E @{ 9111 oldval __attribute__((deprecated)), 9112 newval 9113 @}; 9114 9115 int 9116 fn (void) 9117 @{ 9118 return oldval; 9119 @} 9120 @end smallexample 9121 9122 @table @code 9123 @item deprecated 9124 @cindex @code{deprecated} enumerator attribute 9125 The @code{deprecated} attribute results in a warning if the enumerator 9126 is used anywhere in the source file. This is useful when identifying 9127 enumerators that are expected to be removed in a future version of a 9128 program. The warning also includes the location of the declaration 9129 of the deprecated enumerator, to enable users to easily find further 9130 information about why the enumerator is deprecated, or what they should 9131 do instead. Note that the warnings only occurs for uses. 9132 9133 @item unavailable 9134 @cindex @code{unavailable} enumerator attribute 9135 The @code{unavailable} attribute results in an error if the enumerator 9136 is used anywhere in the source file. In other respects it behaves in the 9137 same manner as the @code{deprecated} attribute. 9138 9139 @end table 9140 9141 @node Statement Attributes 9142 @section Statement Attributes 9143 @cindex Statement Attributes 9144 9145 GCC allows attributes to be set on null statements. @xref{Attribute Syntax}, 9146 for details of the exact syntax for using attributes. Other attributes are 9147 available for functions (@pxref{Function Attributes}), variables 9148 (@pxref{Variable Attributes}), labels (@pxref{Label Attributes}), enumerators 9149 (@pxref{Enumerator Attributes}), and for types (@pxref{Type Attributes}). 9150 9151 This example uses the @code{fallthrough} statement attribute to indicate that 9152 the @option{-Wimplicit-fallthrough} warning should not be emitted: 9153 9154 @smallexample 9155 switch (cond) 9156 @{ 9157 case 1: 9158 bar (1); 9159 __attribute__((fallthrough)); 9160 case 2: 9161 @dots{} 9162 @} 9163 @end smallexample 9164 9165 @table @code 9166 @item fallthrough 9167 @cindex @code{fallthrough} statement attribute 9168 The @code{fallthrough} attribute with a null statement serves as a 9169 fallthrough statement. It hints to the compiler that a statement 9170 that falls through to another case label, or user-defined label 9171 in a switch statement is intentional and thus the 9172 @option{-Wimplicit-fallthrough} warning must not trigger. The 9173 fallthrough attribute may appear at most once in each attribute 9174 list, and may not be mixed with other attributes. It can only 9175 be used in a switch statement (the compiler will issue an error 9176 otherwise), after a preceding statement and before a logically 9177 succeeding case label, or user-defined label. 9178 9179 @end table 9180 9181 @node Attribute Syntax 9182 @section Attribute Syntax 9183 @cindex attribute syntax 9184 9185 This section describes the syntax with which @code{__attribute__} may be 9186 used, and the constructs to which attribute specifiers bind, for the C 9187 language. Some details may vary for C++ and Objective-C@. Because of 9188 infelicities in the grammar for attributes, some forms described here 9189 may not be successfully parsed in all cases. 9190 9191 There are some problems with the semantics of attributes in C++. For 9192 example, there are no manglings for attributes, although they may affect 9193 code generation, so problems may arise when attributed types are used in 9194 conjunction with templates or overloading. Similarly, @code{typeid} 9195 does not distinguish between types with different attributes. Support 9196 for attributes in C++ may be restricted in future to attributes on 9197 declarations only, but not on nested declarators. 9198 9199 @xref{Function Attributes}, for details of the semantics of attributes 9200 applying to functions. @xref{Variable Attributes}, for details of the 9201 semantics of attributes applying to variables. @xref{Type Attributes}, 9202 for details of the semantics of attributes applying to structure, union 9203 and enumerated types. 9204 @xref{Label Attributes}, for details of the semantics of attributes 9205 applying to labels. 9206 @xref{Enumerator Attributes}, for details of the semantics of attributes 9207 applying to enumerators. 9208 @xref{Statement Attributes}, for details of the semantics of attributes 9209 applying to statements. 9210 9211 An @dfn{attribute specifier} is of the form 9212 @code{__attribute__ ((@var{attribute-list}))}. An @dfn{attribute list} 9213 is a possibly empty comma-separated sequence of @dfn{attributes}, where 9214 each attribute is one of the following: 9215 9216 @itemize @bullet 9217 @item 9218 Empty. Empty attributes are ignored. 9219 9220 @item 9221 An attribute name 9222 (which may be an identifier such as @code{unused}, or a reserved 9223 word such as @code{const}). 9224 9225 @item 9226 An attribute name followed by a parenthesized list of 9227 parameters for the attribute. 9228 These parameters take one of the following forms: 9229 9230 @itemize @bullet 9231 @item 9232 An identifier. For example, @code{mode} attributes use this form. 9233 9234 @item 9235 An identifier followed by a comma and a non-empty comma-separated list 9236 of expressions. For example, @code{format} attributes use this form. 9237 9238 @item 9239 A possibly empty comma-separated list of expressions. For example, 9240 @code{format_arg} attributes use this form with the list being a single 9241 integer constant expression, and @code{alias} attributes use this form 9242 with the list being a single string constant. 9243 @end itemize 9244 @end itemize 9245 9246 An @dfn{attribute specifier list} is a sequence of one or more attribute 9247 specifiers, not separated by any other tokens. 9248 9249 You may optionally specify attribute names with @samp{__} 9250 preceding and following the name. 9251 This allows you to use them in header files without 9252 being concerned about a possible macro of the same name. For example, 9253 you may use the attribute name @code{__noreturn__} instead of @code{noreturn}. 9254 9255 9256 @subsubheading Label Attributes 9257 9258 In GNU C, an attribute specifier list may appear after the colon following a 9259 label, other than a @code{case} or @code{default} label. GNU C++ only permits 9260 attributes on labels if the attribute specifier is immediately 9261 followed by a semicolon (i.e., the label applies to an empty 9262 statement). If the semicolon is missing, C++ label attributes are 9263 ambiguous, as it is permissible for a declaration, which could begin 9264 with an attribute list, to be labelled in C++. Declarations cannot be 9265 labelled in C90 or C99, so the ambiguity does not arise there. 9266 9267 @subsubheading Enumerator Attributes 9268 9269 In GNU C, an attribute specifier list may appear as part of an enumerator. 9270 The attribute goes after the enumeration constant, before @code{=}, if 9271 present. The optional attribute in the enumerator appertains to the 9272 enumeration constant. It is not possible to place the attribute after 9273 the constant expression, if present. 9274 9275 @subsubheading Statement Attributes 9276 In GNU C, an attribute specifier list may appear as part of a null 9277 statement. The attribute goes before the semicolon. 9278 9279 @subsubheading Type Attributes 9280 9281 An attribute specifier list may appear as part of a @code{struct}, 9282 @code{union} or @code{enum} specifier. It may go either immediately 9283 after the @code{struct}, @code{union} or @code{enum} keyword, or after 9284 the closing brace. The former syntax is preferred. 9285 Where attribute specifiers follow the closing brace, they are considered 9286 to relate to the structure, union or enumerated type defined, not to any 9287 enclosing declaration the type specifier appears in, and the type 9288 defined is not complete until after the attribute specifiers. 9289 @c Otherwise, there would be the following problems: a shift/reduce 9290 @c conflict between attributes binding the struct/union/enum and 9291 @c binding to the list of specifiers/qualifiers; and "aligned" 9292 @c attributes could use sizeof for the structure, but the size could be 9293 @c changed later by "packed" attributes. 9294 9295 9296 @subsubheading All other attributes 9297 9298 Otherwise, an attribute specifier appears as part of a declaration, 9299 counting declarations of unnamed parameters and type names, and relates 9300 to that declaration (which may be nested in another declaration, for 9301 example in the case of a parameter declaration), or to a particular declarator 9302 within a declaration. Where an 9303 attribute specifier is applied to a parameter declared as a function or 9304 an array, it should apply to the function or array rather than the 9305 pointer to which the parameter is implicitly converted, but this is not 9306 yet correctly implemented. 9307 9308 Any list of specifiers and qualifiers at the start of a declaration may 9309 contain attribute specifiers, whether or not such a list may in that 9310 context contain storage class specifiers. (Some attributes, however, 9311 are essentially in the nature of storage class specifiers, and only make 9312 sense where storage class specifiers may be used; for example, 9313 @code{section}.) There is one necessary limitation to this syntax: the 9314 first old-style parameter declaration in a function definition cannot 9315 begin with an attribute specifier, because such an attribute applies to 9316 the function instead by syntax described below (which, however, is not 9317 yet implemented in this case). In some other cases, attribute 9318 specifiers are permitted by this grammar but not yet supported by the 9319 compiler. All attribute specifiers in this place relate to the 9320 declaration as a whole. In the obsolescent usage where a type of 9321 @code{int} is implied by the absence of type specifiers, such a list of 9322 specifiers and qualifiers may be an attribute specifier list with no 9323 other specifiers or qualifiers. 9324 9325 At present, the first parameter in a function prototype must have some 9326 type specifier that is not an attribute specifier; this resolves an 9327 ambiguity in the interpretation of @code{void f(int 9328 (__attribute__((foo)) x))}, but is subject to change. At present, if 9329 the parentheses of a function declarator contain only attributes then 9330 those attributes are ignored, rather than yielding an error or warning 9331 or implying a single parameter of type int, but this is subject to 9332 change. 9333 9334 An attribute specifier list may appear immediately before a declarator 9335 (other than the first) in a comma-separated list of declarators in a 9336 declaration of more than one identifier using a single list of 9337 specifiers and qualifiers. Such attribute specifiers apply 9338 only to the identifier before whose declarator they appear. For 9339 example, in 9340 9341 @smallexample 9342 __attribute__((noreturn)) void d0 (void), 9343 __attribute__((format(printf, 1, 2))) d1 (const char *, ...), 9344 d2 (void); 9345 @end smallexample 9346 9347 @noindent 9348 the @code{noreturn} attribute applies to all the functions 9349 declared; the @code{format} attribute only applies to @code{d1}. 9350 9351 An attribute specifier list may appear immediately before the comma, 9352 @code{=} or semicolon terminating the declaration of an identifier other 9353 than a function definition. Such attribute specifiers apply 9354 to the declared object or function. Where an 9355 assembler name for an object or function is specified (@pxref{Asm 9356 Labels}), the attribute must follow the @code{asm} 9357 specification. 9358 9359 An attribute specifier list may, in future, be permitted to appear after 9360 the declarator in a function definition (before any old-style parameter 9361 declarations or the function body). 9362 9363 Attribute specifiers may be mixed with type qualifiers appearing inside 9364 the @code{[]} of a parameter array declarator, in the C99 construct by 9365 which such qualifiers are applied to the pointer to which the array is 9366 implicitly converted. Such attribute specifiers apply to the pointer, 9367 not to the array, but at present this is not implemented and they are 9368 ignored. 9369 9370 An attribute specifier list may appear at the start of a nested 9371 declarator. At present, there are some limitations in this usage: the 9372 attributes correctly apply to the declarator, but for most individual 9373 attributes the semantics this implies are not implemented. 9374 When attribute specifiers follow the @code{*} of a pointer 9375 declarator, they may be mixed with any type qualifiers present. 9376 The following describes the formal semantics of this syntax. It makes the 9377 most sense if you are familiar with the formal specification of 9378 declarators in the ISO C standard. 9379 9380 Consider (as in C99 subclause 6.7.5 paragraph 4) a declaration @code{T 9381 D1}, where @code{T} contains declaration specifiers that specify a type 9382 @var{Type} (such as @code{int}) and @code{D1} is a declarator that 9383 contains an identifier @var{ident}. The type specified for @var{ident} 9384 for derived declarators whose type does not include an attribute 9385 specifier is as in the ISO C standard. 9386 9387 If @code{D1} has the form @code{( @var{attribute-specifier-list} D )}, 9388 and the declaration @code{T D} specifies the type 9389 ``@var{derived-declarator-type-list} @var{Type}'' for @var{ident}, then 9390 @code{T D1} specifies the type ``@var{derived-declarator-type-list} 9391 @var{attribute-specifier-list} @var{Type}'' for @var{ident}. 9392 9393 If @code{D1} has the form @code{* 9394 @var{type-qualifier-and-attribute-specifier-list} D}, and the 9395 declaration @code{T D} specifies the type 9396 ``@var{derived-declarator-type-list} @var{Type}'' for @var{ident}, then 9397 @code{T D1} specifies the type ``@var{derived-declarator-type-list} 9398 @var{type-qualifier-and-attribute-specifier-list} pointer to @var{Type}'' for 9399 @var{ident}. 9400 9401 For example, 9402 9403 @smallexample 9404 void (__attribute__((noreturn)) ****f) (void); 9405 @end smallexample 9406 9407 @noindent 9408 specifies the type ``pointer to pointer to pointer to pointer to 9409 non-returning function returning @code{void}''. As another example, 9410 9411 @smallexample 9412 char *__attribute__((aligned(8))) *f; 9413 @end smallexample 9414 9415 @noindent 9416 specifies the type ``pointer to 8-byte-aligned pointer to @code{char}''. 9417 Note again that this does not work with most attributes; for example, 9418 the usage of @samp{aligned} and @samp{noreturn} attributes given above 9419 is not yet supported. 9420 9421 For compatibility with existing code written for compiler versions that 9422 did not implement attributes on nested declarators, some laxity is 9423 allowed in the placing of attributes. If an attribute that only applies 9424 to types is applied to a declaration, it is treated as applying to 9425 the type of that declaration. If an attribute that only applies to 9426 declarations is applied to the type of a declaration, it is treated 9427 as applying to that declaration; and, for compatibility with code 9428 placing the attributes immediately before the identifier declared, such 9429 an attribute applied to a function return type is treated as 9430 applying to the function type, and such an attribute applied to an array 9431 element type is treated as applying to the array type. If an 9432 attribute that only applies to function types is applied to a 9433 pointer-to-function type, it is treated as applying to the pointer 9434 target type; if such an attribute is applied to a function return type 9435 that is not a pointer-to-function type, it is treated as applying 9436 to the function type. 9437 9438 @node Function Prototypes 9439 @section Prototypes and Old-Style Function Definitions 9440 @cindex function prototype declarations 9441 @cindex old-style function definitions 9442 @cindex promotion of formal parameters 9443 9444 GNU C extends ISO C to allow a function prototype to override a later 9445 old-style non-prototype definition. Consider the following example: 9446 9447 @smallexample 9448 /* @r{Use prototypes unless the compiler is old-fashioned.} */ 9449 #ifdef __STDC__ 9450 #define P(x) x 9451 #else 9452 #define P(x) () 9453 #endif 9454 9455 /* @r{Prototype function declaration.} */ 9456 int isroot P((uid_t)); 9457 9458 /* @r{Old-style function definition.} */ 9459 int 9460 isroot (x) /* @r{??? lossage here ???} */ 9461 uid_t x; 9462 @{ 9463 return x == 0; 9464 @} 9465 @end smallexample 9466 9467 Suppose the type @code{uid_t} happens to be @code{short}. ISO C does 9468 not allow this example, because subword arguments in old-style 9469 non-prototype definitions are promoted. Therefore in this example the 9470 function definition's argument is really an @code{int}, which does not 9471 match the prototype argument type of @code{short}. 9472 9473 This restriction of ISO C makes it hard to write code that is portable 9474 to traditional C compilers, because the programmer does not know 9475 whether the @code{uid_t} type is @code{short}, @code{int}, or 9476 @code{long}. Therefore, in cases like these GNU C allows a prototype 9477 to override a later old-style definition. More precisely, in GNU C, a 9478 function prototype argument type overrides the argument type specified 9479 by a later old-style definition if the former type is the same as the 9480 latter type before promotion. Thus in GNU C the above example is 9481 equivalent to the following: 9482 9483 @smallexample 9484 int isroot (uid_t); 9485 9486 int 9487 isroot (uid_t x) 9488 @{ 9489 return x == 0; 9490 @} 9491 @end smallexample 9492 9493 @noindent 9494 GNU C++ does not support old-style function definitions, so this 9495 extension is irrelevant. 9496 9497 @node C++ Comments 9498 @section C++ Style Comments 9499 @cindex @code{//} 9500 @cindex C++ comments 9501 @cindex comments, C++ style 9502 9503 In GNU C, you may use C++ style comments, which start with @samp{//} and 9504 continue until the end of the line. Many other C implementations allow 9505 such comments, and they are included in the 1999 C standard. However, 9506 C++ style comments are not recognized if you specify an @option{-std} 9507 option specifying a version of ISO C before C99, or @option{-ansi} 9508 (equivalent to @option{-std=c90}). 9509 9510 @node Dollar Signs 9511 @section Dollar Signs in Identifier Names 9512 @cindex $ 9513 @cindex dollar signs in identifier names 9514 @cindex identifier names, dollar signs in 9515 9516 In GNU C, you may normally use dollar signs in identifier names. 9517 This is because many traditional C implementations allow such identifiers. 9518 However, dollar signs in identifiers are not supported on a few target 9519 machines, typically because the target assembler does not allow them. 9520 9521 @node Character Escapes 9522 @section The Character @key{ESC} in Constants 9523 9524 You can use the sequence @samp{\e} in a string or character constant to 9525 stand for the ASCII character @key{ESC}. 9526 9527 @node Alignment 9528 @section Determining the Alignment of Functions, Types or Variables 9529 @cindex alignment 9530 @cindex type alignment 9531 @cindex variable alignment 9532 9533 The keyword @code{__alignof__} determines the alignment requirement of 9534 a function, object, or a type, or the minimum alignment usually required 9535 by a type. Its syntax is just like @code{sizeof} and C11 @code{_Alignof}. 9536 9537 For example, if the target machine requires a @code{double} value to be 9538 aligned on an 8-byte boundary, then @code{__alignof__ (double)} is 8. 9539 This is true on many RISC machines. On more traditional machine 9540 designs, @code{__alignof__ (double)} is 4 or even 2. 9541 9542 Some machines never actually require alignment; they allow references to any 9543 data type even at an odd address. For these machines, @code{__alignof__} 9544 reports the smallest alignment that GCC gives the data type, usually as 9545 mandated by the target ABI. 9546 9547 If the operand of @code{__alignof__} is an lvalue rather than a type, 9548 its value is the required alignment for its type, taking into account 9549 any minimum alignment specified by attribute @code{aligned} 9550 (@pxref{Common Variable Attributes}). For example, after this 9551 declaration: 9552 9553 @smallexample 9554 struct foo @{ int x; char y; @} foo1; 9555 @end smallexample 9556 9557 @noindent 9558 the value of @code{__alignof__ (foo1.y)} is 1, even though its actual 9559 alignment is probably 2 or 4, the same as @code{__alignof__ (int)}. 9560 It is an error to ask for the alignment of an incomplete type other 9561 than @code{void}. 9562 9563 If the operand of the @code{__alignof__} expression is a function, 9564 the expression evaluates to the alignment of the function which may 9565 be specified by attribute @code{aligned} (@pxref{Common Function Attributes}). 9566 9567 @node Inline 9568 @section An Inline Function is As Fast As a Macro 9569 @cindex inline functions 9570 @cindex integrating function code 9571 @cindex open coding 9572 @cindex macros, inline alternative 9573 9574 By declaring a function inline, you can direct GCC to make 9575 calls to that function faster. One way GCC can achieve this is to 9576 integrate that function's code into the code for its callers. This 9577 makes execution faster by eliminating the function-call overhead; in 9578 addition, if any of the actual argument values are constant, their 9579 known values may permit simplifications at compile time so that not 9580 all of the inline function's code needs to be included. The effect on 9581 code size is less predictable; object code may be larger or smaller 9582 with function inlining, depending on the particular case. You can 9583 also direct GCC to try to integrate all ``simple enough'' functions 9584 into their callers with the option @option{-finline-functions}. 9585 9586 GCC implements three different semantics of declaring a function 9587 inline. One is available with @option{-std=gnu89} or 9588 @option{-fgnu89-inline} or when @code{gnu_inline} attribute is present 9589 on all inline declarations, another when 9590 @option{-std=c99}, 9591 @option{-std=gnu99} or an option for a later C version is used 9592 (without @option{-fgnu89-inline}), and the third 9593 is used when compiling C++. 9594 9595 To declare a function inline, use the @code{inline} keyword in its 9596 declaration, like this: 9597 9598 @smallexample 9599 static inline int 9600 inc (int *a) 9601 @{ 9602 return (*a)++; 9603 @} 9604 @end smallexample 9605 9606 If you are writing a header file to be included in ISO C90 programs, write 9607 @code{__inline__} instead of @code{inline}. @xref{Alternate Keywords}. 9608 9609 The three types of inlining behave similarly in two important cases: 9610 when the @code{inline} keyword is used on a @code{static} function, 9611 like the example above, and when a function is first declared without 9612 using the @code{inline} keyword and then is defined with 9613 @code{inline}, like this: 9614 9615 @smallexample 9616 extern int inc (int *a); 9617 inline int 9618 inc (int *a) 9619 @{ 9620 return (*a)++; 9621 @} 9622 @end smallexample 9623 9624 In both of these common cases, the program behaves the same as if you 9625 had not used the @code{inline} keyword, except for its speed. 9626 9627 @cindex inline functions, omission of 9628 @opindex fkeep-inline-functions 9629 When a function is both inline and @code{static}, if all calls to the 9630 function are integrated into the caller, and the function's address is 9631 never used, then the function's own assembler code is never referenced. 9632 In this case, GCC does not actually output assembler code for the 9633 function, unless you specify the option @option{-fkeep-inline-functions}. 9634 If there is a nonintegrated call, then the function is compiled to 9635 assembler code as usual. The function must also be compiled as usual if 9636 the program refers to its address, because that cannot be inlined. 9637 9638 @opindex Winline 9639 Note that certain usages in a function definition can make it unsuitable 9640 for inline substitution. Among these usages are: variadic functions, 9641 use of @code{alloca}, use of computed goto (@pxref{Labels as Values}), 9642 use of nonlocal goto, use of nested functions, use of @code{setjmp}, use 9643 of @code{__builtin_longjmp} and use of @code{__builtin_return} or 9644 @code{__builtin_apply_args}. Using @option{-Winline} warns when a 9645 function marked @code{inline} could not be substituted, and gives the 9646 reason for the failure. 9647 9648 @cindex automatic @code{inline} for C++ member fns 9649 @cindex @code{inline} automatic for C++ member fns 9650 @cindex member fns, automatically @code{inline} 9651 @cindex C++ member fns, automatically @code{inline} 9652 @opindex fno-default-inline 9653 As required by ISO C++, GCC considers member functions defined within 9654 the body of a class to be marked inline even if they are 9655 not explicitly declared with the @code{inline} keyword. You can 9656 override this with @option{-fno-default-inline}; @pxref{C++ Dialect 9657 Options,,Options Controlling C++ Dialect}. 9658 9659 GCC does not inline any functions when not optimizing unless you specify 9660 the @samp{always_inline} attribute for the function, like this: 9661 9662 @smallexample 9663 /* @r{Prototype.} */ 9664 inline void foo (const char) __attribute__((always_inline)); 9665 @end smallexample 9666 9667 The remainder of this section is specific to GNU C90 inlining. 9668 9669 @cindex non-static inline function 9670 When an inline function is not @code{static}, then the compiler must assume 9671 that there may be calls from other source files; since a global symbol can 9672 be defined only once in any program, the function must not be defined in 9673 the other source files, so the calls therein cannot be integrated. 9674 Therefore, a non-@code{static} inline function is always compiled on its 9675 own in the usual fashion. 9676 9677 If you specify both @code{inline} and @code{extern} in the function 9678 definition, then the definition is used only for inlining. In no case 9679 is the function compiled on its own, not even if you refer to its 9680 address explicitly. Such an address becomes an external reference, as 9681 if you had only declared the function, and had not defined it. 9682 9683 This combination of @code{inline} and @code{extern} has almost the 9684 effect of a macro. The way to use it is to put a function definition in 9685 a header file with these keywords, and put another copy of the 9686 definition (lacking @code{inline} and @code{extern}) in a library file. 9687 The definition in the header file causes most calls to the function 9688 to be inlined. If any uses of the function remain, they refer to 9689 the single copy in the library. 9690 9691 @node Volatiles 9692 @section When is a Volatile Object Accessed? 9693 @cindex accessing volatiles 9694 @cindex volatile read 9695 @cindex volatile write 9696 @cindex volatile access 9697 9698 C has the concept of volatile objects. These are normally accessed by 9699 pointers and used for accessing hardware or inter-thread 9700 communication. The standard encourages compilers to refrain from 9701 optimizations concerning accesses to volatile objects, but leaves it 9702 implementation defined as to what constitutes a volatile access. The 9703 minimum requirement is that at a sequence point all previous accesses 9704 to volatile objects have stabilized and no subsequent accesses have 9705 occurred. Thus an implementation is free to reorder and combine 9706 volatile accesses that occur between sequence points, but cannot do 9707 so for accesses across a sequence point. The use of volatile does 9708 not allow you to violate the restriction on updating objects multiple 9709 times between two sequence points. 9710 9711 Accesses to non-volatile objects are not ordered with respect to 9712 volatile accesses. You cannot use a volatile object as a memory 9713 barrier to order a sequence of writes to non-volatile memory. For 9714 instance: 9715 9716 @smallexample 9717 int *ptr = @var{something}; 9718 volatile int vobj; 9719 *ptr = @var{something}; 9720 vobj = 1; 9721 @end smallexample 9722 9723 @noindent 9724 Unless @var{*ptr} and @var{vobj} can be aliased, it is not guaranteed 9725 that the write to @var{*ptr} occurs by the time the update 9726 of @var{vobj} happens. If you need this guarantee, you must use 9727 a stronger memory barrier such as: 9728 9729 @smallexample 9730 int *ptr = @var{something}; 9731 volatile int vobj; 9732 *ptr = @var{something}; 9733 asm volatile ("" : : : "memory"); 9734 vobj = 1; 9735 @end smallexample 9736 9737 A scalar volatile object is read when it is accessed in a void context: 9738 9739 @smallexample 9740 volatile int *src = @var{somevalue}; 9741 *src; 9742 @end smallexample 9743 9744 Such expressions are rvalues, and GCC implements this as a 9745 read of the volatile object being pointed to. 9746 9747 Assignments are also expressions and have an rvalue. However when 9748 assigning to a scalar volatile, the volatile object is not reread, 9749 regardless of whether the assignment expression's rvalue is used or 9750 not. If the assignment's rvalue is used, the value is that assigned 9751 to the volatile object. For instance, there is no read of @var{vobj} 9752 in all the following cases: 9753 9754 @smallexample 9755 int obj; 9756 volatile int vobj; 9757 vobj = @var{something}; 9758 obj = vobj = @var{something}; 9759 obj ? vobj = @var{onething} : vobj = @var{anotherthing}; 9760 obj = (@var{something}, vobj = @var{anotherthing}); 9761 @end smallexample 9762 9763 If you need to read the volatile object after an assignment has 9764 occurred, you must use a separate expression with an intervening 9765 sequence point. 9766 9767 As bit-fields are not individually addressable, volatile bit-fields may 9768 be implicitly read when written to, or when adjacent bit-fields are 9769 accessed. Bit-field operations may be optimized such that adjacent 9770 bit-fields are only partially accessed, if they straddle a storage unit 9771 boundary. For these reasons it is unwise to use volatile bit-fields to 9772 access hardware. 9773 9774 @node Using Assembly Language with C 9775 @section How to Use Inline Assembly Language in C Code 9776 @cindex @code{asm} keyword 9777 @cindex assembly language in C 9778 @cindex inline assembly language 9779 @cindex mixing assembly language and C 9780 9781 The @code{asm} keyword allows you to embed assembler instructions 9782 within C code. GCC provides two forms of inline @code{asm} 9783 statements. A @dfn{basic @code{asm}} statement is one with no 9784 operands (@pxref{Basic Asm}), while an @dfn{extended @code{asm}} 9785 statement (@pxref{Extended Asm}) includes one or more operands. 9786 The extended form is preferred for mixing C and assembly language 9787 within a function, but to include assembly language at 9788 top level you must use basic @code{asm}. 9789 9790 You can also use the @code{asm} keyword to override the assembler name 9791 for a C symbol, or to place a C variable in a specific register. 9792 9793 @menu 9794 * Basic Asm:: Inline assembler without operands. 9795 * Extended Asm:: Inline assembler with operands. 9796 * Constraints:: Constraints for @code{asm} operands 9797 * Asm Labels:: Specifying the assembler name to use for a C symbol. 9798 * Explicit Register Variables:: Defining variables residing in specified 9799 registers. 9800 * Size of an asm:: How GCC calculates the size of an @code{asm} block. 9801 @end menu 9802 9803 @node Basic Asm 9804 @subsection Basic Asm --- Assembler Instructions Without Operands 9805 @cindex basic @code{asm} 9806 @cindex assembly language in C, basic 9807 9808 A basic @code{asm} statement has the following syntax: 9809 9810 @example 9811 asm @var{asm-qualifiers} ( @var{AssemblerInstructions} ) 9812 @end example 9813 9814 For the C language, the @code{asm} keyword is a GNU extension. 9815 When writing C code that can be compiled with @option{-ansi} and the 9816 @option{-std} options that select C dialects without GNU extensions, use 9817 @code{__asm__} instead of @code{asm} (@pxref{Alternate Keywords}). For 9818 the C++ language, @code{asm} is a standard keyword, but @code{__asm__} 9819 can be used for code compiled with @option{-fno-asm}. 9820 9821 @subsubheading Qualifiers 9822 @table @code 9823 @item volatile 9824 The optional @code{volatile} qualifier has no effect. 9825 All basic @code{asm} blocks are implicitly volatile. 9826 9827 @item inline 9828 If you use the @code{inline} qualifier, then for inlining purposes the size 9829 of the @code{asm} statement is taken as the smallest size possible (@pxref{Size 9830 of an asm}). 9831 @end table 9832 9833 @subsubheading Parameters 9834 @table @var 9835 9836 @item AssemblerInstructions 9837 This is a literal string that specifies the assembler code. The string can 9838 contain any instructions recognized by the assembler, including directives. 9839 GCC does not parse the assembler instructions themselves and 9840 does not know what they mean or even whether they are valid assembler input. 9841 9842 You may place multiple assembler instructions together in a single @code{asm} 9843 string, separated by the characters normally used in assembly code for the 9844 system. A combination that works in most places is a newline to break the 9845 line, plus a tab character (written as @samp{\n\t}). 9846 Some assemblers allow semicolons as a line separator. However, 9847 note that some assembler dialects use semicolons to start a comment. 9848 @end table 9849 9850 @subsubheading Remarks 9851 Using extended @code{asm} (@pxref{Extended Asm}) typically produces 9852 smaller, safer, and more efficient code, and in most cases it is a 9853 better solution than basic @code{asm}. However, there are two 9854 situations where only basic @code{asm} can be used: 9855 9856 @itemize @bullet 9857 @item 9858 Extended @code{asm} statements have to be inside a C 9859 function, so to write inline assembly language at file scope (``top-level''), 9860 outside of C functions, you must use basic @code{asm}. 9861 You can use this technique to emit assembler directives, 9862 define assembly language macros that can be invoked elsewhere in the file, 9863 or write entire functions in assembly language. 9864 Basic @code{asm} statements outside of functions may not use any 9865 qualifiers. 9866 9867 @item 9868 Functions declared 9869 with the @code{naked} attribute also require basic @code{asm} 9870 (@pxref{Function Attributes}). 9871 @end itemize 9872 9873 Safely accessing C data and calling functions from basic @code{asm} is more 9874 complex than it may appear. To access C data, it is better to use extended 9875 @code{asm}. 9876 9877 Do not expect a sequence of @code{asm} statements to remain perfectly 9878 consecutive after compilation. If certain instructions need to remain 9879 consecutive in the output, put them in a single multi-instruction @code{asm} 9880 statement. Note that GCC's optimizers can move @code{asm} statements 9881 relative to other code, including across jumps. 9882 9883 @code{asm} statements may not perform jumps into other @code{asm} statements. 9884 GCC does not know about these jumps, and therefore cannot take 9885 account of them when deciding how to optimize. Jumps from @code{asm} to C 9886 labels are only supported in extended @code{asm}. 9887 9888 Under certain circumstances, GCC may duplicate (or remove duplicates of) your 9889 assembly code when optimizing. This can lead to unexpected duplicate 9890 symbol errors during compilation if your assembly code defines symbols or 9891 labels. 9892 9893 @strong{Warning:} The C standards do not specify semantics for @code{asm}, 9894 making it a potential source of incompatibilities between compilers. These 9895 incompatibilities may not produce compiler warnings/errors. 9896 9897 GCC does not parse basic @code{asm}'s @var{AssemblerInstructions}, which 9898 means there is no way to communicate to the compiler what is happening 9899 inside them. GCC has no visibility of symbols in the @code{asm} and may 9900 discard them as unreferenced. It also does not know about side effects of 9901 the assembler code, such as modifications to memory or registers. Unlike 9902 some compilers, GCC assumes that no changes to general purpose registers 9903 occur. This assumption may change in a future release. 9904 9905 To avoid complications from future changes to the semantics and the 9906 compatibility issues between compilers, consider replacing basic @code{asm} 9907 with extended @code{asm}. See 9908 @uref{https://gcc.gnu.org/wiki/ConvertBasicAsmToExtended, How to convert 9909 from basic asm to extended asm} for information about how to perform this 9910 conversion. 9911 9912 The compiler copies the assembler instructions in a basic @code{asm} 9913 verbatim to the assembly language output file, without 9914 processing dialects or any of the @samp{%} operators that are available with 9915 extended @code{asm}. This results in minor differences between basic 9916 @code{asm} strings and extended @code{asm} templates. For example, to refer to 9917 registers you might use @samp{%eax} in basic @code{asm} and 9918 @samp{%%eax} in extended @code{asm}. 9919 9920 On targets such as x86 that support multiple assembler dialects, 9921 all basic @code{asm} blocks use the assembler dialect specified by the 9922 @option{-masm} command-line option (@pxref{x86 Options}). 9923 Basic @code{asm} provides no 9924 mechanism to provide different assembler strings for different dialects. 9925 9926 For basic @code{asm} with non-empty assembler string GCC assumes 9927 the assembler block does not change any general purpose registers, 9928 but it may read or write any globally accessible variable. 9929 9930 Here is an example of basic @code{asm} for i386: 9931 9932 @example 9933 /* Note that this code will not compile with -masm=intel */ 9934 #define DebugBreak() asm("int $3") 9935 @end example 9936 9937 @node Extended Asm 9938 @subsection Extended Asm - Assembler Instructions with C Expression Operands 9939 @cindex extended @code{asm} 9940 @cindex assembly language in C, extended 9941 9942 With extended @code{asm} you can read and write C variables from 9943 assembler and perform jumps from assembler code to C labels. 9944 Extended @code{asm} syntax uses colons (@samp{:}) to delimit 9945 the operand parameters after the assembler template: 9946 9947 @example 9948 asm @var{asm-qualifiers} ( @var{AssemblerTemplate} 9949 : @var{OutputOperands} 9950 @r{[} : @var{InputOperands} 9951 @r{[} : @var{Clobbers} @r{]} @r{]}) 9952 9953 asm @var{asm-qualifiers} ( @var{AssemblerTemplate} 9954 : @var{OutputOperands} 9955 : @var{InputOperands} 9956 : @var{Clobbers} 9957 : @var{GotoLabels}) 9958 @end example 9959 where in the last form, @var{asm-qualifiers} contains @code{goto} (and in the 9960 first form, not). 9961 9962 The @code{asm} keyword is a GNU extension. 9963 When writing code that can be compiled with @option{-ansi} and the 9964 various @option{-std} options, use @code{__asm__} instead of 9965 @code{asm} (@pxref{Alternate Keywords}). 9966 9967 @subsubheading Qualifiers 9968 @table @code 9969 9970 @item volatile 9971 The typical use of extended @code{asm} statements is to manipulate input 9972 values to produce output values. However, your @code{asm} statements may 9973 also produce side effects. If so, you may need to use the @code{volatile} 9974 qualifier to disable certain optimizations. @xref{Volatile}. 9975 9976 @item inline 9977 If you use the @code{inline} qualifier, then for inlining purposes the size 9978 of the @code{asm} statement is taken as the smallest size possible 9979 (@pxref{Size of an asm}). 9980 9981 @item goto 9982 This qualifier informs the compiler that the @code{asm} statement may 9983 perform a jump to one of the labels listed in the @var{GotoLabels}. 9984 @xref{GotoLabels}. 9985 @end table 9986 9987 @subsubheading Parameters 9988 @table @var 9989 @item AssemblerTemplate 9990 This is a literal string that is the template for the assembler code. It is a 9991 combination of fixed text and tokens that refer to the input, output, 9992 and goto parameters. @xref{AssemblerTemplate}. 9993 9994 @item OutputOperands 9995 A comma-separated list of the C variables modified by the instructions in the 9996 @var{AssemblerTemplate}. An empty list is permitted. @xref{OutputOperands}. 9997 9998 @item InputOperands 9999 A comma-separated list of C expressions read by the instructions in the 10000 @var{AssemblerTemplate}. An empty list is permitted. @xref{InputOperands}. 10001 10002 @item Clobbers 10003 A comma-separated list of registers or other values changed by the 10004 @var{AssemblerTemplate}, beyond those listed as outputs. 10005 An empty list is permitted. @xref{Clobbers and Scratch Registers}. 10006 10007 @item GotoLabels 10008 When you are using the @code{goto} form of @code{asm}, this section contains 10009 the list of all C labels to which the code in the 10010 @var{AssemblerTemplate} may jump. 10011 @xref{GotoLabels}. 10012 10013 @code{asm} statements may not perform jumps into other @code{asm} statements, 10014 only to the listed @var{GotoLabels}. 10015 GCC's optimizers do not know about other jumps; therefore they cannot take 10016 account of them when deciding how to optimize. 10017 @end table 10018 10019 The total number of input + output + goto operands is limited to 30. 10020 10021 @subsubheading Remarks 10022 The @code{asm} statement allows you to include assembly instructions directly 10023 within C code. This may help you to maximize performance in time-sensitive 10024 code or to access assembly instructions that are not readily available to C 10025 programs. 10026 10027 Note that extended @code{asm} statements must be inside a function. Only 10028 basic @code{asm} may be outside functions (@pxref{Basic Asm}). 10029 Functions declared with the @code{naked} attribute also require basic 10030 @code{asm} (@pxref{Function Attributes}). 10031 10032 While the uses of @code{asm} are many and varied, it may help to think of an 10033 @code{asm} statement as a series of low-level instructions that convert input 10034 parameters to output parameters. So a simple (if not particularly useful) 10035 example for i386 using @code{asm} might look like this: 10036 10037 @example 10038 int src = 1; 10039 int dst; 10040 10041 asm ("mov %1, %0\n\t" 10042 "add $1, %0" 10043 : "=r" (dst) 10044 : "r" (src)); 10045 10046 printf("%d\n", dst); 10047 @end example 10048 10049 This code copies @code{src} to @code{dst} and add 1 to @code{dst}. 10050 10051 @anchor{Volatile} 10052 @subsubsection Volatile 10053 @cindex volatile @code{asm} 10054 @cindex @code{asm} volatile 10055 10056 GCC's optimizers sometimes discard @code{asm} statements if they determine 10057 there is no need for the output variables. Also, the optimizers may move 10058 code out of loops if they believe that the code will always return the same 10059 result (i.e.@: none of its input values change between calls). Using the 10060 @code{volatile} qualifier disables these optimizations. @code{asm} statements 10061 that have no output operands and @code{asm goto} statements, 10062 are implicitly volatile. 10063 10064 This i386 code demonstrates a case that does not use (or require) the 10065 @code{volatile} qualifier. If it is performing assertion checking, this code 10066 uses @code{asm} to perform the validation. Otherwise, @code{dwRes} is 10067 unreferenced by any code. As a result, the optimizers can discard the 10068 @code{asm} statement, which in turn removes the need for the entire 10069 @code{DoCheck} routine. By omitting the @code{volatile} qualifier when it 10070 isn't needed you allow the optimizers to produce the most efficient code 10071 possible. 10072 10073 @example 10074 void DoCheck(uint32_t dwSomeValue) 10075 @{ 10076 uint32_t dwRes; 10077 10078 // Assumes dwSomeValue is not zero. 10079 asm ("bsfl %1,%0" 10080 : "=r" (dwRes) 10081 : "r" (dwSomeValue) 10082 : "cc"); 10083 10084 assert(dwRes > 3); 10085 @} 10086 @end example 10087 10088 The next example shows a case where the optimizers can recognize that the input 10089 (@code{dwSomeValue}) never changes during the execution of the function and can 10090 therefore move the @code{asm} outside the loop to produce more efficient code. 10091 Again, using the @code{volatile} qualifier disables this type of optimization. 10092 10093 @example 10094 void do_print(uint32_t dwSomeValue) 10095 @{ 10096 uint32_t dwRes; 10097 10098 for (uint32_t x=0; x < 5; x++) 10099 @{ 10100 // Assumes dwSomeValue is not zero. 10101 asm ("bsfl %1,%0" 10102 : "=r" (dwRes) 10103 : "r" (dwSomeValue) 10104 : "cc"); 10105 10106 printf("%u: %u %u\n", x, dwSomeValue, dwRes); 10107 @} 10108 @} 10109 @end example 10110 10111 The following example demonstrates a case where you need to use the 10112 @code{volatile} qualifier. 10113 It uses the x86 @code{rdtsc} instruction, which reads 10114 the computer's time-stamp counter. Without the @code{volatile} qualifier, 10115 the optimizers might assume that the @code{asm} block will always return the 10116 same value and therefore optimize away the second call. 10117 10118 @example 10119 uint64_t msr; 10120 10121 asm volatile ( "rdtsc\n\t" // Returns the time in EDX:EAX. 10122 "shl $32, %%rdx\n\t" // Shift the upper bits left. 10123 "or %%rdx, %0" // 'Or' in the lower bits. 10124 : "=a" (msr) 10125 : 10126 : "rdx"); 10127 10128 printf("msr: %llx\n", msr); 10129 10130 // Do other work... 10131 10132 // Reprint the timestamp 10133 asm volatile ( "rdtsc\n\t" // Returns the time in EDX:EAX. 10134 "shl $32, %%rdx\n\t" // Shift the upper bits left. 10135 "or %%rdx, %0" // 'Or' in the lower bits. 10136 : "=a" (msr) 10137 : 10138 : "rdx"); 10139 10140 printf("msr: %llx\n", msr); 10141 @end example 10142 10143 GCC's optimizers do not treat this code like the non-volatile code in the 10144 earlier examples. They do not move it out of loops or omit it on the 10145 assumption that the result from a previous call is still valid. 10146 10147 Note that the compiler can move even @code{volatile asm} instructions relative 10148 to other code, including across jump instructions. For example, on many 10149 targets there is a system register that controls the rounding mode of 10150 floating-point operations. Setting it with a @code{volatile asm} statement, 10151 as in the following PowerPC example, does not work reliably. 10152 10153 @example 10154 asm volatile("mtfsf 255, %0" : : "f" (fpenv)); 10155 sum = x + y; 10156 @end example 10157 10158 The compiler may move the addition back before the @code{volatile asm} 10159 statement. To make it work as expected, add an artificial dependency to 10160 the @code{asm} by referencing a variable in the subsequent code, for 10161 example: 10162 10163 @example 10164 asm volatile ("mtfsf 255,%1" : "=X" (sum) : "f" (fpenv)); 10165 sum = x + y; 10166 @end example 10167 10168 Under certain circumstances, GCC may duplicate (or remove duplicates of) your 10169 assembly code when optimizing. This can lead to unexpected duplicate symbol 10170 errors during compilation if your @code{asm} code defines symbols or labels. 10171 Using @samp{%=} 10172 (@pxref{AssemblerTemplate}) may help resolve this problem. 10173 10174 @anchor{AssemblerTemplate} 10175 @subsubsection Assembler Template 10176 @cindex @code{asm} assembler template 10177 10178 An assembler template is a literal string containing assembler instructions. 10179 The compiler replaces tokens in the template that refer 10180 to inputs, outputs, and goto labels, 10181 and then outputs the resulting string to the assembler. The 10182 string can contain any instructions recognized by the assembler, including 10183 directives. GCC does not parse the assembler instructions 10184 themselves and does not know what they mean or even whether they are valid 10185 assembler input. However, it does count the statements 10186 (@pxref{Size of an asm}). 10187 10188 You may place multiple assembler instructions together in a single @code{asm} 10189 string, separated by the characters normally used in assembly code for the 10190 system. A combination that works in most places is a newline to break the 10191 line, plus a tab character to move to the instruction field (written as 10192 @samp{\n\t}). 10193 Some assemblers allow semicolons as a line separator. However, note 10194 that some assembler dialects use semicolons to start a comment. 10195 10196 Do not expect a sequence of @code{asm} statements to remain perfectly 10197 consecutive after compilation, even when you are using the @code{volatile} 10198 qualifier. If certain instructions need to remain consecutive in the output, 10199 put them in a single multi-instruction @code{asm} statement. 10200 10201 Accessing data from C programs without using input/output operands (such as 10202 by using global symbols directly from the assembler template) may not work as 10203 expected. Similarly, calling functions directly from an assembler template 10204 requires a detailed understanding of the target assembler and ABI. 10205 10206 Since GCC does not parse the assembler template, 10207 it has no visibility of any 10208 symbols it references. This may result in GCC discarding those symbols as 10209 unreferenced unless they are also listed as input, output, or goto operands. 10210 10211 @subsubheading Special format strings 10212 10213 In addition to the tokens described by the input, output, and goto operands, 10214 these tokens have special meanings in the assembler template: 10215 10216 @table @samp 10217 @item %% 10218 Outputs a single @samp{%} into the assembler code. 10219 10220 @item %= 10221 Outputs a number that is unique to each instance of the @code{asm} 10222 statement in the entire compilation. This option is useful when creating local 10223 labels and referring to them multiple times in a single template that 10224 generates multiple assembler instructions. 10225 10226 @item %@{ 10227 @itemx %| 10228 @itemx %@} 10229 Outputs @samp{@{}, @samp{|}, and @samp{@}} characters (respectively) 10230 into the assembler code. When unescaped, these characters have special 10231 meaning to indicate multiple assembler dialects, as described below. 10232 @end table 10233 10234 @subsubheading Multiple assembler dialects in @code{asm} templates 10235 10236 On targets such as x86, GCC supports multiple assembler dialects. 10237 The @option{-masm} option controls which dialect GCC uses as its 10238 default for inline assembler. The target-specific documentation for the 10239 @option{-masm} option contains the list of supported dialects, as well as the 10240 default dialect if the option is not specified. This information may be 10241 important to understand, since assembler code that works correctly when 10242 compiled using one dialect will likely fail if compiled using another. 10243 @xref{x86 Options}. 10244 10245 If your code needs to support multiple assembler dialects (for example, if 10246 you are writing public headers that need to support a variety of compilation 10247 options), use constructs of this form: 10248 10249 @example 10250 @{ dialect0 | dialect1 | dialect2... @} 10251 @end example 10252 10253 This construct outputs @code{dialect0} 10254 when using dialect #0 to compile the code, 10255 @code{dialect1} for dialect #1, etc. If there are fewer alternatives within the 10256 braces than the number of dialects the compiler supports, the construct 10257 outputs nothing. 10258 10259 For example, if an x86 compiler supports two dialects 10260 (@samp{att}, @samp{intel}), an 10261 assembler template such as this: 10262 10263 @example 10264 "bt@{l %[Offset],%[Base] | %[Base],%[Offset]@}; jc %l2" 10265 @end example 10266 10267 @noindent 10268 is equivalent to one of 10269 10270 @example 10271 "btl %[Offset],%[Base] ; jc %l2" @r{/* att dialect */} 10272 "bt %[Base],%[Offset]; jc %l2" @r{/* intel dialect */} 10273 @end example 10274 10275 Using that same compiler, this code: 10276 10277 @example 10278 "xchg@{l@}\t@{%%@}ebx, %1" 10279 @end example 10280 10281 @noindent 10282 corresponds to either 10283 10284 @example 10285 "xchgl\t%%ebx, %1" @r{/* att dialect */} 10286 "xchg\tebx, %1" @r{/* intel dialect */} 10287 @end example 10288 10289 There is no support for nesting dialect alternatives. 10290 10291 @anchor{OutputOperands} 10292 @subsubsection Output Operands 10293 @cindex @code{asm} output operands 10294 10295 An @code{asm} statement has zero or more output operands indicating the names 10296 of C variables modified by the assembler code. 10297 10298 In this i386 example, @code{old} (referred to in the template string as 10299 @code{%0}) and @code{*Base} (as @code{%1}) are outputs and @code{Offset} 10300 (@code{%2}) is an input: 10301 10302 @example 10303 bool old; 10304 10305 __asm__ ("btsl %2,%1\n\t" // Turn on zero-based bit #Offset in Base. 10306 "sbb %0,%0" // Use the CF to calculate old. 10307 : "=r" (old), "+rm" (*Base) 10308 : "Ir" (Offset) 10309 : "cc"); 10310 10311 return old; 10312 @end example 10313 10314 Operands are separated by commas. Each operand has this format: 10315 10316 @example 10317 @r{[} [@var{asmSymbolicName}] @r{]} @var{constraint} (@var{cvariablename}) 10318 @end example 10319 10320 @table @var 10321 @item asmSymbolicName 10322 Specifies a symbolic name for the operand. 10323 Reference the name in the assembler template 10324 by enclosing it in square brackets 10325 (i.e.@: @samp{%[Value]}). The scope of the name is the @code{asm} statement 10326 that contains the definition. Any valid C variable name is acceptable, 10327 including names already defined in the surrounding code. No two operands 10328 within the same @code{asm} statement can use the same symbolic name. 10329 10330 When not using an @var{asmSymbolicName}, use the (zero-based) position 10331 of the operand 10332 in the list of operands in the assembler template. For example if there are 10333 three output operands, use @samp{%0} in the template to refer to the first, 10334 @samp{%1} for the second, and @samp{%2} for the third. 10335 10336 @item constraint 10337 A string constant specifying constraints on the placement of the operand; 10338 @xref{Constraints}, for details. 10339 10340 Output constraints must begin with either @samp{=} (a variable overwriting an 10341 existing value) or @samp{+} (when reading and writing). When using 10342 @samp{=}, do not assume the location contains the existing value 10343 on entry to the @code{asm}, except 10344 when the operand is tied to an input; @pxref{InputOperands,,Input Operands}. 10345 10346 After the prefix, there must be one or more additional constraints 10347 (@pxref{Constraints}) that describe where the value resides. Common 10348 constraints include @samp{r} for register and @samp{m} for memory. 10349 When you list more than one possible location (for example, @code{"=rm"}), 10350 the compiler chooses the most efficient one based on the current context. 10351 If you list as many alternates as the @code{asm} statement allows, you permit 10352 the optimizers to produce the best possible code. 10353 If you must use a specific register, but your Machine Constraints do not 10354 provide sufficient control to select the specific register you want, 10355 local register variables may provide a solution (@pxref{Local Register 10356 Variables}). 10357 10358 @item cvariablename 10359 Specifies a C lvalue expression to hold the output, typically a variable name. 10360 The enclosing parentheses are a required part of the syntax. 10361 10362 @end table 10363 10364 When the compiler selects the registers to use to 10365 represent the output operands, it does not use any of the clobbered registers 10366 (@pxref{Clobbers and Scratch Registers}). 10367 10368 Output operand expressions must be lvalues. The compiler cannot check whether 10369 the operands have data types that are reasonable for the instruction being 10370 executed. For output expressions that are not directly addressable (for 10371 example a bit-field), the constraint must allow a register. In that case, GCC 10372 uses the register as the output of the @code{asm}, and then stores that 10373 register into the output. 10374 10375 Operands using the @samp{+} constraint modifier count as two operands 10376 (that is, both as input and output) towards the total maximum of 30 operands 10377 per @code{asm} statement. 10378 10379 Use the @samp{&} constraint modifier (@pxref{Modifiers}) on all output 10380 operands that must not overlap an input. Otherwise, 10381 GCC may allocate the output operand in the same register as an unrelated 10382 input operand, on the assumption that the assembler code consumes its 10383 inputs before producing outputs. This assumption may be false if the assembler 10384 code actually consists of more than one instruction. 10385 10386 The same problem can occur if one output parameter (@var{a}) allows a register 10387 constraint and another output parameter (@var{b}) allows a memory constraint. 10388 The code generated by GCC to access the memory address in @var{b} can contain 10389 registers which @emph{might} be shared by @var{a}, and GCC considers those 10390 registers to be inputs to the asm. As above, GCC assumes that such input 10391 registers are consumed before any outputs are written. This assumption may 10392 result in incorrect behavior if the @code{asm} statement writes to @var{a} 10393 before using 10394 @var{b}. Combining the @samp{&} modifier with the register constraint on @var{a} 10395 ensures that modifying @var{a} does not affect the address referenced by 10396 @var{b}. Otherwise, the location of @var{b} 10397 is undefined if @var{a} is modified before using @var{b}. 10398 10399 @code{asm} supports operand modifiers on operands (for example @samp{%k2} 10400 instead of simply @samp{%2}). Typically these qualifiers are hardware 10401 dependent. The list of supported modifiers for x86 is found at 10402 @ref{x86Operandmodifiers,x86 Operand modifiers}. 10403 10404 If the C code that follows the @code{asm} makes no use of any of the output 10405 operands, use @code{volatile} for the @code{asm} statement to prevent the 10406 optimizers from discarding the @code{asm} statement as unneeded 10407 (see @ref{Volatile}). 10408 10409 This code makes no use of the optional @var{asmSymbolicName}. Therefore it 10410 references the first output operand as @code{%0} (were there a second, it 10411 would be @code{%1}, etc). The number of the first input operand is one greater 10412 than that of the last output operand. In this i386 example, that makes 10413 @code{Mask} referenced as @code{%1}: 10414 10415 @example 10416 uint32_t Mask = 1234; 10417 uint32_t Index; 10418 10419 asm ("bsfl %1, %0" 10420 : "=r" (Index) 10421 : "r" (Mask) 10422 : "cc"); 10423 @end example 10424 10425 That code overwrites the variable @code{Index} (@samp{=}), 10426 placing the value in a register (@samp{r}). 10427 Using the generic @samp{r} constraint instead of a constraint for a specific 10428 register allows the compiler to pick the register to use, which can result 10429 in more efficient code. This may not be possible if an assembler instruction 10430 requires a specific register. 10431 10432 The following i386 example uses the @var{asmSymbolicName} syntax. 10433 It produces the 10434 same result as the code above, but some may consider it more readable or more 10435 maintainable since reordering index numbers is not necessary when adding or 10436 removing operands. The names @code{aIndex} and @code{aMask} 10437 are only used in this example to emphasize which 10438 names get used where. 10439 It is acceptable to reuse the names @code{Index} and @code{Mask}. 10440 10441 @example 10442 uint32_t Mask = 1234; 10443 uint32_t Index; 10444 10445 asm ("bsfl %[aMask], %[aIndex]" 10446 : [aIndex] "=r" (Index) 10447 : [aMask] "r" (Mask) 10448 : "cc"); 10449 @end example 10450 10451 Here are some more examples of output operands. 10452 10453 @example 10454 uint32_t c = 1; 10455 uint32_t d; 10456 uint32_t *e = &c; 10457 10458 asm ("mov %[e], %[d]" 10459 : [d] "=rm" (d) 10460 : [e] "rm" (*e)); 10461 @end example 10462 10463 Here, @code{d} may either be in a register or in memory. Since the compiler 10464 might already have the current value of the @code{uint32_t} location 10465 pointed to by @code{e} 10466 in a register, you can enable it to choose the best location 10467 for @code{d} by specifying both constraints. 10468 10469 @anchor{FlagOutputOperands} 10470 @subsubsection Flag Output Operands 10471 @cindex @code{asm} flag output operands 10472 10473 Some targets have a special register that holds the ``flags'' for the 10474 result of an operation or comparison. Normally, the contents of that 10475 register are either unmodifed by the asm, or the @code{asm} statement is 10476 considered to clobber the contents. 10477 10478 On some targets, a special form of output operand exists by which 10479 conditions in the flags register may be outputs of the asm. The set of 10480 conditions supported are target specific, but the general rule is that 10481 the output variable must be a scalar integer, and the value is boolean. 10482 When supported, the target defines the preprocessor symbol 10483 @code{__GCC_ASM_FLAG_OUTPUTS__}. 10484 10485 Because of the special nature of the flag output operands, the constraint 10486 may not include alternatives. 10487 10488 Most often, the target has only one flags register, and thus is an implied 10489 operand of many instructions. In this case, the operand should not be 10490 referenced within the assembler template via @code{%0} etc, as there's 10491 no corresponding text in the assembly language. 10492 10493 @table @asis 10494 @item ARM 10495 @itemx AArch64 10496 The flag output constraints for the ARM family are of the form 10497 @samp{=@@cc@var{cond}} where @var{cond} is one of the standard 10498 conditions defined in the ARM ARM for @code{ConditionHolds}. 10499 10500 @table @code 10501 @item eq 10502 Z flag set, or equal 10503 @item ne 10504 Z flag clear or not equal 10505 @item cs 10506 @itemx hs 10507 C flag set or unsigned greater than equal 10508 @item cc 10509 @itemx lo 10510 C flag clear or unsigned less than 10511 @item mi 10512 N flag set or ``minus'' 10513 @item pl 10514 N flag clear or ``plus'' 10515 @item vs 10516 V flag set or signed overflow 10517 @item vc 10518 V flag clear 10519 @item hi 10520 unsigned greater than 10521 @item ls 10522 unsigned less than equal 10523 @item ge 10524 signed greater than equal 10525 @item lt 10526 signed less than 10527 @item gt 10528 signed greater than 10529 @item le 10530 signed less than equal 10531 @end table 10532 10533 The flag output constraints are not supported in thumb1 mode. 10534 10535 @item x86 family 10536 The flag output constraints for the x86 family are of the form 10537 @samp{=@@cc@var{cond}} where @var{cond} is one of the standard 10538 conditions defined in the ISA manual for @code{j@var{cc}} or 10539 @code{set@var{cc}}. 10540 10541 @table @code 10542 @item a 10543 ``above'' or unsigned greater than 10544 @item ae 10545 ``above or equal'' or unsigned greater than or equal 10546 @item b 10547 ``below'' or unsigned less than 10548 @item be 10549 ``below or equal'' or unsigned less than or equal 10550 @item c 10551 carry flag set 10552 @item e 10553 @itemx z 10554 ``equal'' or zero flag set 10555 @item g 10556 signed greater than 10557 @item ge 10558 signed greater than or equal 10559 @item l 10560 signed less than 10561 @item le 10562 signed less than or equal 10563 @item o 10564 overflow flag set 10565 @item p 10566 parity flag set 10567 @item s 10568 sign flag set 10569 @item na 10570 @itemx nae 10571 @itemx nb 10572 @itemx nbe 10573 @itemx nc 10574 @itemx ne 10575 @itemx ng 10576 @itemx nge 10577 @itemx nl 10578 @itemx nle 10579 @itemx no 10580 @itemx np 10581 @itemx ns 10582 @itemx nz 10583 ``not'' @var{flag}, or inverted versions of those above 10584 @end table 10585 10586 @end table 10587 10588 @anchor{InputOperands} 10589 @subsubsection Input Operands 10590 @cindex @code{asm} input operands 10591 @cindex @code{asm} expressions 10592 10593 Input operands make values from C variables and expressions available to the 10594 assembly code. 10595 10596 Operands are separated by commas. Each operand has this format: 10597 10598 @example 10599 @r{[} [@var{asmSymbolicName}] @r{]} @var{constraint} (@var{cexpression}) 10600 @end example 10601 10602 @table @var 10603 @item asmSymbolicName 10604 Specifies a symbolic name for the operand. 10605 Reference the name in the assembler template 10606 by enclosing it in square brackets 10607 (i.e.@: @samp{%[Value]}). The scope of the name is the @code{asm} statement 10608 that contains the definition. Any valid C variable name is acceptable, 10609 including names already defined in the surrounding code. No two operands 10610 within the same @code{asm} statement can use the same symbolic name. 10611 10612 When not using an @var{asmSymbolicName}, use the (zero-based) position 10613 of the operand 10614 in the list of operands in the assembler template. For example if there are 10615 two output operands and three inputs, 10616 use @samp{%2} in the template to refer to the first input operand, 10617 @samp{%3} for the second, and @samp{%4} for the third. 10618 10619 @item constraint 10620 A string constant specifying constraints on the placement of the operand; 10621 @xref{Constraints}, for details. 10622 10623 Input constraint strings may not begin with either @samp{=} or @samp{+}. 10624 When you list more than one possible location (for example, @samp{"irm"}), 10625 the compiler chooses the most efficient one based on the current context. 10626 If you must use a specific register, but your Machine Constraints do not 10627 provide sufficient control to select the specific register you want, 10628 local register variables may provide a solution (@pxref{Local Register 10629 Variables}). 10630 10631 Input constraints can also be digits (for example, @code{"0"}). This indicates 10632 that the specified input must be in the same place as the output constraint 10633 at the (zero-based) index in the output constraint list. 10634 When using @var{asmSymbolicName} syntax for the output operands, 10635 you may use these names (enclosed in brackets @samp{[]}) instead of digits. 10636 10637 @item cexpression 10638 This is the C variable or expression being passed to the @code{asm} statement 10639 as input. The enclosing parentheses are a required part of the syntax. 10640 10641 @end table 10642 10643 When the compiler selects the registers to use to represent the input 10644 operands, it does not use any of the clobbered registers 10645 (@pxref{Clobbers and Scratch Registers}). 10646 10647 If there are no output operands but there are input operands, place two 10648 consecutive colons where the output operands would go: 10649 10650 @example 10651 __asm__ ("some instructions" 10652 : /* No outputs. */ 10653 : "r" (Offset / 8)); 10654 @end example 10655 10656 @strong{Warning:} Do @emph{not} modify the contents of input-only operands 10657 (except for inputs tied to outputs). The compiler assumes that on exit from 10658 the @code{asm} statement these operands contain the same values as they 10659 had before executing the statement. 10660 It is @emph{not} possible to use clobbers 10661 to inform the compiler that the values in these inputs are changing. One 10662 common work-around is to tie the changing input variable to an output variable 10663 that never gets used. Note, however, that if the code that follows the 10664 @code{asm} statement makes no use of any of the output operands, the GCC 10665 optimizers may discard the @code{asm} statement as unneeded 10666 (see @ref{Volatile}). 10667 10668 @code{asm} supports operand modifiers on operands (for example @samp{%k2} 10669 instead of simply @samp{%2}). Typically these qualifiers are hardware 10670 dependent. The list of supported modifiers for x86 is found at 10671 @ref{x86Operandmodifiers,x86 Operand modifiers}. 10672 10673 In this example using the fictitious @code{combine} instruction, the 10674 constraint @code{"0"} for input operand 1 says that it must occupy the same 10675 location as output operand 0. Only input operands may use numbers in 10676 constraints, and they must each refer to an output operand. Only a number (or 10677 the symbolic assembler name) in the constraint can guarantee that one operand 10678 is in the same place as another. The mere fact that @code{foo} is the value of 10679 both operands is not enough to guarantee that they are in the same place in 10680 the generated assembler code. 10681 10682 @example 10683 asm ("combine %2, %0" 10684 : "=r" (foo) 10685 : "0" (foo), "g" (bar)); 10686 @end example 10687 10688 Here is an example using symbolic names. 10689 10690 @example 10691 asm ("cmoveq %1, %2, %[result]" 10692 : [result] "=r"(result) 10693 : "r" (test), "r" (new), "[result]" (old)); 10694 @end example 10695 10696 @anchor{Clobbers and Scratch Registers} 10697 @subsubsection Clobbers and Scratch Registers 10698 @cindex @code{asm} clobbers 10699 @cindex @code{asm} scratch registers 10700 10701 While the compiler is aware of changes to entries listed in the output 10702 operands, the inline @code{asm} code may modify more than just the outputs. For 10703 example, calculations may require additional registers, or the processor may 10704 overwrite a register as a side effect of a particular assembler instruction. 10705 In order to inform the compiler of these changes, list them in the clobber 10706 list. Clobber list items are either register names or the special clobbers 10707 (listed below). Each clobber list item is a string constant 10708 enclosed in double quotes and separated by commas. 10709 10710 Clobber descriptions may not in any way overlap with an input or output 10711 operand. For example, you may not have an operand describing a register class 10712 with one member when listing that register in the clobber list. Variables 10713 declared to live in specific registers (@pxref{Explicit Register 10714 Variables}) and used 10715 as @code{asm} input or output operands must have no part mentioned in the 10716 clobber description. In particular, there is no way to specify that input 10717 operands get modified without also specifying them as output operands. 10718 10719 When the compiler selects which registers to use to represent input and output 10720 operands, it does not use any of the clobbered registers. As a result, 10721 clobbered registers are available for any use in the assembler code. 10722 10723 Another restriction is that the clobber list should not contain the 10724 stack pointer register. This is because the compiler requires the 10725 value of the stack pointer to be the same after an @code{asm} 10726 statement as it was on entry to the statement. However, previous 10727 versions of GCC did not enforce this rule and allowed the stack 10728 pointer to appear in the list, with unclear semantics. This behavior 10729 is deprecated and listing the stack pointer may become an error in 10730 future versions of GCC@. 10731 10732 Here is a realistic example for the VAX showing the use of clobbered 10733 registers: 10734 10735 @example 10736 asm volatile ("movc3 %0, %1, %2" 10737 : /* No outputs. */ 10738 : "g" (from), "g" (to), "g" (count) 10739 : "r0", "r1", "r2", "r3", "r4", "r5", "memory"); 10740 @end example 10741 10742 Also, there are two special clobber arguments: 10743 10744 @table @code 10745 @item "cc" 10746 The @code{"cc"} clobber indicates that the assembler code modifies the flags 10747 register. On some machines, GCC represents the condition codes as a specific 10748 hardware register; @code{"cc"} serves to name this register. 10749 On other machines, condition code handling is different, 10750 and specifying @code{"cc"} has no effect. But 10751 it is valid no matter what the target. 10752 10753 @item "memory" 10754 The @code{"memory"} clobber tells the compiler that the assembly code 10755 performs memory 10756 reads or writes to items other than those listed in the input and output 10757 operands (for example, accessing the memory pointed to by one of the input 10758 parameters). To ensure memory contains correct values, GCC may need to flush 10759 specific register values to memory before executing the @code{asm}. Further, 10760 the compiler does not assume that any values read from memory before an 10761 @code{asm} remain unchanged after that @code{asm}; it reloads them as 10762 needed. 10763 Using the @code{"memory"} clobber effectively forms a read/write 10764 memory barrier for the compiler. 10765 10766 Note that this clobber does not prevent the @emph{processor} from doing 10767 speculative reads past the @code{asm} statement. To prevent that, you need 10768 processor-specific fence instructions. 10769 10770 @end table 10771 10772 Flushing registers to memory has performance implications and may be 10773 an issue for time-sensitive code. You can provide better information 10774 to GCC to avoid this, as shown in the following examples. At a 10775 minimum, aliasing rules allow GCC to know what memory @emph{doesn't} 10776 need to be flushed. 10777 10778 Here is a fictitious sum of squares instruction, that takes two 10779 pointers to floating point values in memory and produces a floating 10780 point register output. 10781 Notice that @code{x}, and @code{y} both appear twice in the @code{asm} 10782 parameters, once to specify memory accessed, and once to specify a 10783 base register used by the @code{asm}. You won't normally be wasting a 10784 register by doing this as GCC can use the same register for both 10785 purposes. However, it would be foolish to use both @code{%1} and 10786 @code{%3} for @code{x} in this @code{asm} and expect them to be the 10787 same. In fact, @code{%3} may well not be a register. It might be a 10788 symbolic memory reference to the object pointed to by @code{x}. 10789 10790 @smallexample 10791 asm ("sumsq %0, %1, %2" 10792 : "+f" (result) 10793 : "r" (x), "r" (y), "m" (*x), "m" (*y)); 10794 @end smallexample 10795 10796 Here is a fictitious @code{*z++ = *x++ * *y++} instruction. 10797 Notice that the @code{x}, @code{y} and @code{z} pointer registers 10798 must be specified as input/output because the @code{asm} modifies 10799 them. 10800 10801 @smallexample 10802 asm ("vecmul %0, %1, %2" 10803 : "+r" (z), "+r" (x), "+r" (y), "=m" (*z) 10804 : "m" (*x), "m" (*y)); 10805 @end smallexample 10806 10807 An x86 example where the string memory argument is of unknown length. 10808 10809 @smallexample 10810 asm("repne scasb" 10811 : "=c" (count), "+D" (p) 10812 : "m" (*(const char (*)[]) p), "0" (-1), "a" (0)); 10813 @end smallexample 10814 10815 If you know the above will only be reading a ten byte array then you 10816 could instead use a memory input like: 10817 @code{"m" (*(const char (*)[10]) p)}. 10818 10819 Here is an example of a PowerPC vector scale implemented in assembly, 10820 complete with vector and condition code clobbers, and some initialized 10821 offset registers that are unchanged by the @code{asm}. 10822 10823 @smallexample 10824 void 10825 dscal (size_t n, double *x, double alpha) 10826 @{ 10827 asm ("/* lots of asm here */" 10828 : "+m" (*(double (*)[n]) x), "+&r" (n), "+b" (x) 10829 : "d" (alpha), "b" (32), "b" (48), "b" (64), 10830 "b" (80), "b" (96), "b" (112) 10831 : "cr0", 10832 "vs32","vs33","vs34","vs35","vs36","vs37","vs38","vs39", 10833 "vs40","vs41","vs42","vs43","vs44","vs45","vs46","vs47"); 10834 @} 10835 @end smallexample 10836 10837 Rather than allocating fixed registers via clobbers to provide scratch 10838 registers for an @code{asm} statement, an alternative is to define a 10839 variable and make it an early-clobber output as with @code{a2} and 10840 @code{a3} in the example below. This gives the compiler register 10841 allocator more freedom. You can also define a variable and make it an 10842 output tied to an input as with @code{a0} and @code{a1}, tied 10843 respectively to @code{ap} and @code{lda}. Of course, with tied 10844 outputs your @code{asm} can't use the input value after modifying the 10845 output register since they are one and the same register. What's 10846 more, if you omit the early-clobber on the output, it is possible that 10847 GCC might allocate the same register to another of the inputs if GCC 10848 could prove they had the same value on entry to the @code{asm}. This 10849 is why @code{a1} has an early-clobber. Its tied input, @code{lda} 10850 might conceivably be known to have the value 16 and without an 10851 early-clobber share the same register as @code{%11}. On the other 10852 hand, @code{ap} can't be the same as any of the other inputs, so an 10853 early-clobber on @code{a0} is not needed. It is also not desirable in 10854 this case. An early-clobber on @code{a0} would cause GCC to allocate 10855 a separate register for the @code{"m" (*(const double (*)[]) ap)} 10856 input. Note that tying an input to an output is the way to set up an 10857 initialized temporary register modified by an @code{asm} statement. 10858 An input not tied to an output is assumed by GCC to be unchanged, for 10859 example @code{"b" (16)} below sets up @code{%11} to 16, and GCC might 10860 use that register in following code if the value 16 happened to be 10861 needed. You can even use a normal @code{asm} output for a scratch if 10862 all inputs that might share the same register are consumed before the 10863 scratch is used. The VSX registers clobbered by the @code{asm} 10864 statement could have used this technique except for GCC's limit on the 10865 number of @code{asm} parameters. 10866 10867 @smallexample 10868 static void 10869 dgemv_kernel_4x4 (long n, const double *ap, long lda, 10870 const double *x, double *y, double alpha) 10871 @{ 10872 double *a0; 10873 double *a1; 10874 double *a2; 10875 double *a3; 10876 10877 __asm__ 10878 ( 10879 /* lots of asm here */ 10880 "#n=%1 ap=%8=%12 lda=%13 x=%7=%10 y=%0=%2 alpha=%9 o16=%11\n" 10881 "#a0=%3 a1=%4 a2=%5 a3=%6" 10882 : 10883 "+m" (*(double (*)[n]) y), 10884 "+&r" (n), // 1 10885 "+b" (y), // 2 10886 "=b" (a0), // 3 10887 "=&b" (a1), // 4 10888 "=&b" (a2), // 5 10889 "=&b" (a3) // 6 10890 : 10891 "m" (*(const double (*)[n]) x), 10892 "m" (*(const double (*)[]) ap), 10893 "d" (alpha), // 9 10894 "r" (x), // 10 10895 "b" (16), // 11 10896 "3" (ap), // 12 10897 "4" (lda) // 13 10898 : 10899 "cr0", 10900 "vs32","vs33","vs34","vs35","vs36","vs37", 10901 "vs40","vs41","vs42","vs43","vs44","vs45","vs46","vs47" 10902 ); 10903 @} 10904 @end smallexample 10905 10906 @anchor{GotoLabels} 10907 @subsubsection Goto Labels 10908 @cindex @code{asm} goto labels 10909 10910 @code{asm goto} allows assembly code to jump to one or more C labels. The 10911 @var{GotoLabels} section in an @code{asm goto} statement contains 10912 a comma-separated 10913 list of all C labels to which the assembler code may jump. GCC assumes that 10914 @code{asm} execution falls through to the next statement (if this is not the 10915 case, consider using the @code{__builtin_unreachable} intrinsic after the 10916 @code{asm} statement). Optimization of @code{asm goto} may be improved by 10917 using the @code{hot} and @code{cold} label attributes (@pxref{Label 10918 Attributes}). 10919 10920 If the assembler code does modify anything, use the @code{"memory"} clobber 10921 to force the 10922 optimizers to flush all register values to memory and reload them if 10923 necessary after the @code{asm} statement. 10924 10925 Also note that an @code{asm goto} statement is always implicitly 10926 considered volatile. 10927 10928 Be careful when you set output operands inside @code{asm goto} only on 10929 some possible control flow paths. If you don't set up the output on 10930 given path and never use it on this path, it is okay. Otherwise, you 10931 should use @samp{+} constraint modifier meaning that the operand is 10932 input and output one. With this modifier you will have the correct 10933 values on all possible paths from the @code{asm goto}. 10934 10935 To reference a label in the assembler template, prefix it with 10936 @samp{%l} (lowercase @samp{L}) followed by its (zero-based) position 10937 in @var{GotoLabels} plus the number of input and output operands. 10938 Output operand with constraint modifier @samp{+} is counted as two 10939 operands because it is considered as one output and one input operand. 10940 For example, if the @code{asm} has three inputs, one output operand 10941 with constraint modifier @samp{+} and one output operand with 10942 constraint modifier @samp{=} and references two labels, refer to the 10943 first label as @samp{%l6} and the second as @samp{%l7}). 10944 10945 Alternately, you can reference labels using the actual C label name 10946 enclosed in brackets. For example, to reference a label named 10947 @code{carry}, you can use @samp{%l[carry]}. The label must still be 10948 listed in the @var{GotoLabels} section when using this approach. It 10949 is better to use the named references for labels as in this case you 10950 can avoid counting input and output operands and special treatment of 10951 output operands with constraint modifier @samp{+}. 10952 10953 Here is an example of @code{asm goto} for i386: 10954 10955 @example 10956 asm goto ( 10957 "btl %1, %0\n\t" 10958 "jc %l2" 10959 : /* No outputs. */ 10960 : "r" (p1), "r" (p2) 10961 : "cc" 10962 : carry); 10963 10964 return 0; 10965 10966 carry: 10967 return 1; 10968 @end example 10969 10970 The following example shows an @code{asm goto} that uses a memory clobber. 10971 10972 @example 10973 int frob(int x) 10974 @{ 10975 int y; 10976 asm goto ("frob %%r5, %1; jc %l[error]; mov (%2), %%r5" 10977 : /* No outputs. */ 10978 : "r"(x), "r"(&y) 10979 : "r5", "memory" 10980 : error); 10981 return y; 10982 error: 10983 return -1; 10984 @} 10985 @end example 10986 10987 The following example shows an @code{asm goto} that uses an output. 10988 10989 @example 10990 int foo(int count) 10991 @{ 10992 asm goto ("dec %0; jb %l[stop]" 10993 : "+r" (count) 10994 : 10995 : 10996 : stop); 10997 return count; 10998 stop: 10999 return 0; 11000 @} 11001 @end example 11002 11003 The following artificial example shows an @code{asm goto} that sets 11004 up an output only on one path inside the @code{asm goto}. Usage of 11005 constraint modifier @code{=} instead of @code{+} would be wrong as 11006 @code{factor} is used on all paths from the @code{asm goto}. 11007 11008 @example 11009 int foo(int inp) 11010 @{ 11011 int factor = 0; 11012 asm goto ("cmp %1, 10; jb %l[lab]; mov 2, %0" 11013 : "+r" (factor) 11014 : "r" (inp) 11015 : 11016 : lab); 11017 lab: 11018 return inp * factor; /* return 2 * inp or 0 if inp < 10 */ 11019 @} 11020 @end example 11021 11022 @anchor{x86Operandmodifiers} 11023 @subsubsection x86 Operand Modifiers 11024 11025 References to input, output, and goto operands in the assembler template 11026 of extended @code{asm} statements can use 11027 modifiers to affect the way the operands are formatted in 11028 the code output to the assembler. For example, the 11029 following code uses the @samp{h} and @samp{b} modifiers for x86: 11030 11031 @example 11032 uint16_t num; 11033 asm volatile ("xchg %h0, %b0" : "+a" (num) ); 11034 @end example 11035 11036 @noindent 11037 These modifiers generate this assembler code: 11038 11039 @example 11040 xchg %ah, %al 11041 @end example 11042 11043 The rest of this discussion uses the following code for illustrative purposes. 11044 11045 @example 11046 int main() 11047 @{ 11048 int iInt = 1; 11049 11050 top: 11051 11052 asm volatile goto ("some assembler instructions here" 11053 : /* No outputs. */ 11054 : "q" (iInt), "X" (sizeof(unsigned char) + 1), "i" (42) 11055 : /* No clobbers. */ 11056 : top); 11057 @} 11058 @end example 11059 11060 With no modifiers, this is what the output from the operands would be 11061 for the @samp{att} and @samp{intel} dialects of assembler: 11062 11063 @multitable {Operand} {$.L2} {OFFSET FLAT:.L2} 11064 @headitem Operand @tab @samp{att} @tab @samp{intel} 11065 @item @code{%0} 11066 @tab @code{%eax} 11067 @tab @code{eax} 11068 @item @code{%1} 11069 @tab @code{$2} 11070 @tab @code{2} 11071 @item @code{%3} 11072 @tab @code{$.L3} 11073 @tab @code{OFFSET FLAT:.L3} 11074 @item @code{%4} 11075 @tab @code{$8} 11076 @tab @code{8} 11077 @item @code{%5} 11078 @tab @code{%xmm0} 11079 @tab @code{xmm0} 11080 @item @code{%7} 11081 @tab @code{$0} 11082 @tab @code{0} 11083 @end multitable 11084 11085 The table below shows the list of supported modifiers and their effects. 11086 11087 @multitable {Modifier} {Print the opcode suffix for the size of th} {Operand} {@samp{att}} {@samp{intel}} 11088 @headitem Modifier @tab Description @tab Operand @tab @samp{att} @tab @samp{intel} 11089 @item @code{A} 11090 @tab Print an absolute memory reference. 11091 @tab @code{%A0} 11092 @tab @code{*%rax} 11093 @tab @code{rax} 11094 @item @code{b} 11095 @tab Print the QImode name of the register. 11096 @tab @code{%b0} 11097 @tab @code{%al} 11098 @tab @code{al} 11099 @item @code{B} 11100 @tab print the opcode suffix of b. 11101 @tab @code{%B0} 11102 @tab @code{b} 11103 @tab 11104 @item @code{c} 11105 @tab Require a constant operand and print the constant expression with no punctuation. 11106 @tab @code{%c1} 11107 @tab @code{2} 11108 @tab @code{2} 11109 @item @code{d} 11110 @tab print duplicated register operand for AVX instruction. 11111 @tab @code{%d5} 11112 @tab @code{%xmm0, %xmm0} 11113 @tab @code{xmm0, xmm0} 11114 @item @code{E} 11115 @tab Print the address in Double Integer (DImode) mode (8 bytes) when the target is 64-bit. 11116 Otherwise mode is unspecified (VOIDmode). 11117 @tab @code{%E1} 11118 @tab @code{%(rax)} 11119 @tab @code{[rax]} 11120 @item @code{g} 11121 @tab Print the V16SFmode name of the register. 11122 @tab @code{%g0} 11123 @tab @code{%zmm0} 11124 @tab @code{zmm0} 11125 @item @code{h} 11126 @tab Print the QImode name for a ``high'' register. 11127 @tab @code{%h0} 11128 @tab @code{%ah} 11129 @tab @code{ah} 11130 @item @code{H} 11131 @tab Add 8 bytes to an offsettable memory reference. Useful when accessing the 11132 high 8 bytes of SSE values. For a memref in (%rax), it generates 11133 @tab @code{%H0} 11134 @tab @code{8(%rax)} 11135 @tab @code{8[rax]} 11136 @item @code{k} 11137 @tab Print the SImode name of the register. 11138 @tab @code{%k0} 11139 @tab @code{%eax} 11140 @tab @code{eax} 11141 @item @code{l} 11142 @tab Print the label name with no punctuation. 11143 @tab @code{%l3} 11144 @tab @code{.L3} 11145 @tab @code{.L3} 11146 @item @code{L} 11147 @tab print the opcode suffix of l. 11148 @tab @code{%L0} 11149 @tab @code{l} 11150 @tab 11151 @item @code{N} 11152 @tab print maskz. 11153 @tab @code{%N7} 11154 @tab @code{@{z@}} 11155 @tab @code{@{z@}} 11156 @item @code{p} 11157 @tab Print raw symbol name (without syntax-specific prefixes). 11158 @tab @code{%p2} 11159 @tab @code{42} 11160 @tab @code{42} 11161 @item @code{P} 11162 @tab If used for a function, print the PLT suffix and generate PIC code. 11163 For example, emit @code{foo@@PLT} instead of 'foo' for the function 11164 foo(). If used for a constant, drop all syntax-specific prefixes and 11165 issue the bare constant. See @code{p} above. 11166 @item @code{q} 11167 @tab Print the DImode name of the register. 11168 @tab @code{%q0} 11169 @tab @code{%rax} 11170 @tab @code{rax} 11171 @item @code{Q} 11172 @tab print the opcode suffix of q. 11173 @tab @code{%Q0} 11174 @tab @code{q} 11175 @tab 11176 @item @code{R} 11177 @tab print embedded rounding and sae. 11178 @tab @code{%R4} 11179 @tab @code{@{rn-sae@}, } 11180 @tab @code{, @{rn-sae@}} 11181 @item @code{r} 11182 @tab print only sae. 11183 @tab @code{%r4} 11184 @tab @code{@{sae@}, } 11185 @tab @code{, @{sae@}} 11186 @item @code{s} 11187 @tab print a shift double count, followed by the assemblers argument 11188 delimiterprint the opcode suffix of s. 11189 @tab @code{%s1} 11190 @tab @code{$2, } 11191 @tab @code{2, } 11192 @item @code{S} 11193 @tab print the opcode suffix of s. 11194 @tab @code{%S0} 11195 @tab @code{s} 11196 @tab 11197 @item @code{t} 11198 @tab print the V8SFmode name of the register. 11199 @tab @code{%t5} 11200 @tab @code{%ymm0} 11201 @tab @code{ymm0} 11202 @item @code{T} 11203 @tab print the opcode suffix of t. 11204 @tab @code{%T0} 11205 @tab @code{t} 11206 @tab 11207 @item @code{V} 11208 @tab print naked full integer register name without %. 11209 @tab @code{%V0} 11210 @tab @code{eax} 11211 @tab @code{eax} 11212 @item @code{w} 11213 @tab Print the HImode name of the register. 11214 @tab @code{%w0} 11215 @tab @code{%ax} 11216 @tab @code{ax} 11217 @item @code{W} 11218 @tab print the opcode suffix of w. 11219 @tab @code{%W0} 11220 @tab @code{w} 11221 @tab 11222 @item @code{x} 11223 @tab print the V4SFmode name of the register. 11224 @tab @code{%x5} 11225 @tab @code{%xmm0} 11226 @tab @code{xmm0} 11227 @item @code{y} 11228 @tab print "st(0)" instead of "st" as a register. 11229 @tab @code{%y6} 11230 @tab @code{%st(0)} 11231 @tab @code{st(0)} 11232 @item @code{z} 11233 @tab Print the opcode suffix for the size of the current integer operand (one of @code{b}/@code{w}/@code{l}/@code{q}). 11234 @tab @code{%z0} 11235 @tab @code{l} 11236 @tab 11237 @item @code{Z} 11238 @tab Like @code{z}, with special suffixes for x87 instructions. 11239 @end multitable 11240 11241 11242 @anchor{x86floatingpointasmoperands} 11243 @subsubsection x86 Floating-Point @code{asm} Operands 11244 11245 On x86 targets, there are several rules on the usage of stack-like registers 11246 in the operands of an @code{asm}. These rules apply only to the operands 11247 that are stack-like registers: 11248 11249 @enumerate 11250 @item 11251 Given a set of input registers that die in an @code{asm}, it is 11252 necessary to know which are implicitly popped by the @code{asm}, and 11253 which must be explicitly popped by GCC@. 11254 11255 An input register that is implicitly popped by the @code{asm} must be 11256 explicitly clobbered, unless it is constrained to match an 11257 output operand. 11258 11259 @item 11260 For any input register that is implicitly popped by an @code{asm}, it is 11261 necessary to know how to adjust the stack to compensate for the pop. 11262 If any non-popped input is closer to the top of the reg-stack than 11263 the implicitly popped register, it would not be possible to know what the 11264 stack looked like---it's not clear how the rest of the stack ``slides 11265 up''. 11266 11267 All implicitly popped input registers must be closer to the top of 11268 the reg-stack than any input that is not implicitly popped. 11269 11270 It is possible that if an input dies in an @code{asm}, the compiler might 11271 use the input register for an output reload. Consider this example: 11272 11273 @smallexample 11274 asm ("foo" : "=t" (a) : "f" (b)); 11275 @end smallexample 11276 11277 @noindent 11278 This code says that input @code{b} is not popped by the @code{asm}, and that 11279 the @code{asm} pushes a result onto the reg-stack, i.e., the stack is one 11280 deeper after the @code{asm} than it was before. But, it is possible that 11281 reload may think that it can use the same register for both the input and 11282 the output. 11283 11284 To prevent this from happening, 11285 if any input operand uses the @samp{f} constraint, all output register 11286 constraints must use the @samp{&} early-clobber modifier. 11287 11288 The example above is correctly written as: 11289 11290 @smallexample 11291 asm ("foo" : "=&t" (a) : "f" (b)); 11292 @end smallexample 11293 11294 @item 11295 Some operands need to be in particular places on the stack. All 11296 output operands fall in this category---GCC has no other way to 11297 know which registers the outputs appear in unless you indicate 11298 this in the constraints. 11299 11300 Output operands must specifically indicate which register an output 11301 appears in after an @code{asm}. @samp{=f} is not allowed: the operand 11302 constraints must select a class with a single register. 11303 11304 @item 11305 Output operands may not be ``inserted'' between existing stack registers. 11306 Since no 387 opcode uses a read/write operand, all output operands 11307 are dead before the @code{asm}, and are pushed by the @code{asm}. 11308 It makes no sense to push anywhere but the top of the reg-stack. 11309 11310 Output operands must start at the top of the reg-stack: output 11311 operands may not ``skip'' a register. 11312 11313 @item 11314 Some @code{asm} statements may need extra stack space for internal 11315 calculations. This can be guaranteed by clobbering stack registers 11316 unrelated to the inputs and outputs. 11317 11318 @end enumerate 11319 11320 This @code{asm} 11321 takes one input, which is internally popped, and produces two outputs. 11322 11323 @smallexample 11324 asm ("fsincos" : "=t" (cos), "=u" (sin) : "0" (inp)); 11325 @end smallexample 11326 11327 @noindent 11328 This @code{asm} takes two inputs, which are popped by the @code{fyl2xp1} opcode, 11329 and replaces them with one output. The @code{st(1)} clobber is necessary 11330 for the compiler to know that @code{fyl2xp1} pops both inputs. 11331 11332 @smallexample 11333 asm ("fyl2xp1" : "=t" (result) : "0" (x), "u" (y) : "st(1)"); 11334 @end smallexample 11335 11336 @anchor{msp430Operandmodifiers} 11337 @subsubsection MSP430 Operand Modifiers 11338 11339 The list below describes the supported modifiers and their effects for MSP430. 11340 11341 @multitable @columnfractions .10 .90 11342 @headitem Modifier @tab Description 11343 @item @code{A} @tab Select low 16-bits of the constant/register/memory operand. 11344 @item @code{B} @tab Select high 16-bits of the constant/register/memory 11345 operand. 11346 @item @code{C} @tab Select bits 32-47 of the constant/register/memory operand. 11347 @item @code{D} @tab Select bits 48-63 of the constant/register/memory operand. 11348 @item @code{H} @tab Equivalent to @code{B} (for backwards compatibility). 11349 @item @code{I} @tab Print the inverse (logical @code{NOT}) of the constant 11350 value. 11351 @item @code{J} @tab Print an integer without a @code{#} prefix. 11352 @item @code{L} @tab Equivalent to @code{A} (for backwards compatibility). 11353 @item @code{O} @tab Offset of the current frame from the top of the stack. 11354 @item @code{Q} @tab Use the @code{A} instruction postfix. 11355 @item @code{R} @tab Inverse of condition code, for unsigned comparisons. 11356 @item @code{W} @tab Subtract 16 from the constant value. 11357 @item @code{X} @tab Use the @code{X} instruction postfix. 11358 @item @code{Y} @tab Subtract 4 from the constant value. 11359 @item @code{Z} @tab Subtract 1 from the constant value. 11360 @item @code{b} @tab Append @code{.B}, @code{.W} or @code{.A} to the 11361 instruction, depending on the mode. 11362 @item @code{d} @tab Offset 1 byte of a memory reference or constant value. 11363 @item @code{e} @tab Offset 3 bytes of a memory reference or constant value. 11364 @item @code{f} @tab Offset 5 bytes of a memory reference or constant value. 11365 @item @code{g} @tab Offset 7 bytes of a memory reference or constant value. 11366 @item @code{p} @tab Print the value of 2, raised to the power of the given 11367 constant. Used to select the specified bit position. 11368 @item @code{r} @tab Inverse of condition code, for signed comparisons. 11369 @item @code{x} @tab Equivialent to @code{X}, but only for pointers. 11370 @end multitable 11371 11372 @lowersections 11373 @include md.texi 11374 @raisesections 11375 11376 @node Asm Labels 11377 @subsection Controlling Names Used in Assembler Code 11378 @cindex assembler names for identifiers 11379 @cindex names used in assembler code 11380 @cindex identifiers, names in assembler code 11381 11382 You can specify the name to be used in the assembler code for a C 11383 function or variable by writing the @code{asm} (or @code{__asm__}) 11384 keyword after the declarator. 11385 It is up to you to make sure that the assembler names you choose do not 11386 conflict with any other assembler symbols, or reference registers. 11387 11388 @subsubheading Assembler names for data: 11389 11390 This sample shows how to specify the assembler name for data: 11391 11392 @smallexample 11393 int foo asm ("myfoo") = 2; 11394 @end smallexample 11395 11396 @noindent 11397 This specifies that the name to be used for the variable @code{foo} in 11398 the assembler code should be @samp{myfoo} rather than the usual 11399 @samp{_foo}. 11400 11401 On systems where an underscore is normally prepended to the name of a C 11402 variable, this feature allows you to define names for the 11403 linker that do not start with an underscore. 11404 11405 GCC does not support using this feature with a non-static local variable 11406 since such variables do not have assembler names. If you are 11407 trying to put the variable in a particular register, see 11408 @ref{Explicit Register Variables}. 11409 11410 @subsubheading Assembler names for functions: 11411 11412 To specify the assembler name for functions, write a declaration for the 11413 function before its definition and put @code{asm} there, like this: 11414 11415 @smallexample 11416 int func (int x, int y) asm ("MYFUNC"); 11417 11418 int func (int x, int y) 11419 @{ 11420 /* @r{@dots{}} */ 11421 @end smallexample 11422 11423 @noindent 11424 This specifies that the name to be used for the function @code{func} in 11425 the assembler code should be @code{MYFUNC}. 11426 11427 @node Explicit Register Variables 11428 @subsection Variables in Specified Registers 11429 @anchor{Explicit Reg Vars} 11430 @cindex explicit register variables 11431 @cindex variables in specified registers 11432 @cindex specified registers 11433 11434 GNU C allows you to associate specific hardware registers with C 11435 variables. In almost all cases, allowing the compiler to assign 11436 registers produces the best code. However under certain unusual 11437 circumstances, more precise control over the variable storage is 11438 required. 11439 11440 Both global and local variables can be associated with a register. The 11441 consequences of performing this association are very different between 11442 the two, as explained in the sections below. 11443 11444 @menu 11445 * Global Register Variables:: Variables declared at global scope. 11446 * Local Register Variables:: Variables declared within a function. 11447 @end menu 11448 11449 @node Global Register Variables 11450 @subsubsection Defining Global Register Variables 11451 @anchor{Global Reg Vars} 11452 @cindex global register variables 11453 @cindex registers, global variables in 11454 @cindex registers, global allocation 11455 11456 You can define a global register variable and associate it with a specified 11457 register like this: 11458 11459 @smallexample 11460 register int *foo asm ("r12"); 11461 @end smallexample 11462 11463 @noindent 11464 Here @code{r12} is the name of the register that should be used. Note that 11465 this is the same syntax used for defining local register variables, but for 11466 a global variable the declaration appears outside a function. The 11467 @code{register} keyword is required, and cannot be combined with 11468 @code{static}. The register name must be a valid register name for the 11469 target platform. 11470 11471 Do not use type qualifiers such as @code{const} and @code{volatile}, as 11472 the outcome may be contrary to expectations. In particular, using the 11473 @code{volatile} qualifier does not fully prevent the compiler from 11474 optimizing accesses to the register. 11475 11476 Registers are a scarce resource on most systems and allowing the 11477 compiler to manage their usage usually results in the best code. However, 11478 under special circumstances it can make sense to reserve some globally. 11479 For example this may be useful in programs such as programming language 11480 interpreters that have a couple of global variables that are accessed 11481 very often. 11482 11483 After defining a global register variable, for the current compilation 11484 unit: 11485 11486 @itemize @bullet 11487 @item If the register is a call-saved register, call ABI is affected: 11488 the register will not be restored in function epilogue sequences after 11489 the variable has been assigned. Therefore, functions cannot safely 11490 return to callers that assume standard ABI. 11491 @item Conversely, if the register is a call-clobbered register, making 11492 calls to functions that use standard ABI may lose contents of the variable. 11493 Such calls may be created by the compiler even if none are evident in 11494 the original program, for example when libgcc functions are used to 11495 make up for unavailable instructions. 11496 @item Accesses to the variable may be optimized as usual and the register 11497 remains available for allocation and use in any computations, provided that 11498 observable values of the variable are not affected. 11499 @item If the variable is referenced in inline assembly, the type of access 11500 must be provided to the compiler via constraints (@pxref{Constraints}). 11501 Accesses from basic asms are not supported. 11502 @end itemize 11503 11504 Note that these points @emph{only} apply to code that is compiled with the 11505 definition. The behavior of code that is merely linked in (for example 11506 code from libraries) is not affected. 11507 11508 If you want to recompile source files that do not actually use your global 11509 register variable so they do not use the specified register for any other 11510 purpose, you need not actually add the global register declaration to 11511 their source code. It suffices to specify the compiler option 11512 @option{-ffixed-@var{reg}} (@pxref{Code Gen Options}) to reserve the 11513 register. 11514 11515 @subsubheading Declaring the variable 11516 11517 Global register variables cannot have initial values, because an 11518 executable file has no means to supply initial contents for a register. 11519 11520 When selecting a register, choose one that is normally saved and 11521 restored by function calls on your machine. This ensures that code 11522 which is unaware of this reservation (such as library routines) will 11523 restore it before returning. 11524 11525 On machines with register windows, be sure to choose a global 11526 register that is not affected magically by the function call mechanism. 11527 11528 @subsubheading Using the variable 11529 11530 @cindex @code{qsort}, and global register variables 11531 When calling routines that are not aware of the reservation, be 11532 cautious if those routines call back into code which uses them. As an 11533 example, if you call the system library version of @code{qsort}, it may 11534 clobber your registers during execution, but (if you have selected 11535 appropriate registers) it will restore them before returning. However 11536 it will @emph{not} restore them before calling @code{qsort}'s comparison 11537 function. As a result, global values will not reliably be available to 11538 the comparison function unless the @code{qsort} function itself is rebuilt. 11539 11540 Similarly, it is not safe to access the global register variables from signal 11541 handlers or from more than one thread of control. Unless you recompile 11542 them specially for the task at hand, the system library routines may 11543 temporarily use the register for other things. Furthermore, since the register 11544 is not reserved exclusively for the variable, accessing it from handlers of 11545 asynchronous signals may observe unrelated temporary values residing in the 11546 register. 11547 11548 @cindex register variable after @code{longjmp} 11549 @cindex global register after @code{longjmp} 11550 @cindex value after @code{longjmp} 11551 @findex longjmp 11552 @findex setjmp 11553 On most machines, @code{longjmp} restores to each global register 11554 variable the value it had at the time of the @code{setjmp}. On some 11555 machines, however, @code{longjmp} does not change the value of global 11556 register variables. To be portable, the function that called @code{setjmp} 11557 should make other arrangements to save the values of the global register 11558 variables, and to restore them in a @code{longjmp}. This way, the same 11559 thing happens regardless of what @code{longjmp} does. 11560 11561 @node Local Register Variables 11562 @subsubsection Specifying Registers for Local Variables 11563 @anchor{Local Reg Vars} 11564 @cindex local variables, specifying registers 11565 @cindex specifying registers for local variables 11566 @cindex registers for local variables 11567 11568 You can define a local register variable and associate it with a specified 11569 register like this: 11570 11571 @smallexample 11572 register int *foo asm ("r12"); 11573 @end smallexample 11574 11575 @noindent 11576 Here @code{r12} is the name of the register that should be used. Note 11577 that this is the same syntax used for defining global register variables, 11578 but for a local variable the declaration appears within a function. The 11579 @code{register} keyword is required, and cannot be combined with 11580 @code{static}. The register name must be a valid register name for the 11581 target platform. 11582 11583 Do not use type qualifiers such as @code{const} and @code{volatile}, as 11584 the outcome may be contrary to expectations. In particular, when the 11585 @code{const} qualifier is used, the compiler may substitute the 11586 variable with its initializer in @code{asm} statements, which may cause 11587 the corresponding operand to appear in a different register. 11588 11589 As with global register variables, it is recommended that you choose 11590 a register that is normally saved and restored by function calls on your 11591 machine, so that calls to library routines will not clobber it. 11592 11593 The only supported use for this feature is to specify registers 11594 for input and output operands when calling Extended @code{asm} 11595 (@pxref{Extended Asm}). This may be necessary if the constraints for a 11596 particular machine don't provide sufficient control to select the desired 11597 register. To force an operand into a register, create a local variable 11598 and specify the register name after the variable's declaration. Then use 11599 the local variable for the @code{asm} operand and specify any constraint 11600 letter that matches the register: 11601 11602 @smallexample 11603 register int *p1 asm ("r0") = @dots{}; 11604 register int *p2 asm ("r1") = @dots{}; 11605 register int *result asm ("r0"); 11606 asm ("sysint" : "=r" (result) : "0" (p1), "r" (p2)); 11607 @end smallexample 11608 11609 @emph{Warning:} In the above example, be aware that a register (for example 11610 @code{r0}) can be call-clobbered by subsequent code, including function 11611 calls and library calls for arithmetic operators on other variables (for 11612 example the initialization of @code{p2}). In this case, use temporary 11613 variables for expressions between the register assignments: 11614 11615 @smallexample 11616 int t1 = @dots{}; 11617 register int *p1 asm ("r0") = @dots{}; 11618 register int *p2 asm ("r1") = t1; 11619 register int *result asm ("r0"); 11620 asm ("sysint" : "=r" (result) : "0" (p1), "r" (p2)); 11621 @end smallexample 11622 11623 Defining a register variable does not reserve the register. Other than 11624 when invoking the Extended @code{asm}, the contents of the specified 11625 register are not guaranteed. For this reason, the following uses 11626 are explicitly @emph{not} supported. If they appear to work, it is only 11627 happenstance, and may stop working as intended due to (seemingly) 11628 unrelated changes in surrounding code, or even minor changes in the 11629 optimization of a future version of gcc: 11630 11631 @itemize @bullet 11632 @item Passing parameters to or from Basic @code{asm} 11633 @item Passing parameters to or from Extended @code{asm} without using input 11634 or output operands. 11635 @item Passing parameters to or from routines written in assembler (or 11636 other languages) using non-standard calling conventions. 11637 @end itemize 11638 11639 Some developers use Local Register Variables in an attempt to improve 11640 gcc's allocation of registers, especially in large functions. In this 11641 case the register name is essentially a hint to the register allocator. 11642 While in some instances this can generate better code, improvements are 11643 subject to the whims of the allocator/optimizers. Since there are no 11644 guarantees that your improvements won't be lost, this usage of Local 11645 Register Variables is discouraged. 11646 11647 On the MIPS platform, there is related use for local register variables 11648 with slightly different characteristics (@pxref{MIPS Coprocessors,, 11649 Defining coprocessor specifics for MIPS targets, gccint, 11650 GNU Compiler Collection (GCC) Internals}). 11651 11652 @node Size of an asm 11653 @subsection Size of an @code{asm} 11654 11655 Some targets require that GCC track the size of each instruction used 11656 in order to generate correct code. Because the final length of the 11657 code produced by an @code{asm} statement is only known by the 11658 assembler, GCC must make an estimate as to how big it will be. It 11659 does this by counting the number of instructions in the pattern of the 11660 @code{asm} and multiplying that by the length of the longest 11661 instruction supported by that processor. (When working out the number 11662 of instructions, it assumes that any occurrence of a newline or of 11663 whatever statement separator character is supported by the assembler --- 11664 typically @samp{;} --- indicates the end of an instruction.) 11665 11666 Normally, GCC's estimate is adequate to ensure that correct 11667 code is generated, but it is possible to confuse the compiler if you use 11668 pseudo instructions or assembler macros that expand into multiple real 11669 instructions, or if you use assembler directives that expand to more 11670 space in the object file than is needed for a single instruction. 11671 If this happens then the assembler may produce a diagnostic saying that 11672 a label is unreachable. 11673 11674 @cindex @code{asm inline} 11675 This size is also used for inlining decisions. If you use @code{asm inline} 11676 instead of just @code{asm}, then for inlining purposes the size of the asm 11677 is taken as the minimum size, ignoring how many instructions GCC thinks it is. 11678 11679 @node Alternate Keywords 11680 @section Alternate Keywords 11681 @cindex alternate keywords 11682 @cindex keywords, alternate 11683 11684 @option{-ansi} and the various @option{-std} options disable certain 11685 keywords. This causes trouble when you want to use GNU C extensions, or 11686 a general-purpose header file that should be usable by all programs, 11687 including ISO C programs. The keywords @code{asm}, @code{typeof} and 11688 @code{inline} are not available in programs compiled with 11689 @option{-ansi} or @option{-std} (although @code{inline} can be used in a 11690 program compiled with @option{-std=c99} or a later standard). The 11691 ISO C99 keyword 11692 @code{restrict} is only available when @option{-std=gnu99} (which will 11693 eventually be the default) or @option{-std=c99} (or the equivalent 11694 @option{-std=iso9899:1999}), or an option for a later standard 11695 version, is used. 11696 11697 The way to solve these problems is to put @samp{__} at the beginning and 11698 end of each problematical keyword. For example, use @code{__asm__} 11699 instead of @code{asm}, and @code{__inline__} instead of @code{inline}. 11700 11701 Other C compilers won't accept these alternative keywords; if you want to 11702 compile with another compiler, you can define the alternate keywords as 11703 macros to replace them with the customary keywords. It looks like this: 11704 11705 @smallexample 11706 #ifndef __GNUC__ 11707 #define __asm__ asm 11708 #endif 11709 @end smallexample 11710 11711 @findex __extension__ 11712 @opindex pedantic 11713 @option{-pedantic} and other options cause warnings for many GNU C extensions. 11714 You can 11715 prevent such warnings within one expression by writing 11716 @code{__extension__} before the expression. @code{__extension__} has no 11717 effect aside from this. 11718 11719 @node Incomplete Enums 11720 @section Incomplete @code{enum} Types 11721 11722 You can define an @code{enum} tag without specifying its possible values. 11723 This results in an incomplete type, much like what you get if you write 11724 @code{struct foo} without describing the elements. A later declaration 11725 that does specify the possible values completes the type. 11726 11727 You cannot allocate variables or storage using the type while it is 11728 incomplete. However, you can work with pointers to that type. 11729 11730 This extension may not be very useful, but it makes the handling of 11731 @code{enum} more consistent with the way @code{struct} and @code{union} 11732 are handled. 11733 11734 This extension is not supported by GNU C++. 11735 11736 @node Function Names 11737 @section Function Names as Strings 11738 @cindex @code{__func__} identifier 11739 @cindex @code{__FUNCTION__} identifier 11740 @cindex @code{__PRETTY_FUNCTION__} identifier 11741 11742 GCC provides three magic constants that hold the name of the current 11743 function as a string. In C++11 and later modes, all three are treated 11744 as constant expressions and can be used in @code{constexpr} constexts. 11745 The first of these constants is @code{__func__}, which is part of 11746 the C99 standard: 11747 11748 The identifier @code{__func__} is implicitly declared by the translator 11749 as if, immediately following the opening brace of each function 11750 definition, the declaration 11751 11752 @smallexample 11753 static const char __func__[] = "function-name"; 11754 @end smallexample 11755 11756 @noindent 11757 appeared, where function-name is the name of the lexically-enclosing 11758 function. This name is the unadorned name of the function. As an 11759 extension, at file (or, in C++, namespace scope), @code{__func__} 11760 evaluates to the empty string. 11761 11762 @code{__FUNCTION__} is another name for @code{__func__}, provided for 11763 backward compatibility with old versions of GCC. 11764 11765 In C, @code{__PRETTY_FUNCTION__} is yet another name for 11766 @code{__func__}, except that at file scope (or, in C++, namespace scope), 11767 it evaluates to the string @code{"top level"}. In addition, in C++, 11768 @code{__PRETTY_FUNCTION__} contains the signature of the function as 11769 well as its bare name. For example, this program: 11770 11771 @smallexample 11772 extern "C" int printf (const char *, ...); 11773 11774 class a @{ 11775 public: 11776 void sub (int i) 11777 @{ 11778 printf ("__FUNCTION__ = %s\n", __FUNCTION__); 11779 printf ("__PRETTY_FUNCTION__ = %s\n", __PRETTY_FUNCTION__); 11780 @} 11781 @}; 11782 11783 int 11784 main (void) 11785 @{ 11786 a ax; 11787 ax.sub (0); 11788 return 0; 11789 @} 11790 @end smallexample 11791 11792 @noindent 11793 gives this output: 11794 11795 @smallexample 11796 __FUNCTION__ = sub 11797 __PRETTY_FUNCTION__ = void a::sub(int) 11798 @end smallexample 11799 11800 These identifiers are variables, not preprocessor macros, and may not 11801 be used to initialize @code{char} arrays or be concatenated with string 11802 literals. 11803 11804 @node Return Address 11805 @section Getting the Return or Frame Address of a Function 11806 11807 These functions may be used to get information about the callers of a 11808 function. 11809 11810 @deftypefn {Built-in Function} {void *} __builtin_return_address (unsigned int @var{level}) 11811 This function returns the return address of the current function, or of 11812 one of its callers. The @var{level} argument is number of frames to 11813 scan up the call stack. A value of @code{0} yields the return address 11814 of the current function, a value of @code{1} yields the return address 11815 of the caller of the current function, and so forth. When inlining 11816 the expected behavior is that the function returns the address of 11817 the function that is returned to. To work around this behavior use 11818 the @code{noinline} function attribute. 11819 11820 The @var{level} argument must be a constant integer. 11821 11822 On some machines it may be impossible to determine the return address of 11823 any function other than the current one; in such cases, or when the top 11824 of the stack has been reached, this function returns an unspecified 11825 value. In addition, @code{__builtin_frame_address} may be used 11826 to determine if the top of the stack has been reached. 11827 11828 Additional post-processing of the returned value may be needed, see 11829 @code{__builtin_extract_return_addr}. 11830 11831 The stored representation of the return address in memory may be different 11832 from the address returned by @code{__builtin_return_address}. For example, 11833 on AArch64 the stored address may be mangled with return address signing 11834 whereas the address returned by @code{__builtin_return_address} is not. 11835 11836 Calling this function with a nonzero argument can have unpredictable 11837 effects, including crashing the calling program. As a result, calls 11838 that are considered unsafe are diagnosed when the @option{-Wframe-address} 11839 option is in effect. Such calls should only be made in debugging 11840 situations. 11841 11842 On targets where code addresses are representable as @code{void *}, 11843 @smallexample 11844 void *addr = __builtin_extract_return_addr (__builtin_return_address (0)); 11845 @end smallexample 11846 gives the code address where the current function would return. For example, 11847 such an address may be used with @code{dladdr} or other interfaces that work 11848 with code addresses. 11849 @end deftypefn 11850 11851 @deftypefn {Built-in Function} {void *} __builtin_extract_return_addr (void *@var{addr}) 11852 The address as returned by @code{__builtin_return_address} may have to be fed 11853 through this function to get the actual encoded address. For example, on the 11854 31-bit S/390 platform the highest bit has to be masked out, or on SPARC 11855 platforms an offset has to be added for the true next instruction to be 11856 executed. 11857 11858 If no fixup is needed, this function simply passes through @var{addr}. 11859 @end deftypefn 11860 11861 @deftypefn {Built-in Function} {void *} __builtin_frob_return_addr (void *@var{addr}) 11862 This function does the reverse of @code{__builtin_extract_return_addr}. 11863 @end deftypefn 11864 11865 @deftypefn {Built-in Function} {void *} __builtin_frame_address (unsigned int @var{level}) 11866 This function is similar to @code{__builtin_return_address}, but it 11867 returns the address of the function frame rather than the return address 11868 of the function. Calling @code{__builtin_frame_address} with a value of 11869 @code{0} yields the frame address of the current function, a value of 11870 @code{1} yields the frame address of the caller of the current function, 11871 and so forth. 11872 11873 The frame is the area on the stack that holds local variables and saved 11874 registers. The frame address is normally the address of the first word 11875 pushed on to the stack by the function. However, the exact definition 11876 depends upon the processor and the calling convention. If the processor 11877 has a dedicated frame pointer register, and the function has a frame, 11878 then @code{__builtin_frame_address} returns the value of the frame 11879 pointer register. 11880 11881 On some machines it may be impossible to determine the frame address of 11882 any function other than the current one; in such cases, or when the top 11883 of the stack has been reached, this function returns @code{0} if 11884 the first frame pointer is properly initialized by the startup code. 11885 11886 Calling this function with a nonzero argument can have unpredictable 11887 effects, including crashing the calling program. As a result, calls 11888 that are considered unsafe are diagnosed when the @option{-Wframe-address} 11889 option is in effect. Such calls should only be made in debugging 11890 situations. 11891 @end deftypefn 11892 11893 @node Vector Extensions 11894 @section Using Vector Instructions through Built-in Functions 11895 11896 On some targets, the instruction set contains SIMD vector instructions which 11897 operate on multiple values contained in one large register at the same time. 11898 For example, on the x86 the MMX, 3DNow!@: and SSE extensions can be used 11899 this way. 11900 11901 The first step in using these extensions is to provide the necessary data 11902 types. This should be done using an appropriate @code{typedef}: 11903 11904 @smallexample 11905 typedef int v4si __attribute__ ((vector_size (16))); 11906 @end smallexample 11907 11908 @noindent 11909 The @code{int} type specifies the @dfn{base type}, while the attribute specifies 11910 the vector size for the variable, measured in bytes. For example, the 11911 declaration above causes the compiler to set the mode for the @code{v4si} 11912 type to be 16 bytes wide and divided into @code{int} sized units. For 11913 a 32-bit @code{int} this means a vector of 4 units of 4 bytes, and the 11914 corresponding mode of @code{foo} is @acronym{V4SI}. 11915 11916 The @code{vector_size} attribute is only applicable to integral and 11917 floating scalars, although arrays, pointers, and function return values 11918 are allowed in conjunction with this construct. Only sizes that are 11919 positive power-of-two multiples of the base type size are currently allowed. 11920 11921 All the basic integer types can be used as base types, both as signed 11922 and as unsigned: @code{char}, @code{short}, @code{int}, @code{long}, 11923 @code{long long}. In addition, @code{float} and @code{double} can be 11924 used to build floating-point vector types. 11925 11926 Specifying a combination that is not valid for the current architecture 11927 causes GCC to synthesize the instructions using a narrower mode. 11928 For example, if you specify a variable of type @code{V4SI} and your 11929 architecture does not allow for this specific SIMD type, GCC 11930 produces code that uses 4 @code{SIs}. 11931 11932 The types defined in this manner can be used with a subset of normal C 11933 operations. Currently, GCC allows using the following operators 11934 on these types: @code{+, -, *, /, unary minus, ^, |, &, ~, %}@. 11935 11936 The operations behave like C++ @code{valarrays}. Addition is defined as 11937 the addition of the corresponding elements of the operands. For 11938 example, in the code below, each of the 4 elements in @var{a} is 11939 added to the corresponding 4 elements in @var{b} and the resulting 11940 vector is stored in @var{c}. 11941 11942 @smallexample 11943 typedef int v4si __attribute__ ((vector_size (16))); 11944 11945 v4si a, b, c; 11946 11947 c = a + b; 11948 @end smallexample 11949 11950 Subtraction, multiplication, division, and the logical operations 11951 operate in a similar manner. Likewise, the result of using the unary 11952 minus or complement operators on a vector type is a vector whose 11953 elements are the negative or complemented values of the corresponding 11954 elements in the operand. 11955 11956 It is possible to use shifting operators @code{<<}, @code{>>} on 11957 integer-type vectors. The operation is defined as following: @code{@{a0, 11958 a1, @dots{}, an@} >> @{b0, b1, @dots{}, bn@} == @{a0 >> b0, a1 >> b1, 11959 @dots{}, an >> bn@}}@. Vector operands must have the same number of 11960 elements. 11961 11962 For convenience, it is allowed to use a binary vector operation 11963 where one operand is a scalar. In that case the compiler transforms 11964 the scalar operand into a vector where each element is the scalar from 11965 the operation. The transformation happens only if the scalar could be 11966 safely converted to the vector-element type. 11967 Consider the following code. 11968 11969 @smallexample 11970 typedef int v4si __attribute__ ((vector_size (16))); 11971 11972 v4si a, b, c; 11973 long l; 11974 11975 a = b + 1; /* a = b + @{1,1,1,1@}; */ 11976 a = 2 * b; /* a = @{2,2,2,2@} * b; */ 11977 11978 a = l + a; /* Error, cannot convert long to int. */ 11979 @end smallexample 11980 11981 Vectors can be subscripted as if the vector were an array with 11982 the same number of elements and base type. Out of bound accesses 11983 invoke undefined behavior at run time. Warnings for out of bound 11984 accesses for vector subscription can be enabled with 11985 @option{-Warray-bounds}. 11986 11987 Vector comparison is supported with standard comparison 11988 operators: @code{==, !=, <, <=, >, >=}. Comparison operands can be 11989 vector expressions of integer-type or real-type. Comparison between 11990 integer-type vectors and real-type vectors are not supported. The 11991 result of the comparison is a vector of the same width and number of 11992 elements as the comparison operands with a signed integral element 11993 type. 11994 11995 Vectors are compared element-wise producing 0 when comparison is false 11996 and -1 (constant of the appropriate type where all bits are set) 11997 otherwise. Consider the following example. 11998 11999 @smallexample 12000 typedef int v4si __attribute__ ((vector_size (16))); 12001 12002 v4si a = @{1,2,3,4@}; 12003 v4si b = @{3,2,1,4@}; 12004 v4si c; 12005 12006 c = a > b; /* The result would be @{0, 0,-1, 0@} */ 12007 c = a == b; /* The result would be @{0,-1, 0,-1@} */ 12008 @end smallexample 12009 12010 In C++, the ternary operator @code{?:} is available. @code{a?b:c}, where 12011 @code{b} and @code{c} are vectors of the same type and @code{a} is an 12012 integer vector with the same number of elements of the same size as @code{b} 12013 and @code{c}, computes all three arguments and creates a vector 12014 @code{@{a[0]?b[0]:c[0], a[1]?b[1]:c[1], @dots{}@}}. Note that unlike in 12015 OpenCL, @code{a} is thus interpreted as @code{a != 0} and not @code{a < 0}. 12016 As in the case of binary operations, this syntax is also accepted when 12017 one of @code{b} or @code{c} is a scalar that is then transformed into a 12018 vector. If both @code{b} and @code{c} are scalars and the type of 12019 @code{true?b:c} has the same size as the element type of @code{a}, then 12020 @code{b} and @code{c} are converted to a vector type whose elements have 12021 this type and with the same number of elements as @code{a}. 12022 12023 In C++, the logic operators @code{!, &&, ||} are available for vectors. 12024 @code{!v} is equivalent to @code{v == 0}, @code{a && b} is equivalent to 12025 @code{a!=0 & b!=0} and @code{a || b} is equivalent to @code{a!=0 | b!=0}. 12026 For mixed operations between a scalar @code{s} and a vector @code{v}, 12027 @code{s && v} is equivalent to @code{s?v!=0:0} (the evaluation is 12028 short-circuit) and @code{v && s} is equivalent to @code{v!=0 & (s?-1:0)}. 12029 12030 @findex __builtin_shuffle 12031 Vector shuffling is available using functions 12032 @code{__builtin_shuffle (vec, mask)} and 12033 @code{__builtin_shuffle (vec0, vec1, mask)}. 12034 Both functions construct a permutation of elements from one or two 12035 vectors and return a vector of the same type as the input vector(s). 12036 The @var{mask} is an integral vector with the same width (@var{W}) 12037 and element count (@var{N}) as the output vector. 12038 12039 The elements of the input vectors are numbered in memory ordering of 12040 @var{vec0} beginning at 0 and @var{vec1} beginning at @var{N}. The 12041 elements of @var{mask} are considered modulo @var{N} in the single-operand 12042 case and modulo @math{2*@var{N}} in the two-operand case. 12043 12044 Consider the following example, 12045 12046 @smallexample 12047 typedef int v4si __attribute__ ((vector_size (16))); 12048 12049 v4si a = @{1,2,3,4@}; 12050 v4si b = @{5,6,7,8@}; 12051 v4si mask1 = @{0,1,1,3@}; 12052 v4si mask2 = @{0,4,2,5@}; 12053 v4si res; 12054 12055 res = __builtin_shuffle (a, mask1); /* res is @{1,2,2,4@} */ 12056 res = __builtin_shuffle (a, b, mask2); /* res is @{1,5,3,6@} */ 12057 @end smallexample 12058 12059 Note that @code{__builtin_shuffle} is intentionally semantically 12060 compatible with the OpenCL @code{shuffle} and @code{shuffle2} functions. 12061 12062 You can declare variables and use them in function calls and returns, as 12063 well as in assignments and some casts. You can specify a vector type as 12064 a return type for a function. Vector types can also be used as function 12065 arguments. It is possible to cast from one vector type to another, 12066 provided they are of the same size (in fact, you can also cast vectors 12067 to and from other datatypes of the same size). 12068 12069 You cannot operate between vectors of different lengths or different 12070 signedness without a cast. 12071 12072 @findex __builtin_shufflevector 12073 Vector shuffling is available using the 12074 @code{__builtin_shufflevector (vec1, vec2, index...)} 12075 function. @var{vec1} and @var{vec2} must be expressions with 12076 vector type with a compatible element type. The result of 12077 @code{__builtin_shufflevector} is a vector with the same element type 12078 as @var{vec1} and @var{vec2} but that has an element count equal to 12079 the number of indices specified. 12080 12081 The @var{index} arguments are a list of integers that specify the 12082 elements indices of the first two vectors that should be extracted and 12083 returned in a new vector. These element indices are numbered sequentially 12084 starting with the first vector, continuing into the second vector. 12085 An index of -1 can be used to indicate that the corresponding element in 12086 the returned vector is a don't care and can be freely chosen to optimized 12087 the generated code sequence performing the shuffle operation. 12088 12089 Consider the following example, 12090 @smallexample 12091 typedef int v4si __attribute__ ((vector_size (16))); 12092 typedef int v8si __attribute__ ((vector_size (32))); 12093 12094 v8si a = @{1,-2,3,-4,5,-6,7,-8@}; 12095 v4si b = __builtin_shufflevector (a, a, 0, 2, 4, 6); /* b is @{1,3,5,7@} */ 12096 v4si c = @{-2,-4,-6,-8@}; 12097 v8si d = __builtin_shufflevector (c, b, 4, 0, 5, 1, 6, 2, 7, 3); /* d is a */ 12098 @end smallexample 12099 12100 @findex __builtin_convertvector 12101 Vector conversion is available using the 12102 @code{__builtin_convertvector (vec, vectype)} 12103 function. @var{vec} must be an expression with integral or floating 12104 vector type and @var{vectype} an integral or floating vector type with the 12105 same number of elements. The result has @var{vectype} type and value of 12106 a C cast of every element of @var{vec} to the element type of @var{vectype}. 12107 12108 Consider the following example, 12109 @smallexample 12110 typedef int v4si __attribute__ ((vector_size (16))); 12111 typedef float v4sf __attribute__ ((vector_size (16))); 12112 typedef double v4df __attribute__ ((vector_size (32))); 12113 typedef unsigned long long v4di __attribute__ ((vector_size (32))); 12114 12115 v4si a = @{1,-2,3,-4@}; 12116 v4sf b = @{1.5f,-2.5f,3.f,7.f@}; 12117 v4di c = @{1ULL,5ULL,0ULL,10ULL@}; 12118 v4sf d = __builtin_convertvector (a, v4sf); /* d is @{1.f,-2.f,3.f,-4.f@} */ 12119 /* Equivalent of: 12120 v4sf d = @{ (float)a[0], (float)a[1], (float)a[2], (float)a[3] @}; */ 12121 v4df e = __builtin_convertvector (a, v4df); /* e is @{1.,-2.,3.,-4.@} */ 12122 v4df f = __builtin_convertvector (b, v4df); /* f is @{1.5,-2.5,3.,7.@} */ 12123 v4si g = __builtin_convertvector (f, v4si); /* g is @{1,-2,3,7@} */ 12124 v4si h = __builtin_convertvector (c, v4si); /* h is @{1,5,0,10@} */ 12125 @end smallexample 12126 12127 @cindex vector types, using with x86 intrinsics 12128 Sometimes it is desirable to write code using a mix of generic vector 12129 operations (for clarity) and machine-specific vector intrinsics (to 12130 access vector instructions that are not exposed via generic built-ins). 12131 On x86, intrinsic functions for integer vectors typically use the same 12132 vector type @code{__m128i} irrespective of how they interpret the vector, 12133 making it necessary to cast their arguments and return values from/to 12134 other vector types. In C, you can make use of a @code{union} type: 12135 @c In C++ such type punning via a union is not allowed by the language 12136 @smallexample 12137 #include <immintrin.h> 12138 12139 typedef unsigned char u8x16 __attribute__ ((vector_size (16))); 12140 typedef unsigned int u32x4 __attribute__ ((vector_size (16))); 12141 12142 typedef union @{ 12143 __m128i mm; 12144 u8x16 u8; 12145 u32x4 u32; 12146 @} v128; 12147 @end smallexample 12148 12149 @noindent 12150 for variables that can be used with both built-in operators and x86 12151 intrinsics: 12152 12153 @smallexample 12154 v128 x, y = @{ 0 @}; 12155 memcpy (&x, ptr, sizeof x); 12156 y.u8 += 0x80; 12157 x.mm = _mm_adds_epu8 (x.mm, y.mm); 12158 x.u32 &= 0xffffff; 12159 12160 /* Instead of a variable, a compound literal may be used to pass the 12161 return value of an intrinsic call to a function expecting the union: */ 12162 v128 foo (v128); 12163 x = foo ((v128) @{_mm_adds_epu8 (x.mm, y.mm)@}); 12164 @c This could be done implicitly with __attribute__((transparent_union)), 12165 @c but GCC does not accept it for unions of vector types (PR 88955). 12166 @end smallexample 12167 12168 @node Offsetof 12169 @section Support for @code{offsetof} 12170 @findex __builtin_offsetof 12171 12172 GCC implements for both C and C++ a syntactic extension to implement 12173 the @code{offsetof} macro. 12174 12175 @smallexample 12176 primary: 12177 "__builtin_offsetof" "(" @code{typename} "," offsetof_member_designator ")" 12178 12179 offsetof_member_designator: 12180 @code{identifier} 12181 | offsetof_member_designator "." @code{identifier} 12182 | offsetof_member_designator "[" @code{expr} "]" 12183 @end smallexample 12184 12185 This extension is sufficient such that 12186 12187 @smallexample 12188 #define offsetof(@var{type}, @var{member}) __builtin_offsetof (@var{type}, @var{member}) 12189 @end smallexample 12190 12191 @noindent 12192 is a suitable definition of the @code{offsetof} macro. In C++, @var{type} 12193 may be dependent. In either case, @var{member} may consist of a single 12194 identifier, or a sequence of member accesses and array references. 12195 12196 @node __sync Builtins 12197 @section Legacy @code{__sync} Built-in Functions for Atomic Memory Access 12198 12199 The following built-in functions 12200 are intended to be compatible with those described 12201 in the @cite{Intel Itanium Processor-specific Application Binary Interface}, 12202 section 7.4. As such, they depart from normal GCC practice by not using 12203 the @samp{__builtin_} prefix and also by being overloaded so that they 12204 work on multiple types. 12205 12206 The definition given in the Intel documentation allows only for the use of 12207 the types @code{int}, @code{long}, @code{long long} or their unsigned 12208 counterparts. GCC allows any scalar type that is 1, 2, 4 or 8 bytes in 12209 size other than the C type @code{_Bool} or the C++ type @code{bool}. 12210 Operations on pointer arguments are performed as if the operands were 12211 of the @code{uintptr_t} type. That is, they are not scaled by the size 12212 of the type to which the pointer points. 12213 12214 These functions are implemented in terms of the @samp{__atomic} 12215 builtins (@pxref{__atomic Builtins}). They should not be used for new 12216 code which should use the @samp{__atomic} builtins instead. 12217 12218 Not all operations are supported by all target processors. If a particular 12219 operation cannot be implemented on the target processor, a call to an 12220 external function is generated. The external function carries the same name 12221 as the built-in version, with an additional suffix 12222 @samp{_@var{n}} where @var{n} is the size of the data type. 12223 12224 In most cases, these built-in functions are considered a @dfn{full barrier}. 12225 That is, 12226 no memory operand is moved across the operation, either forward or 12227 backward. Further, instructions are issued as necessary to prevent the 12228 processor from speculating loads across the operation and from queuing stores 12229 after the operation. 12230 12231 All of the routines are described in the Intel documentation to take 12232 ``an optional list of variables protected by the memory barrier''. It's 12233 not clear what is meant by that; it could mean that @emph{only} the 12234 listed variables are protected, or it could mean a list of additional 12235 variables to be protected. The list is ignored by GCC which treats it as 12236 empty. GCC interprets an empty list as meaning that all globally 12237 accessible variables should be protected. 12238 12239 @table @code 12240 @item @var{type} __sync_fetch_and_add (@var{type} *ptr, @var{type} value, ...) 12241 @itemx @var{type} __sync_fetch_and_sub (@var{type} *ptr, @var{type} value, ...) 12242 @itemx @var{type} __sync_fetch_and_or (@var{type} *ptr, @var{type} value, ...) 12243 @itemx @var{type} __sync_fetch_and_and (@var{type} *ptr, @var{type} value, ...) 12244 @itemx @var{type} __sync_fetch_and_xor (@var{type} *ptr, @var{type} value, ...) 12245 @itemx @var{type} __sync_fetch_and_nand (@var{type} *ptr, @var{type} value, ...) 12246 @findex __sync_fetch_and_add 12247 @findex __sync_fetch_and_sub 12248 @findex __sync_fetch_and_or 12249 @findex __sync_fetch_and_and 12250 @findex __sync_fetch_and_xor 12251 @findex __sync_fetch_and_nand 12252 These built-in functions perform the operation suggested by the name, and 12253 returns the value that had previously been in memory. That is, operations 12254 on integer operands have the following semantics. Operations on pointer 12255 arguments are performed as if the operands were of the @code{uintptr_t} 12256 type. That is, they are not scaled by the size of the type to which 12257 the pointer points. 12258 12259 @smallexample 12260 @{ tmp = *ptr; *ptr @var{op}= value; return tmp; @} 12261 @{ tmp = *ptr; *ptr = ~(tmp & value); return tmp; @} // nand 12262 @end smallexample 12263 12264 The object pointed to by the first argument must be of integer or pointer 12265 type. It must not be a boolean type. 12266 12267 @emph{Note:} GCC 4.4 and later implement @code{__sync_fetch_and_nand} 12268 as @code{*ptr = ~(tmp & value)} instead of @code{*ptr = ~tmp & value}. 12269 12270 @item @var{type} __sync_add_and_fetch (@var{type} *ptr, @var{type} value, ...) 12271 @itemx @var{type} __sync_sub_and_fetch (@var{type} *ptr, @var{type} value, ...) 12272 @itemx @var{type} __sync_or_and_fetch (@var{type} *ptr, @var{type} value, ...) 12273 @itemx @var{type} __sync_and_and_fetch (@var{type} *ptr, @var{type} value, ...) 12274 @itemx @var{type} __sync_xor_and_fetch (@var{type} *ptr, @var{type} value, ...) 12275 @itemx @var{type} __sync_nand_and_fetch (@var{type} *ptr, @var{type} value, ...) 12276 @findex __sync_add_and_fetch 12277 @findex __sync_sub_and_fetch 12278 @findex __sync_or_and_fetch 12279 @findex __sync_and_and_fetch 12280 @findex __sync_xor_and_fetch 12281 @findex __sync_nand_and_fetch 12282 These built-in functions perform the operation suggested by the name, and 12283 return the new value. That is, operations on integer operands have 12284 the following semantics. Operations on pointer operands are performed as 12285 if the operand's type were @code{uintptr_t}. 12286 12287 @smallexample 12288 @{ *ptr @var{op}= value; return *ptr; @} 12289 @{ *ptr = ~(*ptr & value); return *ptr; @} // nand 12290 @end smallexample 12291 12292 The same constraints on arguments apply as for the corresponding 12293 @code{__sync_op_and_fetch} built-in functions. 12294 12295 @emph{Note:} GCC 4.4 and later implement @code{__sync_nand_and_fetch} 12296 as @code{*ptr = ~(*ptr & value)} instead of 12297 @code{*ptr = ~*ptr & value}. 12298 12299 @item bool __sync_bool_compare_and_swap (@var{type} *ptr, @var{type} oldval, @var{type} newval, ...) 12300 @itemx @var{type} __sync_val_compare_and_swap (@var{type} *ptr, @var{type} oldval, @var{type} newval, ...) 12301 @findex __sync_bool_compare_and_swap 12302 @findex __sync_val_compare_and_swap 12303 These built-in functions perform an atomic compare and swap. 12304 That is, if the current 12305 value of @code{*@var{ptr}} is @var{oldval}, then write @var{newval} into 12306 @code{*@var{ptr}}. 12307 12308 The ``bool'' version returns @code{true} if the comparison is successful and 12309 @var{newval} is written. The ``val'' version returns the contents 12310 of @code{*@var{ptr}} before the operation. 12311 12312 @item __sync_synchronize (...) 12313 @findex __sync_synchronize 12314 This built-in function issues a full memory barrier. 12315 12316 @item @var{type} __sync_lock_test_and_set (@var{type} *ptr, @var{type} value, ...) 12317 @findex __sync_lock_test_and_set 12318 This built-in function, as described by Intel, is not a traditional test-and-set 12319 operation, but rather an atomic exchange operation. It writes @var{value} 12320 into @code{*@var{ptr}}, and returns the previous contents of 12321 @code{*@var{ptr}}. 12322 12323 Many targets have only minimal support for such locks, and do not support 12324 a full exchange operation. In this case, a target may support reduced 12325 functionality here by which the @emph{only} valid value to store is the 12326 immediate constant 1. The exact value actually stored in @code{*@var{ptr}} 12327 is implementation defined. 12328 12329 This built-in function is not a full barrier, 12330 but rather an @dfn{acquire barrier}. 12331 This means that references after the operation cannot move to (or be 12332 speculated to) before the operation, but previous memory stores may not 12333 be globally visible yet, and previous memory loads may not yet be 12334 satisfied. 12335 12336 @item void __sync_lock_release (@var{type} *ptr, ...) 12337 @findex __sync_lock_release 12338 This built-in function releases the lock acquired by 12339 @code{__sync_lock_test_and_set}. 12340 Normally this means writing the constant 0 to @code{*@var{ptr}}. 12341 12342 This built-in function is not a full barrier, 12343 but rather a @dfn{release barrier}. 12344 This means that all previous memory stores are globally visible, and all 12345 previous memory loads have been satisfied, but following memory reads 12346 are not prevented from being speculated to before the barrier. 12347 @end table 12348 12349 @node __atomic Builtins 12350 @section Built-in Functions for Memory Model Aware Atomic Operations 12351 12352 The following built-in functions approximately match the requirements 12353 for the C++11 memory model. They are all 12354 identified by being prefixed with @samp{__atomic} and most are 12355 overloaded so that they work with multiple types. 12356 12357 These functions are intended to replace the legacy @samp{__sync} 12358 builtins. The main difference is that the memory order that is requested 12359 is a parameter to the functions. New code should always use the 12360 @samp{__atomic} builtins rather than the @samp{__sync} builtins. 12361 12362 Note that the @samp{__atomic} builtins assume that programs will 12363 conform to the C++11 memory model. In particular, they assume 12364 that programs are free of data races. See the C++11 standard for 12365 detailed requirements. 12366 12367 The @samp{__atomic} builtins can be used with any integral scalar or 12368 pointer type that is 1, 2, 4, or 8 bytes in length. 16-byte integral 12369 types are also allowed if @samp{__int128} (@pxref{__int128}) is 12370 supported by the architecture. 12371 12372 The four non-arithmetic functions (load, store, exchange, and 12373 compare_exchange) all have a generic version as well. This generic 12374 version works on any data type. It uses the lock-free built-in function 12375 if the specific data type size makes that possible; otherwise, an 12376 external call is left to be resolved at run time. This external call is 12377 the same format with the addition of a @samp{size_t} parameter inserted 12378 as the first parameter indicating the size of the object being pointed to. 12379 All objects must be the same size. 12380 12381 There are 6 different memory orders that can be specified. These map 12382 to the C++11 memory orders with the same names, see the C++11 standard 12383 or the @uref{https://gcc.gnu.org/wiki/Atomic/GCCMM/AtomicSync,GCC wiki 12384 on atomic synchronization} for detailed definitions. Individual 12385 targets may also support additional memory orders for use on specific 12386 architectures. Refer to the target documentation for details of 12387 these. 12388 12389 An atomic operation can both constrain code motion and 12390 be mapped to hardware instructions for synchronization between threads 12391 (e.g., a fence). To which extent this happens is controlled by the 12392 memory orders, which are listed here in approximately ascending order of 12393 strength. The description of each memory order is only meant to roughly 12394 illustrate the effects and is not a specification; see the C++11 12395 memory model for precise semantics. 12396 12397 @table @code 12398 @item __ATOMIC_RELAXED 12399 Implies no inter-thread ordering constraints. 12400 @item __ATOMIC_CONSUME 12401 This is currently implemented using the stronger @code{__ATOMIC_ACQUIRE} 12402 memory order because of a deficiency in C++11's semantics for 12403 @code{memory_order_consume}. 12404 @item __ATOMIC_ACQUIRE 12405 Creates an inter-thread happens-before constraint from the release (or 12406 stronger) semantic store to this acquire load. Can prevent hoisting 12407 of code to before the operation. 12408 @item __ATOMIC_RELEASE 12409 Creates an inter-thread happens-before constraint to acquire (or stronger) 12410 semantic loads that read from this release store. Can prevent sinking 12411 of code to after the operation. 12412 @item __ATOMIC_ACQ_REL 12413 Combines the effects of both @code{__ATOMIC_ACQUIRE} and 12414 @code{__ATOMIC_RELEASE}. 12415 @item __ATOMIC_SEQ_CST 12416 Enforces total ordering with all other @code{__ATOMIC_SEQ_CST} operations. 12417 @end table 12418 12419 Note that in the C++11 memory model, @emph{fences} (e.g., 12420 @samp{__atomic_thread_fence}) take effect in combination with other 12421 atomic operations on specific memory locations (e.g., atomic loads); 12422 operations on specific memory locations do not necessarily affect other 12423 operations in the same way. 12424 12425 Target architectures are encouraged to provide their own patterns for 12426 each of the atomic built-in functions. If no target is provided, the original 12427 non-memory model set of @samp{__sync} atomic built-in functions are 12428 used, along with any required synchronization fences surrounding it in 12429 order to achieve the proper behavior. Execution in this case is subject 12430 to the same restrictions as those built-in functions. 12431 12432 If there is no pattern or mechanism to provide a lock-free instruction 12433 sequence, a call is made to an external routine with the same parameters 12434 to be resolved at run time. 12435 12436 When implementing patterns for these built-in functions, the memory order 12437 parameter can be ignored as long as the pattern implements the most 12438 restrictive @code{__ATOMIC_SEQ_CST} memory order. Any of the other memory 12439 orders execute correctly with this memory order but they may not execute as 12440 efficiently as they could with a more appropriate implementation of the 12441 relaxed requirements. 12442 12443 Note that the C++11 standard allows for the memory order parameter to be 12444 determined at run time rather than at compile time. These built-in 12445 functions map any run-time value to @code{__ATOMIC_SEQ_CST} rather 12446 than invoke a runtime library call or inline a switch statement. This is 12447 standard compliant, safe, and the simplest approach for now. 12448 12449 The memory order parameter is a signed int, but only the lower 16 bits are 12450 reserved for the memory order. The remainder of the signed int is reserved 12451 for target use and should be 0. Use of the predefined atomic values 12452 ensures proper usage. 12453 12454 @deftypefn {Built-in Function} @var{type} __atomic_load_n (@var{type} *ptr, int memorder) 12455 This built-in function implements an atomic load operation. It returns the 12456 contents of @code{*@var{ptr}}. 12457 12458 The valid memory order variants are 12459 @code{__ATOMIC_RELAXED}, @code{__ATOMIC_SEQ_CST}, @code{__ATOMIC_ACQUIRE}, 12460 and @code{__ATOMIC_CONSUME}. 12461 12462 @end deftypefn 12463 12464 @deftypefn {Built-in Function} void __atomic_load (@var{type} *ptr, @var{type} *ret, int memorder) 12465 This is the generic version of an atomic load. It returns the 12466 contents of @code{*@var{ptr}} in @code{*@var{ret}}. 12467 12468 @end deftypefn 12469 12470 @deftypefn {Built-in Function} void __atomic_store_n (@var{type} *ptr, @var{type} val, int memorder) 12471 This built-in function implements an atomic store operation. It writes 12472 @code{@var{val}} into @code{*@var{ptr}}. 12473 12474 The valid memory order variants are 12475 @code{__ATOMIC_RELAXED}, @code{__ATOMIC_SEQ_CST}, and @code{__ATOMIC_RELEASE}. 12476 12477 @end deftypefn 12478 12479 @deftypefn {Built-in Function} void __atomic_store (@var{type} *ptr, @var{type} *val, int memorder) 12480 This is the generic version of an atomic store. It stores the value 12481 of @code{*@var{val}} into @code{*@var{ptr}}. 12482 12483 @end deftypefn 12484 12485 @deftypefn {Built-in Function} @var{type} __atomic_exchange_n (@var{type} *ptr, @var{type} val, int memorder) 12486 This built-in function implements an atomic exchange operation. It writes 12487 @var{val} into @code{*@var{ptr}}, and returns the previous contents of 12488 @code{*@var{ptr}}. 12489 12490 All memory order variants are valid. 12491 12492 @end deftypefn 12493 12494 @deftypefn {Built-in Function} void __atomic_exchange (@var{type} *ptr, @var{type} *val, @var{type} *ret, int memorder) 12495 This is the generic version of an atomic exchange. It stores the 12496 contents of @code{*@var{val}} into @code{*@var{ptr}}. The original value 12497 of @code{*@var{ptr}} is copied into @code{*@var{ret}}. 12498 12499 @end deftypefn 12500 12501 @deftypefn {Built-in Function} bool __atomic_compare_exchange_n (@var{type} *ptr, @var{type} *expected, @var{type} desired, bool weak, int success_memorder, int failure_memorder) 12502 This built-in function implements an atomic compare and exchange operation. 12503 This compares the contents of @code{*@var{ptr}} with the contents of 12504 @code{*@var{expected}}. If equal, the operation is a @emph{read-modify-write} 12505 operation that writes @var{desired} into @code{*@var{ptr}}. If they are not 12506 equal, the operation is a @emph{read} and the current contents of 12507 @code{*@var{ptr}} are written into @code{*@var{expected}}. @var{weak} is @code{true} 12508 for weak compare_exchange, which may fail spuriously, and @code{false} for 12509 the strong variation, which never fails spuriously. Many targets 12510 only offer the strong variation and ignore the parameter. When in doubt, use 12511 the strong variation. 12512 12513 If @var{desired} is written into @code{*@var{ptr}} then @code{true} is returned 12514 and memory is affected according to the 12515 memory order specified by @var{success_memorder}. There are no 12516 restrictions on what memory order can be used here. 12517 12518 Otherwise, @code{false} is returned and memory is affected according 12519 to @var{failure_memorder}. This memory order cannot be 12520 @code{__ATOMIC_RELEASE} nor @code{__ATOMIC_ACQ_REL}. It also cannot be a 12521 stronger order than that specified by @var{success_memorder}. 12522 12523 @end deftypefn 12524 12525 @deftypefn {Built-in Function} bool __atomic_compare_exchange (@var{type} *ptr, @var{type} *expected, @var{type} *desired, bool weak, int success_memorder, int failure_memorder) 12526 This built-in function implements the generic version of 12527 @code{__atomic_compare_exchange}. The function is virtually identical to 12528 @code{__atomic_compare_exchange_n}, except the desired value is also a 12529 pointer. 12530 12531 @end deftypefn 12532 12533 @deftypefn {Built-in Function} @var{type} __atomic_add_fetch (@var{type} *ptr, @var{type} val, int memorder) 12534 @deftypefnx {Built-in Function} @var{type} __atomic_sub_fetch (@var{type} *ptr, @var{type} val, int memorder) 12535 @deftypefnx {Built-in Function} @var{type} __atomic_and_fetch (@var{type} *ptr, @var{type} val, int memorder) 12536 @deftypefnx {Built-in Function} @var{type} __atomic_xor_fetch (@var{type} *ptr, @var{type} val, int memorder) 12537 @deftypefnx {Built-in Function} @var{type} __atomic_or_fetch (@var{type} *ptr, @var{type} val, int memorder) 12538 @deftypefnx {Built-in Function} @var{type} __atomic_nand_fetch (@var{type} *ptr, @var{type} val, int memorder) 12539 These built-in functions perform the operation suggested by the name, and 12540 return the result of the operation. Operations on pointer arguments are 12541 performed as if the operands were of the @code{uintptr_t} type. That is, 12542 they are not scaled by the size of the type to which the pointer points. 12543 12544 @smallexample 12545 @{ *ptr @var{op}= val; return *ptr; @} 12546 @{ *ptr = ~(*ptr & val); return *ptr; @} // nand 12547 @end smallexample 12548 12549 The object pointed to by the first argument must be of integer or pointer 12550 type. It must not be a boolean type. All memory orders are valid. 12551 12552 @end deftypefn 12553 12554 @deftypefn {Built-in Function} @var{type} __atomic_fetch_add (@var{type} *ptr, @var{type} val, int memorder) 12555 @deftypefnx {Built-in Function} @var{type} __atomic_fetch_sub (@var{type} *ptr, @var{type} val, int memorder) 12556 @deftypefnx {Built-in Function} @var{type} __atomic_fetch_and (@var{type} *ptr, @var{type} val, int memorder) 12557 @deftypefnx {Built-in Function} @var{type} __atomic_fetch_xor (@var{type} *ptr, @var{type} val, int memorder) 12558 @deftypefnx {Built-in Function} @var{type} __atomic_fetch_or (@var{type} *ptr, @var{type} val, int memorder) 12559 @deftypefnx {Built-in Function} @var{type} __atomic_fetch_nand (@var{type} *ptr, @var{type} val, int memorder) 12560 These built-in functions perform the operation suggested by the name, and 12561 return the value that had previously been in @code{*@var{ptr}}. Operations 12562 on pointer arguments are performed as if the operands were of 12563 the @code{uintptr_t} type. That is, they are not scaled by the size of 12564 the type to which the pointer points. 12565 12566 @smallexample 12567 @{ tmp = *ptr; *ptr @var{op}= val; return tmp; @} 12568 @{ tmp = *ptr; *ptr = ~(*ptr & val); return tmp; @} // nand 12569 @end smallexample 12570 12571 The same constraints on arguments apply as for the corresponding 12572 @code{__atomic_op_fetch} built-in functions. All memory orders are valid. 12573 12574 @end deftypefn 12575 12576 @deftypefn {Built-in Function} bool __atomic_test_and_set (void *ptr, int memorder) 12577 12578 This built-in function performs an atomic test-and-set operation on 12579 the byte at @code{*@var{ptr}}. The byte is set to some implementation 12580 defined nonzero ``set'' value and the return value is @code{true} if and only 12581 if the previous contents were ``set''. 12582 It should be only used for operands of type @code{bool} or @code{char}. For 12583 other types only part of the value may be set. 12584 12585 All memory orders are valid. 12586 12587 @end deftypefn 12588 12589 @deftypefn {Built-in Function} void __atomic_clear (bool *ptr, int memorder) 12590 12591 This built-in function performs an atomic clear operation on 12592 @code{*@var{ptr}}. After the operation, @code{*@var{ptr}} contains 0. 12593 It should be only used for operands of type @code{bool} or @code{char} and 12594 in conjunction with @code{__atomic_test_and_set}. 12595 For other types it may only clear partially. If the type is not @code{bool} 12596 prefer using @code{__atomic_store}. 12597 12598 The valid memory order variants are 12599 @code{__ATOMIC_RELAXED}, @code{__ATOMIC_SEQ_CST}, and 12600 @code{__ATOMIC_RELEASE}. 12601 12602 @end deftypefn 12603 12604 @deftypefn {Built-in Function} void __atomic_thread_fence (int memorder) 12605 12606 This built-in function acts as a synchronization fence between threads 12607 based on the specified memory order. 12608 12609 All memory orders are valid. 12610 12611 @end deftypefn 12612 12613 @deftypefn {Built-in Function} void __atomic_signal_fence (int memorder) 12614 12615 This built-in function acts as a synchronization fence between a thread 12616 and signal handlers based in the same thread. 12617 12618 All memory orders are valid. 12619 12620 @end deftypefn 12621 12622 @deftypefn {Built-in Function} bool __atomic_always_lock_free (size_t size, void *ptr) 12623 12624 This built-in function returns @code{true} if objects of @var{size} bytes always 12625 generate lock-free atomic instructions for the target architecture. 12626 @var{size} must resolve to a compile-time constant and the result also 12627 resolves to a compile-time constant. 12628 12629 @var{ptr} is an optional pointer to the object that may be used to determine 12630 alignment. A value of 0 indicates typical alignment should be used. The 12631 compiler may also ignore this parameter. 12632 12633 @smallexample 12634 if (__atomic_always_lock_free (sizeof (long long), 0)) 12635 @end smallexample 12636 12637 @end deftypefn 12638 12639 @deftypefn {Built-in Function} bool __atomic_is_lock_free (size_t size, void *ptr) 12640 12641 This built-in function returns @code{true} if objects of @var{size} bytes always 12642 generate lock-free atomic instructions for the target architecture. If 12643 the built-in function is not known to be lock-free, a call is made to a 12644 runtime routine named @code{__atomic_is_lock_free}. 12645 12646 @var{ptr} is an optional pointer to the object that may be used to determine 12647 alignment. A value of 0 indicates typical alignment should be used. The 12648 compiler may also ignore this parameter. 12649 @end deftypefn 12650 12651 @node Integer Overflow Builtins 12652 @section Built-in Functions to Perform Arithmetic with Overflow Checking 12653 12654 The following built-in functions allow performing simple arithmetic operations 12655 together with checking whether the operations overflowed. 12656 12657 @deftypefn {Built-in Function} bool __builtin_add_overflow (@var{type1} a, @var{type2} b, @var{type3} *res) 12658 @deftypefnx {Built-in Function} bool __builtin_sadd_overflow (int a, int b, int *res) 12659 @deftypefnx {Built-in Function} bool __builtin_saddl_overflow (long int a, long int b, long int *res) 12660 @deftypefnx {Built-in Function} bool __builtin_saddll_overflow (long long int a, long long int b, long long int *res) 12661 @deftypefnx {Built-in Function} bool __builtin_uadd_overflow (unsigned int a, unsigned int b, unsigned int *res) 12662 @deftypefnx {Built-in Function} bool __builtin_uaddl_overflow (unsigned long int a, unsigned long int b, unsigned long int *res) 12663 @deftypefnx {Built-in Function} bool __builtin_uaddll_overflow (unsigned long long int a, unsigned long long int b, unsigned long long int *res) 12664 12665 These built-in functions promote the first two operands into infinite precision signed 12666 type and perform addition on those promoted operands. The result is then 12667 cast to the type the third pointer argument points to and stored there. 12668 If the stored result is equal to the infinite precision result, the built-in 12669 functions return @code{false}, otherwise they return @code{true}. As the addition is 12670 performed in infinite signed precision, these built-in functions have fully defined 12671 behavior for all argument values. 12672 12673 The first built-in function allows arbitrary integral types for operands and 12674 the result type must be pointer to some integral type other than enumerated or 12675 boolean type, the rest of the built-in functions have explicit integer types. 12676 12677 The compiler will attempt to use hardware instructions to implement 12678 these built-in functions where possible, like conditional jump on overflow 12679 after addition, conditional jump on carry etc. 12680 12681 @end deftypefn 12682 12683 @deftypefn {Built-in Function} bool __builtin_sub_overflow (@var{type1} a, @var{type2} b, @var{type3} *res) 12684 @deftypefnx {Built-in Function} bool __builtin_ssub_overflow (int a, int b, int *res) 12685 @deftypefnx {Built-in Function} bool __builtin_ssubl_overflow (long int a, long int b, long int *res) 12686 @deftypefnx {Built-in Function} bool __builtin_ssubll_overflow (long long int a, long long int b, long long int *res) 12687 @deftypefnx {Built-in Function} bool __builtin_usub_overflow (unsigned int a, unsigned int b, unsigned int *res) 12688 @deftypefnx {Built-in Function} bool __builtin_usubl_overflow (unsigned long int a, unsigned long int b, unsigned long int *res) 12689 @deftypefnx {Built-in Function} bool __builtin_usubll_overflow (unsigned long long int a, unsigned long long int b, unsigned long long int *res) 12690 12691 These built-in functions are similar to the add overflow checking built-in 12692 functions above, except they perform subtraction, subtract the second argument 12693 from the first one, instead of addition. 12694 12695 @end deftypefn 12696 12697 @deftypefn {Built-in Function} bool __builtin_mul_overflow (@var{type1} a, @var{type2} b, @var{type3} *res) 12698 @deftypefnx {Built-in Function} bool __builtin_smul_overflow (int a, int b, int *res) 12699 @deftypefnx {Built-in Function} bool __builtin_smull_overflow (long int a, long int b, long int *res) 12700 @deftypefnx {Built-in Function} bool __builtin_smulll_overflow (long long int a, long long int b, long long int *res) 12701 @deftypefnx {Built-in Function} bool __builtin_umul_overflow (unsigned int a, unsigned int b, unsigned int *res) 12702 @deftypefnx {Built-in Function} bool __builtin_umull_overflow (unsigned long int a, unsigned long int b, unsigned long int *res) 12703 @deftypefnx {Built-in Function} bool __builtin_umulll_overflow (unsigned long long int a, unsigned long long int b, unsigned long long int *res) 12704 12705 These built-in functions are similar to the add overflow checking built-in 12706 functions above, except they perform multiplication, instead of addition. 12707 12708 @end deftypefn 12709 12710 The following built-in functions allow checking if simple arithmetic operation 12711 would overflow. 12712 12713 @deftypefn {Built-in Function} bool __builtin_add_overflow_p (@var{type1} a, @var{type2} b, @var{type3} c) 12714 @deftypefnx {Built-in Function} bool __builtin_sub_overflow_p (@var{type1} a, @var{type2} b, @var{type3} c) 12715 @deftypefnx {Built-in Function} bool __builtin_mul_overflow_p (@var{type1} a, @var{type2} b, @var{type3} c) 12716 12717 These built-in functions are similar to @code{__builtin_add_overflow}, 12718 @code{__builtin_sub_overflow}, or @code{__builtin_mul_overflow}, except that 12719 they don't store the result of the arithmetic operation anywhere and the 12720 last argument is not a pointer, but some expression with integral type other 12721 than enumerated or boolean type. 12722 12723 The built-in functions promote the first two operands into infinite precision signed type 12724 and perform addition on those promoted operands. The result is then 12725 cast to the type of the third argument. If the cast result is equal to the infinite 12726 precision result, the built-in functions return @code{false}, otherwise they return @code{true}. 12727 The value of the third argument is ignored, just the side effects in the third argument 12728 are evaluated, and no integral argument promotions are performed on the last argument. 12729 If the third argument is a bit-field, the type used for the result cast has the 12730 precision and signedness of the given bit-field, rather than precision and signedness 12731 of the underlying type. 12732 12733 For example, the following macro can be used to portably check, at 12734 compile-time, whether or not adding two constant integers will overflow, 12735 and perform the addition only when it is known to be safe and not to trigger 12736 a @option{-Woverflow} warning. 12737 12738 @smallexample 12739 #define INT_ADD_OVERFLOW_P(a, b) \ 12740 __builtin_add_overflow_p (a, b, (__typeof__ ((a) + (b))) 0) 12741 12742 enum @{ 12743 A = INT_MAX, B = 3, 12744 C = INT_ADD_OVERFLOW_P (A, B) ? 0 : A + B, 12745 D = __builtin_add_overflow_p (1, SCHAR_MAX, (signed char) 0) 12746 @}; 12747 @end smallexample 12748 12749 The compiler will attempt to use hardware instructions to implement 12750 these built-in functions where possible, like conditional jump on overflow 12751 after addition, conditional jump on carry etc. 12752 12753 @end deftypefn 12754 12755 @node x86 specific memory model extensions for transactional memory 12756 @section x86-Specific Memory Model Extensions for Transactional Memory 12757 12758 The x86 architecture supports additional memory ordering flags 12759 to mark critical sections for hardware lock elision. 12760 These must be specified in addition to an existing memory order to 12761 atomic intrinsics. 12762 12763 @table @code 12764 @item __ATOMIC_HLE_ACQUIRE 12765 Start lock elision on a lock variable. 12766 Memory order must be @code{__ATOMIC_ACQUIRE} or stronger. 12767 @item __ATOMIC_HLE_RELEASE 12768 End lock elision on a lock variable. 12769 Memory order must be @code{__ATOMIC_RELEASE} or stronger. 12770 @end table 12771 12772 When a lock acquire fails, it is required for good performance to abort 12773 the transaction quickly. This can be done with a @code{_mm_pause}. 12774 12775 @smallexample 12776 #include <immintrin.h> // For _mm_pause 12777 12778 int lockvar; 12779 12780 /* Acquire lock with lock elision */ 12781 while (__atomic_exchange_n(&lockvar, 1, __ATOMIC_ACQUIRE|__ATOMIC_HLE_ACQUIRE)) 12782 _mm_pause(); /* Abort failed transaction */ 12783 ... 12784 /* Free lock with lock elision */ 12785 __atomic_store_n(&lockvar, 0, __ATOMIC_RELEASE|__ATOMIC_HLE_RELEASE); 12786 @end smallexample 12787 12788 @node Object Size Checking 12789 @section Object Size Checking Built-in Functions 12790 @findex __builtin_object_size 12791 @findex __builtin_dynamic_object_size 12792 @findex __builtin___memcpy_chk 12793 @findex __builtin___mempcpy_chk 12794 @findex __builtin___memmove_chk 12795 @findex __builtin___memset_chk 12796 @findex __builtin___strcpy_chk 12797 @findex __builtin___stpcpy_chk 12798 @findex __builtin___strncpy_chk 12799 @findex __builtin___strcat_chk 12800 @findex __builtin___strncat_chk 12801 @findex __builtin___sprintf_chk 12802 @findex __builtin___snprintf_chk 12803 @findex __builtin___vsprintf_chk 12804 @findex __builtin___vsnprintf_chk 12805 @findex __builtin___printf_chk 12806 @findex __builtin___vprintf_chk 12807 @findex __builtin___fprintf_chk 12808 @findex __builtin___vfprintf_chk 12809 12810 GCC implements a limited buffer overflow protection mechanism that can 12811 prevent some buffer overflow attacks by determining the sizes of objects 12812 into which data is about to be written and preventing the writes when 12813 the size isn't sufficient. The built-in functions described below yield 12814 the best results when used together and when optimization is enabled. 12815 For example, to detect object sizes across function boundaries or to 12816 follow pointer assignments through non-trivial control flow they rely 12817 on various optimization passes enabled with @option{-O2}. However, to 12818 a limited extent, they can be used without optimization as well. 12819 12820 @deftypefn {Built-in Function} {size_t} __builtin_object_size (const void * @var{ptr}, int @var{type}) 12821 is a built-in construct that returns a constant number of bytes from 12822 @var{ptr} to the end of the object @var{ptr} pointer points to 12823 (if known at compile time). To determine the sizes of dynamically allocated 12824 objects the function relies on the allocation functions called to obtain 12825 the storage to be declared with the @code{alloc_size} attribute (@pxref{Common 12826 Function Attributes}). @code{__builtin_object_size} never evaluates 12827 its arguments for side effects. If there are any side effects in them, it 12828 returns @code{(size_t) -1} for @var{type} 0 or 1 and @code{(size_t) 0} 12829 for @var{type} 2 or 3. If there are multiple objects @var{ptr} can 12830 point to and all of them are known at compile time, the returned number 12831 is the maximum of remaining byte counts in those objects if @var{type} & 2 is 12832 0 and minimum if nonzero. If it is not possible to determine which objects 12833 @var{ptr} points to at compile time, @code{__builtin_object_size} should 12834 return @code{(size_t) -1} for @var{type} 0 or 1 and @code{(size_t) 0} 12835 for @var{type} 2 or 3. 12836 12837 @var{type} is an integer constant from 0 to 3. If the least significant 12838 bit is clear, objects are whole variables, if it is set, a closest 12839 surrounding subobject is considered the object a pointer points to. 12840 The second bit determines if maximum or minimum of remaining bytes 12841 is computed. 12842 12843 @smallexample 12844 struct V @{ char buf1[10]; int b; char buf2[10]; @} var; 12845 char *p = &var.buf1[1], *q = &var.b; 12846 12847 /* Here the object p points to is var. */ 12848 assert (__builtin_object_size (p, 0) == sizeof (var) - 1); 12849 /* The subobject p points to is var.buf1. */ 12850 assert (__builtin_object_size (p, 1) == sizeof (var.buf1) - 1); 12851 /* The object q points to is var. */ 12852 assert (__builtin_object_size (q, 0) 12853 == (char *) (&var + 1) - (char *) &var.b); 12854 /* The subobject q points to is var.b. */ 12855 assert (__builtin_object_size (q, 1) == sizeof (var.b)); 12856 @end smallexample 12857 @end deftypefn 12858 12859 @deftypefn {Built-in Function} {size_t} __builtin_dynamic_object_size (const void * @var{ptr}, int @var{type}) 12860 is similar to @code{__builtin_object_size} in that it returns a number of bytes 12861 from @var{ptr} to the end of the object @var{ptr} pointer points to, except 12862 that the size returned may not be a constant. This results in successful 12863 evaluation of object size estimates in a wider range of use cases and can be 12864 more precise than @code{__builtin_object_size}, but it incurs a performance 12865 penalty since it may add a runtime overhead on size computation. Semantics of 12866 @var{type} as well as return values in case it is not possible to determine 12867 which objects @var{ptr} points to at compile time are the same as in the case 12868 of @code{__builtin_object_size}. 12869 @end deftypefn 12870 12871 There are built-in functions added for many common string operation 12872 functions, e.g., for @code{memcpy} @code{__builtin___memcpy_chk} 12873 built-in is provided. This built-in has an additional last argument, 12874 which is the number of bytes remaining in the object the @var{dest} 12875 argument points to or @code{(size_t) -1} if the size is not known. 12876 12877 The built-in functions are optimized into the normal string functions 12878 like @code{memcpy} if the last argument is @code{(size_t) -1} or if 12879 it is known at compile time that the destination object will not 12880 be overflowed. If the compiler can determine at compile time that the 12881 object will always be overflowed, it issues a warning. 12882 12883 The intended use can be e.g.@: 12884 12885 @smallexample 12886 #undef memcpy 12887 #define bos0(dest) __builtin_object_size (dest, 0) 12888 #define memcpy(dest, src, n) \ 12889 __builtin___memcpy_chk (dest, src, n, bos0 (dest)) 12890 12891 char *volatile p; 12892 char buf[10]; 12893 /* It is unknown what object p points to, so this is optimized 12894 into plain memcpy - no checking is possible. */ 12895 memcpy (p, "abcde", n); 12896 /* Destination is known and length too. It is known at compile 12897 time there will be no overflow. */ 12898 memcpy (&buf[5], "abcde", 5); 12899 /* Destination is known, but the length is not known at compile time. 12900 This will result in __memcpy_chk call that can check for overflow 12901 at run time. */ 12902 memcpy (&buf[5], "abcde", n); 12903 /* Destination is known and it is known at compile time there will 12904 be overflow. There will be a warning and __memcpy_chk call that 12905 will abort the program at run time. */ 12906 memcpy (&buf[6], "abcde", 5); 12907 @end smallexample 12908 12909 Such built-in functions are provided for @code{memcpy}, @code{mempcpy}, 12910 @code{memmove}, @code{memset}, @code{strcpy}, @code{stpcpy}, @code{strncpy}, 12911 @code{strcat} and @code{strncat}. 12912 12913 There are also checking built-in functions for formatted output functions. 12914 @smallexample 12915 int __builtin___sprintf_chk (char *s, int flag, size_t os, const char *fmt, ...); 12916 int __builtin___snprintf_chk (char *s, size_t maxlen, int flag, size_t os, 12917 const char *fmt, ...); 12918 int __builtin___vsprintf_chk (char *s, int flag, size_t os, const char *fmt, 12919 va_list ap); 12920 int __builtin___vsnprintf_chk (char *s, size_t maxlen, int flag, size_t os, 12921 const char *fmt, va_list ap); 12922 @end smallexample 12923 12924 The added @var{flag} argument is passed unchanged to @code{__sprintf_chk} 12925 etc.@: functions and can contain implementation specific flags on what 12926 additional security measures the checking function might take, such as 12927 handling @code{%n} differently. 12928 12929 The @var{os} argument is the object size @var{s} points to, like in the 12930 other built-in functions. There is a small difference in the behavior 12931 though, if @var{os} is @code{(size_t) -1}, the built-in functions are 12932 optimized into the non-checking functions only if @var{flag} is 0, otherwise 12933 the checking function is called with @var{os} argument set to 12934 @code{(size_t) -1}. 12935 12936 In addition to this, there are checking built-in functions 12937 @code{__builtin___printf_chk}, @code{__builtin___vprintf_chk}, 12938 @code{__builtin___fprintf_chk} and @code{__builtin___vfprintf_chk}. 12939 These have just one additional argument, @var{flag}, right before 12940 format string @var{fmt}. If the compiler is able to optimize them to 12941 @code{fputc} etc.@: functions, it does, otherwise the checking function 12942 is called and the @var{flag} argument passed to it. 12943 12944 @node Other Builtins 12945 @section Other Built-in Functions Provided by GCC 12946 @cindex built-in functions 12947 @findex __builtin_alloca 12948 @findex __builtin_alloca_with_align 12949 @findex __builtin_alloca_with_align_and_max 12950 @findex __builtin_call_with_static_chain 12951 @findex __builtin_extend_pointer 12952 @findex __builtin_fpclassify 12953 @findex __builtin_has_attribute 12954 @findex __builtin_isfinite 12955 @findex __builtin_isnormal 12956 @findex __builtin_isgreater 12957 @findex __builtin_isgreaterequal 12958 @findex __builtin_isinf_sign 12959 @findex __builtin_isless 12960 @findex __builtin_islessequal 12961 @findex __builtin_islessgreater 12962 @findex __builtin_isunordered 12963 @findex __builtin_object_size 12964 @findex __builtin_powi 12965 @findex __builtin_powif 12966 @findex __builtin_powil 12967 @findex __builtin_speculation_safe_value 12968 @findex _Exit 12969 @findex _exit 12970 @findex abort 12971 @findex abs 12972 @findex acos 12973 @findex acosf 12974 @findex acosh 12975 @findex acoshf 12976 @findex acoshl 12977 @findex acosl 12978 @findex alloca 12979 @findex asin 12980 @findex asinf 12981 @findex asinh 12982 @findex asinhf 12983 @findex asinhl 12984 @findex asinl 12985 @findex atan 12986 @findex atan2 12987 @findex atan2f 12988 @findex atan2l 12989 @findex atanf 12990 @findex atanh 12991 @findex atanhf 12992 @findex atanhl 12993 @findex atanl 12994 @findex bcmp 12995 @findex bzero 12996 @findex cabs 12997 @findex cabsf 12998 @findex cabsl 12999 @findex cacos 13000 @findex cacosf 13001 @findex cacosh 13002 @findex cacoshf 13003 @findex cacoshl 13004 @findex cacosl 13005 @findex calloc 13006 @findex carg 13007 @findex cargf 13008 @findex cargl 13009 @findex casin 13010 @findex casinf 13011 @findex casinh 13012 @findex casinhf 13013 @findex casinhl 13014 @findex casinl 13015 @findex catan 13016 @findex catanf 13017 @findex catanh 13018 @findex catanhf 13019 @findex catanhl 13020 @findex catanl 13021 @findex cbrt 13022 @findex cbrtf 13023 @findex cbrtl 13024 @findex ccos 13025 @findex ccosf 13026 @findex ccosh 13027 @findex ccoshf 13028 @findex ccoshl 13029 @findex ccosl 13030 @findex ceil 13031 @findex ceilf 13032 @findex ceill 13033 @findex cexp 13034 @findex cexpf 13035 @findex cexpl 13036 @findex cimag 13037 @findex cimagf 13038 @findex cimagl 13039 @findex clog 13040 @findex clogf 13041 @findex clogl 13042 @findex clog10 13043 @findex clog10f 13044 @findex clog10l 13045 @findex conj 13046 @findex conjf 13047 @findex conjl 13048 @findex copysign 13049 @findex copysignf 13050 @findex copysignl 13051 @findex cos 13052 @findex cosf 13053 @findex cosh 13054 @findex coshf 13055 @findex coshl 13056 @findex cosl 13057 @findex cpow 13058 @findex cpowf 13059 @findex cpowl 13060 @findex cproj 13061 @findex cprojf 13062 @findex cprojl 13063 @findex creal 13064 @findex crealf 13065 @findex creall 13066 @findex csin 13067 @findex csinf 13068 @findex csinh 13069 @findex csinhf 13070 @findex csinhl 13071 @findex csinl 13072 @findex csqrt 13073 @findex csqrtf 13074 @findex csqrtl 13075 @findex ctan 13076 @findex ctanf 13077 @findex ctanh 13078 @findex ctanhf 13079 @findex ctanhl 13080 @findex ctanl 13081 @findex dcgettext 13082 @findex dgettext 13083 @findex drem 13084 @findex dremf 13085 @findex dreml 13086 @findex erf 13087 @findex erfc 13088 @findex erfcf 13089 @findex erfcl 13090 @findex erff 13091 @findex erfl 13092 @findex exit 13093 @findex exp 13094 @findex exp10 13095 @findex exp10f 13096 @findex exp10l 13097 @findex exp2 13098 @findex exp2f 13099 @findex exp2l 13100 @findex expf 13101 @findex expl 13102 @findex expm1 13103 @findex expm1f 13104 @findex expm1l 13105 @findex fabs 13106 @findex fabsf 13107 @findex fabsl 13108 @findex fdim 13109 @findex fdimf 13110 @findex fdiml 13111 @findex ffs 13112 @findex floor 13113 @findex floorf 13114 @findex floorl 13115 @findex fma 13116 @findex fmaf 13117 @findex fmal 13118 @findex fmax 13119 @findex fmaxf 13120 @findex fmaxl 13121 @findex fmin 13122 @findex fminf 13123 @findex fminl 13124 @findex fmod 13125 @findex fmodf 13126 @findex fmodl 13127 @findex fprintf 13128 @findex fprintf_unlocked 13129 @findex fputs 13130 @findex fputs_unlocked 13131 @findex free 13132 @findex frexp 13133 @findex frexpf 13134 @findex frexpl 13135 @findex fscanf 13136 @findex gamma 13137 @findex gammaf 13138 @findex gammal 13139 @findex gamma_r 13140 @findex gammaf_r 13141 @findex gammal_r 13142 @findex gettext 13143 @findex hypot 13144 @findex hypotf 13145 @findex hypotl 13146 @findex ilogb 13147 @findex ilogbf 13148 @findex ilogbl 13149 @findex imaxabs 13150 @findex index 13151 @findex isalnum 13152 @findex isalpha 13153 @findex isascii 13154 @findex isblank 13155 @findex iscntrl 13156 @findex isdigit 13157 @findex isgraph 13158 @findex islower 13159 @findex isprint 13160 @findex ispunct 13161 @findex isspace 13162 @findex isupper 13163 @findex iswalnum 13164 @findex iswalpha 13165 @findex iswblank 13166 @findex iswcntrl 13167 @findex iswdigit 13168 @findex iswgraph 13169 @findex iswlower 13170 @findex iswprint 13171 @findex iswpunct 13172 @findex iswspace 13173 @findex iswupper 13174 @findex iswxdigit 13175 @findex isxdigit 13176 @findex j0 13177 @findex j0f 13178 @findex j0l 13179 @findex j1 13180 @findex j1f 13181 @findex j1l 13182 @findex jn 13183 @findex jnf 13184 @findex jnl 13185 @findex labs 13186 @findex ldexp 13187 @findex ldexpf 13188 @findex ldexpl 13189 @findex lgamma 13190 @findex lgammaf 13191 @findex lgammal 13192 @findex lgamma_r 13193 @findex lgammaf_r 13194 @findex lgammal_r 13195 @findex llabs 13196 @findex llrint 13197 @findex llrintf 13198 @findex llrintl 13199 @findex llround 13200 @findex llroundf 13201 @findex llroundl 13202 @findex log 13203 @findex log10 13204 @findex log10f 13205 @findex log10l 13206 @findex log1p 13207 @findex log1pf 13208 @findex log1pl 13209 @findex log2 13210 @findex log2f 13211 @findex log2l 13212 @findex logb 13213 @findex logbf 13214 @findex logbl 13215 @findex logf 13216 @findex logl 13217 @findex lrint 13218 @findex lrintf 13219 @findex lrintl 13220 @findex lround 13221 @findex lroundf 13222 @findex lroundl 13223 @findex malloc 13224 @findex memchr 13225 @findex memcmp 13226 @findex memcpy 13227 @findex mempcpy 13228 @findex memset 13229 @findex modf 13230 @findex modff 13231 @findex modfl 13232 @findex nearbyint 13233 @findex nearbyintf 13234 @findex nearbyintl 13235 @findex nextafter 13236 @findex nextafterf 13237 @findex nextafterl 13238 @findex nexttoward 13239 @findex nexttowardf 13240 @findex nexttowardl 13241 @findex pow 13242 @findex pow10 13243 @findex pow10f 13244 @findex pow10l 13245 @findex powf 13246 @findex powl 13247 @findex printf 13248 @findex printf_unlocked 13249 @findex putchar 13250 @findex puts 13251 @findex realloc 13252 @findex remainder 13253 @findex remainderf 13254 @findex remainderl 13255 @findex remquo 13256 @findex remquof 13257 @findex remquol 13258 @findex rindex 13259 @findex rint 13260 @findex rintf 13261 @findex rintl 13262 @findex round 13263 @findex roundf 13264 @findex roundl 13265 @findex scalb 13266 @findex scalbf 13267 @findex scalbl 13268 @findex scalbln 13269 @findex scalblnf 13270 @findex scalblnf 13271 @findex scalbn 13272 @findex scalbnf 13273 @findex scanfnl 13274 @findex signbit 13275 @findex signbitf 13276 @findex signbitl 13277 @findex signbitd32 13278 @findex signbitd64 13279 @findex signbitd128 13280 @findex significand 13281 @findex significandf 13282 @findex significandl 13283 @findex sin 13284 @findex sincos 13285 @findex sincosf 13286 @findex sincosl 13287 @findex sinf 13288 @findex sinh 13289 @findex sinhf 13290 @findex sinhl 13291 @findex sinl 13292 @findex snprintf 13293 @findex sprintf 13294 @findex sqrt 13295 @findex sqrtf 13296 @findex sqrtl 13297 @findex sscanf 13298 @findex stpcpy 13299 @findex stpncpy 13300 @findex strcasecmp 13301 @findex strcat 13302 @findex strchr 13303 @findex strcmp 13304 @findex strcpy 13305 @findex strcspn 13306 @findex strdup 13307 @findex strfmon 13308 @findex strftime 13309 @findex strlen 13310 @findex strncasecmp 13311 @findex strncat 13312 @findex strncmp 13313 @findex strncpy 13314 @findex strndup 13315 @findex strnlen 13316 @findex strpbrk 13317 @findex strrchr 13318 @findex strspn 13319 @findex strstr 13320 @findex tan 13321 @findex tanf 13322 @findex tanh 13323 @findex tanhf 13324 @findex tanhl 13325 @findex tanl 13326 @findex tgamma 13327 @findex tgammaf 13328 @findex tgammal 13329 @findex toascii 13330 @findex tolower 13331 @findex toupper 13332 @findex towlower 13333 @findex towupper 13334 @findex trunc 13335 @findex truncf 13336 @findex truncl 13337 @findex vfprintf 13338 @findex vfscanf 13339 @findex vprintf 13340 @findex vscanf 13341 @findex vsnprintf 13342 @findex vsprintf 13343 @findex vsscanf 13344 @findex y0 13345 @findex y0f 13346 @findex y0l 13347 @findex y1 13348 @findex y1f 13349 @findex y1l 13350 @findex yn 13351 @findex ynf 13352 @findex ynl 13353 13354 GCC provides a large number of built-in functions other than the ones 13355 mentioned above. Some of these are for internal use in the processing 13356 of exceptions or variable-length argument lists and are not 13357 documented here because they may change from time to time; we do not 13358 recommend general use of these functions. 13359 13360 The remaining functions are provided for optimization purposes. 13361 13362 With the exception of built-ins that have library equivalents such as 13363 the standard C library functions discussed below, or that expand to 13364 library calls, GCC built-in functions are always expanded inline and 13365 thus do not have corresponding entry points and their address cannot 13366 be obtained. Attempting to use them in an expression other than 13367 a function call results in a compile-time error. 13368 13369 @opindex fno-builtin 13370 GCC includes built-in versions of many of the functions in the standard 13371 C library. These functions come in two forms: one whose names start with 13372 the @code{__builtin_} prefix, and the other without. Both forms have the 13373 same type (including prototype), the same address (when their address is 13374 taken), and the same meaning as the C library functions even if you specify 13375 the @option{-fno-builtin} option @pxref{C Dialect Options}). Many of these 13376 functions are only optimized in certain cases; if they are not optimized in 13377 a particular case, a call to the library function is emitted. 13378 13379 @opindex ansi 13380 @opindex std 13381 Outside strict ISO C mode (@option{-ansi}, @option{-std=c90}, 13382 @option{-std=c99} or @option{-std=c11}), the functions 13383 @code{_exit}, @code{alloca}, @code{bcmp}, @code{bzero}, 13384 @code{dcgettext}, @code{dgettext}, @code{dremf}, @code{dreml}, 13385 @code{drem}, @code{exp10f}, @code{exp10l}, @code{exp10}, @code{ffsll}, 13386 @code{ffsl}, @code{ffs}, @code{fprintf_unlocked}, 13387 @code{fputs_unlocked}, @code{gammaf}, @code{gammal}, @code{gamma}, 13388 @code{gammaf_r}, @code{gammal_r}, @code{gamma_r}, @code{gettext}, 13389 @code{index}, @code{isascii}, @code{j0f}, @code{j0l}, @code{j0}, 13390 @code{j1f}, @code{j1l}, @code{j1}, @code{jnf}, @code{jnl}, @code{jn}, 13391 @code{lgammaf_r}, @code{lgammal_r}, @code{lgamma_r}, @code{mempcpy}, 13392 @code{pow10f}, @code{pow10l}, @code{pow10}, @code{printf_unlocked}, 13393 @code{rindex}, @code{roundeven}, @code{roundevenf}, @code{roundevenl}, 13394 @code{scalbf}, @code{scalbl}, @code{scalb}, 13395 @code{signbit}, @code{signbitf}, @code{signbitl}, @code{signbitd32}, 13396 @code{signbitd64}, @code{signbitd128}, @code{significandf}, 13397 @code{significandl}, @code{significand}, @code{sincosf}, 13398 @code{sincosl}, @code{sincos}, @code{stpcpy}, @code{stpncpy}, 13399 @code{strcasecmp}, @code{strdup}, @code{strfmon}, @code{strncasecmp}, 13400 @code{strndup}, @code{strnlen}, @code{toascii}, @code{y0f}, @code{y0l}, 13401 @code{y0}, @code{y1f}, @code{y1l}, @code{y1}, @code{ynf}, @code{ynl} and 13402 @code{yn} 13403 may be handled as built-in functions. 13404 All these functions have corresponding versions 13405 prefixed with @code{__builtin_}, which may be used even in strict C90 13406 mode. 13407 13408 The ISO C99 functions 13409 @code{_Exit}, @code{acoshf}, @code{acoshl}, @code{acosh}, @code{asinhf}, 13410 @code{asinhl}, @code{asinh}, @code{atanhf}, @code{atanhl}, @code{atanh}, 13411 @code{cabsf}, @code{cabsl}, @code{cabs}, @code{cacosf}, @code{cacoshf}, 13412 @code{cacoshl}, @code{cacosh}, @code{cacosl}, @code{cacos}, 13413 @code{cargf}, @code{cargl}, @code{carg}, @code{casinf}, @code{casinhf}, 13414 @code{casinhl}, @code{casinh}, @code{casinl}, @code{casin}, 13415 @code{catanf}, @code{catanhf}, @code{catanhl}, @code{catanh}, 13416 @code{catanl}, @code{catan}, @code{cbrtf}, @code{cbrtl}, @code{cbrt}, 13417 @code{ccosf}, @code{ccoshf}, @code{ccoshl}, @code{ccosh}, @code{ccosl}, 13418 @code{ccos}, @code{cexpf}, @code{cexpl}, @code{cexp}, @code{cimagf}, 13419 @code{cimagl}, @code{cimag}, @code{clogf}, @code{clogl}, @code{clog}, 13420 @code{conjf}, @code{conjl}, @code{conj}, @code{copysignf}, @code{copysignl}, 13421 @code{copysign}, @code{cpowf}, @code{cpowl}, @code{cpow}, @code{cprojf}, 13422 @code{cprojl}, @code{cproj}, @code{crealf}, @code{creall}, @code{creal}, 13423 @code{csinf}, @code{csinhf}, @code{csinhl}, @code{csinh}, @code{csinl}, 13424 @code{csin}, @code{csqrtf}, @code{csqrtl}, @code{csqrt}, @code{ctanf}, 13425 @code{ctanhf}, @code{ctanhl}, @code{ctanh}, @code{ctanl}, @code{ctan}, 13426 @code{erfcf}, @code{erfcl}, @code{erfc}, @code{erff}, @code{erfl}, 13427 @code{erf}, @code{exp2f}, @code{exp2l}, @code{exp2}, @code{expm1f}, 13428 @code{expm1l}, @code{expm1}, @code{fdimf}, @code{fdiml}, @code{fdim}, 13429 @code{fmaf}, @code{fmal}, @code{fmaxf}, @code{fmaxl}, @code{fmax}, 13430 @code{fma}, @code{fminf}, @code{fminl}, @code{fmin}, @code{hypotf}, 13431 @code{hypotl}, @code{hypot}, @code{ilogbf}, @code{ilogbl}, @code{ilogb}, 13432 @code{imaxabs}, @code{isblank}, @code{iswblank}, @code{lgammaf}, 13433 @code{lgammal}, @code{lgamma}, @code{llabs}, @code{llrintf}, @code{llrintl}, 13434 @code{llrint}, @code{llroundf}, @code{llroundl}, @code{llround}, 13435 @code{log1pf}, @code{log1pl}, @code{log1p}, @code{log2f}, @code{log2l}, 13436 @code{log2}, @code{logbf}, @code{logbl}, @code{logb}, @code{lrintf}, 13437 @code{lrintl}, @code{lrint}, @code{lroundf}, @code{lroundl}, 13438 @code{lround}, @code{nearbyintf}, @code{nearbyintl}, @code{nearbyint}, 13439 @code{nextafterf}, @code{nextafterl}, @code{nextafter}, 13440 @code{nexttowardf}, @code{nexttowardl}, @code{nexttoward}, 13441 @code{remainderf}, @code{remainderl}, @code{remainder}, @code{remquof}, 13442 @code{remquol}, @code{remquo}, @code{rintf}, @code{rintl}, @code{rint}, 13443 @code{roundf}, @code{roundl}, @code{round}, @code{scalblnf}, 13444 @code{scalblnl}, @code{scalbln}, @code{scalbnf}, @code{scalbnl}, 13445 @code{scalbn}, @code{snprintf}, @code{tgammaf}, @code{tgammal}, 13446 @code{tgamma}, @code{truncf}, @code{truncl}, @code{trunc}, 13447 @code{vfscanf}, @code{vscanf}, @code{vsnprintf} and @code{vsscanf} 13448 are handled as built-in functions 13449 except in strict ISO C90 mode (@option{-ansi} or @option{-std=c90}). 13450 13451 There are also built-in versions of the ISO C99 functions 13452 @code{acosf}, @code{acosl}, @code{asinf}, @code{asinl}, @code{atan2f}, 13453 @code{atan2l}, @code{atanf}, @code{atanl}, @code{ceilf}, @code{ceill}, 13454 @code{cosf}, @code{coshf}, @code{coshl}, @code{cosl}, @code{expf}, 13455 @code{expl}, @code{fabsf}, @code{fabsl}, @code{floorf}, @code{floorl}, 13456 @code{fmodf}, @code{fmodl}, @code{frexpf}, @code{frexpl}, @code{ldexpf}, 13457 @code{ldexpl}, @code{log10f}, @code{log10l}, @code{logf}, @code{logl}, 13458 @code{modfl}, @code{modff}, @code{powf}, @code{powl}, @code{sinf}, 13459 @code{sinhf}, @code{sinhl}, @code{sinl}, @code{sqrtf}, @code{sqrtl}, 13460 @code{tanf}, @code{tanhf}, @code{tanhl} and @code{tanl} 13461 that are recognized in any mode since ISO C90 reserves these names for 13462 the purpose to which ISO C99 puts them. All these functions have 13463 corresponding versions prefixed with @code{__builtin_}. 13464 13465 There are also built-in functions @code{__builtin_fabsf@var{n}}, 13466 @code{__builtin_fabsf@var{n}x}, @code{__builtin_copysignf@var{n}} and 13467 @code{__builtin_copysignf@var{n}x}, corresponding to the TS 18661-3 13468 functions @code{fabsf@var{n}}, @code{fabsf@var{n}x}, 13469 @code{copysignf@var{n}} and @code{copysignf@var{n}x}, for supported 13470 types @code{_Float@var{n}} and @code{_Float@var{n}x}. 13471 13472 There are also GNU extension functions @code{clog10}, @code{clog10f} and 13473 @code{clog10l} which names are reserved by ISO C99 for future use. 13474 All these functions have versions prefixed with @code{__builtin_}. 13475 13476 The ISO C94 functions 13477 @code{iswalnum}, @code{iswalpha}, @code{iswcntrl}, @code{iswdigit}, 13478 @code{iswgraph}, @code{iswlower}, @code{iswprint}, @code{iswpunct}, 13479 @code{iswspace}, @code{iswupper}, @code{iswxdigit}, @code{towlower} and 13480 @code{towupper} 13481 are handled as built-in functions 13482 except in strict ISO C90 mode (@option{-ansi} or @option{-std=c90}). 13483 13484 The ISO C90 functions 13485 @code{abort}, @code{abs}, @code{acos}, @code{asin}, @code{atan2}, 13486 @code{atan}, @code{calloc}, @code{ceil}, @code{cosh}, @code{cos}, 13487 @code{exit}, @code{exp}, @code{fabs}, @code{floor}, @code{fmod}, 13488 @code{fprintf}, @code{fputs}, @code{free}, @code{frexp}, @code{fscanf}, 13489 @code{isalnum}, @code{isalpha}, @code{iscntrl}, @code{isdigit}, 13490 @code{isgraph}, @code{islower}, @code{isprint}, @code{ispunct}, 13491 @code{isspace}, @code{isupper}, @code{isxdigit}, @code{tolower}, 13492 @code{toupper}, @code{labs}, @code{ldexp}, @code{log10}, @code{log}, 13493 @code{malloc}, @code{memchr}, @code{memcmp}, @code{memcpy}, 13494 @code{memset}, @code{modf}, @code{pow}, @code{printf}, @code{putchar}, 13495 @code{puts}, @code{realloc}, @code{scanf}, @code{sinh}, @code{sin}, 13496 @code{snprintf}, @code{sprintf}, @code{sqrt}, @code{sscanf}, @code{strcat}, 13497 @code{strchr}, @code{strcmp}, @code{strcpy}, @code{strcspn}, 13498 @code{strlen}, @code{strncat}, @code{strncmp}, @code{strncpy}, 13499 @code{strpbrk}, @code{strrchr}, @code{strspn}, @code{strstr}, 13500 @code{tanh}, @code{tan}, @code{vfprintf}, @code{vprintf} and @code{vsprintf} 13501 are all recognized as built-in functions unless 13502 @option{-fno-builtin} is specified (or @option{-fno-builtin-@var{function}} 13503 is specified for an individual function). All of these functions have 13504 corresponding versions prefixed with @code{__builtin_}. 13505 13506 GCC provides built-in versions of the ISO C99 floating-point comparison 13507 macros that avoid raising exceptions for unordered operands. They have 13508 the same names as the standard macros ( @code{isgreater}, 13509 @code{isgreaterequal}, @code{isless}, @code{islessequal}, 13510 @code{islessgreater}, and @code{isunordered}) , with @code{__builtin_} 13511 prefixed. We intend for a library implementor to be able to simply 13512 @code{#define} each standard macro to its built-in equivalent. 13513 In the same fashion, GCC provides @code{fpclassify}, @code{isfinite}, 13514 @code{isinf_sign}, @code{isnormal} and @code{signbit} built-ins used with 13515 @code{__builtin_} prefixed. The @code{isinf} and @code{isnan} 13516 built-in functions appear both with and without the @code{__builtin_} prefix. 13517 13518 GCC provides built-in versions of the ISO C99 floating-point rounding and 13519 exceptions handling functions @code{fegetround}, @code{feclearexcept} and 13520 @code{feraiseexcept}. They may not be available for all targets, and because 13521 they need close interaction with libc internal values, they may not be available 13522 for all target libcs, but in all cases they will gracefully fallback to libc 13523 calls. These built-in functions appear both with and without the 13524 @code{__builtin_} prefix. 13525 13526 @deftypefn {Built-in Function} void *__builtin_alloca (size_t size) 13527 The @code{__builtin_alloca} function must be called at block scope. 13528 The function allocates an object @var{size} bytes large on the stack 13529 of the calling function. The object is aligned on the default stack 13530 alignment boundary for the target determined by the 13531 @code{__BIGGEST_ALIGNMENT__} macro. The @code{__builtin_alloca} 13532 function returns a pointer to the first byte of the allocated object. 13533 The lifetime of the allocated object ends just before the calling 13534 function returns to its caller. This is so even when 13535 @code{__builtin_alloca} is called within a nested block. 13536 13537 For example, the following function allocates eight objects of @code{n} 13538 bytes each on the stack, storing a pointer to each in consecutive elements 13539 of the array @code{a}. It then passes the array to function @code{g} 13540 which can safely use the storage pointed to by each of the array elements. 13541 13542 @smallexample 13543 void f (unsigned n) 13544 @{ 13545 void *a [8]; 13546 for (int i = 0; i != 8; ++i) 13547 a [i] = __builtin_alloca (n); 13548 13549 g (a, n); // @r{safe} 13550 @} 13551 @end smallexample 13552 13553 Since the @code{__builtin_alloca} function doesn't validate its argument 13554 it is the responsibility of its caller to make sure the argument doesn't 13555 cause it to exceed the stack size limit. 13556 The @code{__builtin_alloca} function is provided to make it possible to 13557 allocate on the stack arrays of bytes with an upper bound that may be 13558 computed at run time. Since C99 Variable Length Arrays offer 13559 similar functionality under a portable, more convenient, and safer 13560 interface they are recommended instead, in both C99 and C++ programs 13561 where GCC provides them as an extension. 13562 @xref{Variable Length}, for details. 13563 13564 @end deftypefn 13565 13566 @deftypefn {Built-in Function} void *__builtin_alloca_with_align (size_t size, size_t alignment) 13567 The @code{__builtin_alloca_with_align} function must be called at block 13568 scope. The function allocates an object @var{size} bytes large on 13569 the stack of the calling function. The allocated object is aligned on 13570 the boundary specified by the argument @var{alignment} whose unit is given 13571 in bits (not bytes). The @var{size} argument must be positive and not 13572 exceed the stack size limit. The @var{alignment} argument must be a constant 13573 integer expression that evaluates to a power of 2 greater than or equal to 13574 @code{CHAR_BIT} and less than some unspecified maximum. Invocations 13575 with other values are rejected with an error indicating the valid bounds. 13576 The function returns a pointer to the first byte of the allocated object. 13577 The lifetime of the allocated object ends at the end of the block in which 13578 the function was called. The allocated storage is released no later than 13579 just before the calling function returns to its caller, but may be released 13580 at the end of the block in which the function was called. 13581 13582 For example, in the following function the call to @code{g} is unsafe 13583 because when @code{overalign} is non-zero, the space allocated by 13584 @code{__builtin_alloca_with_align} may have been released at the end 13585 of the @code{if} statement in which it was called. 13586 13587 @smallexample 13588 void f (unsigned n, bool overalign) 13589 @{ 13590 void *p; 13591 if (overalign) 13592 p = __builtin_alloca_with_align (n, 64 /* bits */); 13593 else 13594 p = __builtin_alloc (n); 13595 13596 g (p, n); // @r{unsafe} 13597 @} 13598 @end smallexample 13599 13600 Since the @code{__builtin_alloca_with_align} function doesn't validate its 13601 @var{size} argument it is the responsibility of its caller to make sure 13602 the argument doesn't cause it to exceed the stack size limit. 13603 The @code{__builtin_alloca_with_align} function is provided to make 13604 it possible to allocate on the stack overaligned arrays of bytes with 13605 an upper bound that may be computed at run time. Since C99 13606 Variable Length Arrays offer the same functionality under 13607 a portable, more convenient, and safer interface they are recommended 13608 instead, in both C99 and C++ programs where GCC provides them as 13609 an extension. @xref{Variable Length}, for details. 13610 13611 @end deftypefn 13612 13613 @deftypefn {Built-in Function} void *__builtin_alloca_with_align_and_max (size_t size, size_t alignment, size_t max_size) 13614 Similar to @code{__builtin_alloca_with_align} but takes an extra argument 13615 specifying an upper bound for @var{size} in case its value cannot be computed 13616 at compile time, for use by @option{-fstack-usage}, @option{-Wstack-usage} 13617 and @option{-Walloca-larger-than}. @var{max_size} must be a constant integer 13618 expression, it has no effect on code generation and no attempt is made to 13619 check its compatibility with @var{size}. 13620 13621 @end deftypefn 13622 13623 @deftypefn {Built-in Function} bool __builtin_has_attribute (@var{type-or-expression}, @var{attribute}) 13624 The @code{__builtin_has_attribute} function evaluates to an integer constant 13625 expression equal to @code{true} if the symbol or type referenced by 13626 the @var{type-or-expression} argument has been declared with 13627 the @var{attribute} referenced by the second argument. For 13628 an @var{type-or-expression} argument that does not reference a symbol, 13629 since attributes do not apply to expressions the built-in consider 13630 the type of the argument. Neither argument is evaluated. 13631 The @var{type-or-expression} argument is subject to the same 13632 restrictions as the argument to @code{typeof} (@pxref{Typeof}). The 13633 @var{attribute} argument is an attribute name optionally followed by 13634 a comma-separated list of arguments enclosed in parentheses. Both forms 13635 of attribute names---with and without double leading and trailing 13636 underscores---are recognized. @xref{Attribute Syntax}, for details. 13637 When no attribute arguments are specified for an attribute that expects 13638 one or more arguments the function returns @code{true} if 13639 @var{type-or-expression} has been declared with the attribute regardless 13640 of the attribute argument values. Arguments provided for an attribute 13641 that expects some are validated and matched up to the provided number. 13642 The function returns @code{true} if all provided arguments match. For 13643 example, the first call to the function below evaluates to @code{true} 13644 because @code{x} is declared with the @code{aligned} attribute but 13645 the second call evaluates to @code{false} because @code{x} is declared 13646 @code{aligned (8)} and not @code{aligned (4)}. 13647 13648 @smallexample 13649 __attribute__ ((aligned (8))) int x; 13650 _Static_assert (__builtin_has_attribute (x, aligned), "aligned"); 13651 _Static_assert (!__builtin_has_attribute (x, aligned (4)), "aligned (4)"); 13652 @end smallexample 13653 13654 Due to a limitation the @code{__builtin_has_attribute} function returns 13655 @code{false} for the @code{mode} attribute even if the type or variable 13656 referenced by the @var{type-or-expression} argument was declared with one. 13657 The function is also not supported with labels, and in C with enumerators. 13658 13659 Note that unlike the @code{__has_attribute} preprocessor operator which 13660 is suitable for use in @code{#if} preprocessing directives 13661 @code{__builtin_has_attribute} is an intrinsic function that is not 13662 recognized in such contexts. 13663 13664 @end deftypefn 13665 13666 @deftypefn {Built-in Function} @var{type} __builtin_speculation_safe_value (@var{type} val, @var{type} failval) 13667 13668 This built-in function can be used to help mitigate against unsafe 13669 speculative execution. @var{type} may be any integral type or any 13670 pointer type. 13671 13672 @enumerate 13673 @item 13674 If the CPU is not speculatively executing the code, then @var{val} 13675 is returned. 13676 @item 13677 If the CPU is executing speculatively then either: 13678 @itemize 13679 @item 13680 The function may cause execution to pause until it is known that the 13681 code is no-longer being executed speculatively (in which case 13682 @var{val} can be returned, as above); or 13683 @item 13684 The function may use target-dependent speculation tracking state to cause 13685 @var{failval} to be returned when it is known that speculative 13686 execution has incorrectly predicted a conditional branch operation. 13687 @end itemize 13688 @end enumerate 13689 13690 The second argument, @var{failval}, is optional and defaults to zero 13691 if omitted. 13692 13693 GCC defines the preprocessor macro 13694 @code{__HAVE_BUILTIN_SPECULATION_SAFE_VALUE} for targets that have been 13695 updated to support this builtin. 13696 13697 The built-in function can be used where a variable appears to be used in a 13698 safe way, but the CPU, due to speculative execution may temporarily ignore 13699 the bounds checks. Consider, for example, the following function: 13700 13701 @smallexample 13702 int array[500]; 13703 int f (unsigned untrusted_index) 13704 @{ 13705 if (untrusted_index < 500) 13706 return array[untrusted_index]; 13707 return 0; 13708 @} 13709 @end smallexample 13710 13711 If the function is called repeatedly with @code{untrusted_index} less 13712 than the limit of 500, then a branch predictor will learn that the 13713 block of code that returns a value stored in @code{array} will be 13714 executed. If the function is subsequently called with an 13715 out-of-range value it will still try to execute that block of code 13716 first until the CPU determines that the prediction was incorrect 13717 (the CPU will unwind any incorrect operations at that point). 13718 However, depending on how the result of the function is used, it might be 13719 possible to leave traces in the cache that can reveal what was stored 13720 at the out-of-bounds location. The built-in function can be used to 13721 provide some protection against leaking data in this way by changing 13722 the code to: 13723 13724 @smallexample 13725 int array[500]; 13726 int f (unsigned untrusted_index) 13727 @{ 13728 if (untrusted_index < 500) 13729 return array[__builtin_speculation_safe_value (untrusted_index)]; 13730 return 0; 13731 @} 13732 @end smallexample 13733 13734 The built-in function will either cause execution to stall until the 13735 conditional branch has been fully resolved, or it may permit 13736 speculative execution to continue, but using 0 instead of 13737 @code{untrusted_value} if that exceeds the limit. 13738 13739 If accessing any memory location is potentially unsafe when speculative 13740 execution is incorrect, then the code can be rewritten as 13741 13742 @smallexample 13743 int array[500]; 13744 int f (unsigned untrusted_index) 13745 @{ 13746 if (untrusted_index < 500) 13747 return *__builtin_speculation_safe_value (&array[untrusted_index], NULL); 13748 return 0; 13749 @} 13750 @end smallexample 13751 13752 which will cause a @code{NULL} pointer to be used for the unsafe case. 13753 13754 @end deftypefn 13755 13756 @deftypefn {Built-in Function} int __builtin_types_compatible_p (@var{type1}, @var{type2}) 13757 13758 You can use the built-in function @code{__builtin_types_compatible_p} to 13759 determine whether two types are the same. 13760 13761 This built-in function returns 1 if the unqualified versions of the 13762 types @var{type1} and @var{type2} (which are types, not expressions) are 13763 compatible, 0 otherwise. The result of this built-in function can be 13764 used in integer constant expressions. 13765 13766 This built-in function ignores top level qualifiers (e.g., @code{const}, 13767 @code{volatile}). For example, @code{int} is equivalent to @code{const 13768 int}. 13769 13770 The type @code{int[]} and @code{int[5]} are compatible. On the other 13771 hand, @code{int} and @code{char *} are not compatible, even if the size 13772 of their types, on the particular architecture are the same. Also, the 13773 amount of pointer indirection is taken into account when determining 13774 similarity. Consequently, @code{short *} is not similar to 13775 @code{short **}. Furthermore, two types that are typedefed are 13776 considered compatible if their underlying types are compatible. 13777 13778 An @code{enum} type is not considered to be compatible with another 13779 @code{enum} type even if both are compatible with the same integer 13780 type; this is what the C standard specifies. 13781 For example, @code{enum @{foo, bar@}} is not similar to 13782 @code{enum @{hot, dog@}}. 13783 13784 You typically use this function in code whose execution varies 13785 depending on the arguments' types. For example: 13786 13787 @smallexample 13788 #define foo(x) \ 13789 (@{ \ 13790 typeof (x) tmp = (x); \ 13791 if (__builtin_types_compatible_p (typeof (x), long double)) \ 13792 tmp = foo_long_double (tmp); \ 13793 else if (__builtin_types_compatible_p (typeof (x), double)) \ 13794 tmp = foo_double (tmp); \ 13795 else if (__builtin_types_compatible_p (typeof (x), float)) \ 13796 tmp = foo_float (tmp); \ 13797 else \ 13798 abort (); \ 13799 tmp; \ 13800 @}) 13801 @end smallexample 13802 13803 @emph{Note:} This construct is only available for C@. 13804 13805 @end deftypefn 13806 13807 @deftypefn {Built-in Function} @var{type} __builtin_call_with_static_chain (@var{call_exp}, @var{pointer_exp}) 13808 13809 The @var{call_exp} expression must be a function call, and the 13810 @var{pointer_exp} expression must be a pointer. The @var{pointer_exp} 13811 is passed to the function call in the target's static chain location. 13812 The result of builtin is the result of the function call. 13813 13814 @emph{Note:} This builtin is only available for C@. 13815 This builtin can be used to call Go closures from C. 13816 13817 @end deftypefn 13818 13819 @deftypefn {Built-in Function} @var{type} __builtin_choose_expr (@var{const_exp}, @var{exp1}, @var{exp2}) 13820 13821 You can use the built-in function @code{__builtin_choose_expr} to 13822 evaluate code depending on the value of a constant expression. This 13823 built-in function returns @var{exp1} if @var{const_exp}, which is an 13824 integer constant expression, is nonzero. Otherwise it returns @var{exp2}. 13825 13826 This built-in function is analogous to the @samp{? :} operator in C, 13827 except that the expression returned has its type unaltered by promotion 13828 rules. Also, the built-in function does not evaluate the expression 13829 that is not chosen. For example, if @var{const_exp} evaluates to @code{true}, 13830 @var{exp2} is not evaluated even if it has side effects. 13831 13832 This built-in function can return an lvalue if the chosen argument is an 13833 lvalue. 13834 13835 If @var{exp1} is returned, the return type is the same as @var{exp1}'s 13836 type. Similarly, if @var{exp2} is returned, its return type is the same 13837 as @var{exp2}. 13838 13839 Example: 13840 13841 @smallexample 13842 #define foo(x) \ 13843 __builtin_choose_expr ( \ 13844 __builtin_types_compatible_p (typeof (x), double), \ 13845 foo_double (x), \ 13846 __builtin_choose_expr ( \ 13847 __builtin_types_compatible_p (typeof (x), float), \ 13848 foo_float (x), \ 13849 /* @r{The void expression results in a compile-time error} \ 13850 @r{when assigning the result to something.} */ \ 13851 (void)0)) 13852 @end smallexample 13853 13854 @emph{Note:} This construct is only available for C@. Furthermore, the 13855 unused expression (@var{exp1} or @var{exp2} depending on the value of 13856 @var{const_exp}) may still generate syntax errors. This may change in 13857 future revisions. 13858 13859 @end deftypefn 13860 13861 @deftypefn {Built-in Function} @var{type} __builtin_tgmath (@var{functions}, @var{arguments}) 13862 13863 The built-in function @code{__builtin_tgmath}, available only for C 13864 and Objective-C, calls a function determined according to the rules of 13865 @code{<tgmath.h>} macros. It is intended to be used in 13866 implementations of that header, so that expansions of macros from that 13867 header only expand each of their arguments once, to avoid problems 13868 when calls to such macros are nested inside the arguments of other 13869 calls to such macros; in addition, it results in better diagnostics 13870 for invalid calls to @code{<tgmath.h>} macros than implementations 13871 using other GNU C language features. For example, the @code{pow} 13872 type-generic macro might be defined as: 13873 13874 @smallexample 13875 #define pow(a, b) __builtin_tgmath (powf, pow, powl, \ 13876 cpowf, cpow, cpowl, a, b) 13877 @end smallexample 13878 13879 The arguments to @code{__builtin_tgmath} are at least two pointers to 13880 functions, followed by the arguments to the type-generic macro (which 13881 will be passed as arguments to the selected function). All the 13882 pointers to functions must be pointers to prototyped functions, none 13883 of which may have variable arguments, and all of which must have the 13884 same number of parameters; the number of parameters of the first 13885 function determines how many arguments to @code{__builtin_tgmath} are 13886 interpreted as function pointers, and how many as the arguments to the 13887 called function. 13888 13889 The types of the specified functions must all be different, but 13890 related to each other in the same way as a set of functions that may 13891 be selected between by a macro in @code{<tgmath.h>}. This means that 13892 the functions are parameterized by a floating-point type @var{t}, 13893 different for each such function. The function return types may all 13894 be the same type, or they may be @var{t} for each function, or they 13895 may be the real type corresponding to @var{t} for each function (if 13896 some of the types @var{t} are complex). Likewise, for each parameter 13897 position, the type of the parameter in that position may always be the 13898 same type, or may be @var{t} for each function (this case must apply 13899 for at least one parameter position), or may be the real type 13900 corresponding to @var{t} for each function. 13901 13902 The standard rules for @code{<tgmath.h>} macros are used to find a 13903 common type @var{u} from the types of the arguments for parameters 13904 whose types vary between the functions; complex integer types (a GNU 13905 extension) are treated like @code{_Complex double} for this purpose 13906 (or @code{_Complex _Float64} if all the function return types are the 13907 same @code{_Float@var{n}} or @code{_Float@var{n}x} type). 13908 If the function return types vary, or are all the same integer type, 13909 the function called is the one for which @var{t} is @var{u}, and it is 13910 an error if there is no such function. If the function return types 13911 are all the same floating-point type, the type-generic macro is taken 13912 to be one of those from TS 18661 that rounds the result to a narrower 13913 type; if there is a function for which @var{t} is @var{u}, it is 13914 called, and otherwise the first function, if any, for which @var{t} 13915 has at least the range and precision of @var{u} is called, and it is 13916 an error if there is no such function. 13917 13918 @end deftypefn 13919 13920 @deftypefn {Built-in Function} int __builtin_constant_p (@var{exp}) 13921 You can use the built-in function @code{__builtin_constant_p} to 13922 determine if a value is known to be constant at compile time and hence 13923 that GCC can perform constant-folding on expressions involving that 13924 value. The argument of the function is the value to test. The function 13925 returns the integer 1 if the argument is known to be a compile-time 13926 constant and 0 if it is not known to be a compile-time constant. A 13927 return of 0 does not indicate that the value is @emph{not} a constant, 13928 but merely that GCC cannot prove it is a constant with the specified 13929 value of the @option{-O} option. 13930 13931 You typically use this function in an embedded application where 13932 memory is a critical resource. If you have some complex calculation, 13933 you may want it to be folded if it involves constants, but need to call 13934 a function if it does not. For example: 13935 13936 @smallexample 13937 #define Scale_Value(X) \ 13938 (__builtin_constant_p (X) \ 13939 ? ((X) * SCALE + OFFSET) : Scale (X)) 13940 @end smallexample 13941 13942 You may use this built-in function in either a macro or an inline 13943 function. However, if you use it in an inlined function and pass an 13944 argument of the function as the argument to the built-in, GCC 13945 never returns 1 when you call the inline function with a string constant 13946 or compound literal (@pxref{Compound Literals}) and does not return 1 13947 when you pass a constant numeric value to the inline function unless you 13948 specify the @option{-O} option. 13949 13950 You may also use @code{__builtin_constant_p} in initializers for static 13951 data. For instance, you can write 13952 13953 @smallexample 13954 static const int table[] = @{ 13955 __builtin_constant_p (EXPRESSION) ? (EXPRESSION) : -1, 13956 /* @r{@dots{}} */ 13957 @}; 13958 @end smallexample 13959 13960 @noindent 13961 This is an acceptable initializer even if @var{EXPRESSION} is not a 13962 constant expression, including the case where 13963 @code{__builtin_constant_p} returns 1 because @var{EXPRESSION} can be 13964 folded to a constant but @var{EXPRESSION} contains operands that are 13965 not otherwise permitted in a static initializer (for example, 13966 @code{0 && foo ()}). GCC must be more conservative about evaluating the 13967 built-in in this case, because it has no opportunity to perform 13968 optimization. 13969 @end deftypefn 13970 13971 @deftypefn {Built-in Function} bool __builtin_is_constant_evaluated (void) 13972 The @code{__builtin_is_constant_evaluated} function is available only 13973 in C++. The built-in is intended to be used by implementations of 13974 the @code{std::is_constant_evaluated} C++ function. Programs should make 13975 use of the latter function rather than invoking the built-in directly. 13976 13977 The main use case of the built-in is to determine whether a @code{constexpr} 13978 function is being called in a @code{constexpr} context. A call to 13979 the function evaluates to a core constant expression with the value 13980 @code{true} if and only if it occurs within the evaluation of an expression 13981 or conversion that is manifestly constant-evaluated as defined in the C++ 13982 standard. Manifestly constant-evaluated contexts include constant-expressions, 13983 the conditions of @code{constexpr if} statements, constraint-expressions, and 13984 initializers of variables usable in constant expressions. For more details 13985 refer to the latest revision of the C++ standard. 13986 @end deftypefn 13987 13988 @deftypefn {Built-in Function} void __builtin_clear_padding (@var{ptr}) 13989 The built-in function @code{__builtin_clear_padding} function clears 13990 padding bits inside of the object representation of object pointed by 13991 @var{ptr}, which has to be a pointer. The value representation of the 13992 object is not affected. The type of the object is assumed to be the type 13993 the pointer points to. Inside of a union, the only cleared bits are 13994 bits that are padding bits for all the union members. 13995 13996 This built-in-function is useful if the padding bits of an object might 13997 have intederminate values and the object representation needs to be 13998 bitwise compared to some other object, for example for atomic operations. 13999 14000 For C++, @var{ptr} argument type should be pointer to trivially-copyable 14001 type, unless the argument is address of a variable or parameter, because 14002 otherwise it isn't known if the type isn't just a base class whose padding 14003 bits are reused or laid out differently in a derived class. 14004 @end deftypefn 14005 14006 @deftypefn {Built-in Function} @var{type} __builtin_bit_cast (@var{type}, @var{arg}) 14007 The @code{__builtin_bit_cast} function is available only 14008 in C++. The built-in is intended to be used by implementations of 14009 the @code{std::bit_cast} C++ template function. Programs should make 14010 use of the latter function rather than invoking the built-in directly. 14011 14012 This built-in function allows reinterpreting the bits of the @var{arg} 14013 argument as if it had type @var{type}. @var{type} and the type of the 14014 @var{arg} argument need to be trivially copyable types with the same size. 14015 When manifestly constant-evaluated, it performs extra diagnostics required 14016 for @code{std::bit_cast} and returns a constant expression if @var{arg} 14017 is a constant expression. For more details 14018 refer to the latest revision of the C++ standard. 14019 @end deftypefn 14020 14021 @deftypefn {Built-in Function} long __builtin_expect (long @var{exp}, long @var{c}) 14022 @opindex fprofile-arcs 14023 You may use @code{__builtin_expect} to provide the compiler with 14024 branch prediction information. In general, you should prefer to 14025 use actual profile feedback for this (@option{-fprofile-arcs}), as 14026 programmers are notoriously bad at predicting how their programs 14027 actually perform. However, there are applications in which this 14028 data is hard to collect. 14029 14030 The return value is the value of @var{exp}, which should be an integral 14031 expression. The semantics of the built-in are that it is expected that 14032 @var{exp} == @var{c}. For example: 14033 14034 @smallexample 14035 if (__builtin_expect (x, 0)) 14036 foo (); 14037 @end smallexample 14038 14039 @noindent 14040 indicates that we do not expect to call @code{foo}, since 14041 we expect @code{x} to be zero. Since you are limited to integral 14042 expressions for @var{exp}, you should use constructions such as 14043 14044 @smallexample 14045 if (__builtin_expect (ptr != NULL, 1)) 14046 foo (*ptr); 14047 @end smallexample 14048 14049 @noindent 14050 when testing pointer or floating-point values. 14051 14052 For the purposes of branch prediction optimizations, the probability that 14053 a @code{__builtin_expect} expression is @code{true} is controlled by GCC's 14054 @code{builtin-expect-probability} parameter, which defaults to 90%. 14055 14056 You can also use @code{__builtin_expect_with_probability} to explicitly 14057 assign a probability value to individual expressions. If the built-in 14058 is used in a loop construct, the provided probability will influence 14059 the expected number of iterations made by loop optimizations. 14060 @end deftypefn 14061 14062 @deftypefn {Built-in Function} long __builtin_expect_with_probability 14063 (long @var{exp}, long @var{c}, double @var{probability}) 14064 14065 This function has the same semantics as @code{__builtin_expect}, 14066 but the caller provides the expected probability that @var{exp} == @var{c}. 14067 The last argument, @var{probability}, is a floating-point value in the 14068 range 0.0 to 1.0, inclusive. The @var{probability} argument must be 14069 constant floating-point expression. 14070 @end deftypefn 14071 14072 @deftypefn {Built-in Function} void __builtin_trap (void) 14073 This function causes the program to exit abnormally. GCC implements 14074 this function by using a target-dependent mechanism (such as 14075 intentionally executing an illegal instruction) or by calling 14076 @code{abort}. The mechanism used may vary from release to release so 14077 you should not rely on any particular implementation. 14078 @end deftypefn 14079 14080 @deftypefn {Built-in Function} void __builtin_unreachable (void) 14081 If control flow reaches the point of the @code{__builtin_unreachable}, 14082 the program is undefined. It is useful in situations where the 14083 compiler cannot deduce the unreachability of the code. 14084 14085 One such case is immediately following an @code{asm} statement that 14086 either never terminates, or one that transfers control elsewhere 14087 and never returns. In this example, without the 14088 @code{__builtin_unreachable}, GCC issues a warning that control 14089 reaches the end of a non-void function. It also generates code 14090 to return after the @code{asm}. 14091 14092 @smallexample 14093 int f (int c, int v) 14094 @{ 14095 if (c) 14096 @{ 14097 return v; 14098 @} 14099 else 14100 @{ 14101 asm("jmp error_handler"); 14102 __builtin_unreachable (); 14103 @} 14104 @} 14105 @end smallexample 14106 14107 @noindent 14108 Because the @code{asm} statement unconditionally transfers control out 14109 of the function, control never reaches the end of the function 14110 body. The @code{__builtin_unreachable} is in fact unreachable and 14111 communicates this fact to the compiler. 14112 14113 Another use for @code{__builtin_unreachable} is following a call a 14114 function that never returns but that is not declared 14115 @code{__attribute__((noreturn))}, as in this example: 14116 14117 @smallexample 14118 void function_that_never_returns (void); 14119 14120 int g (int c) 14121 @{ 14122 if (c) 14123 @{ 14124 return 1; 14125 @} 14126 else 14127 @{ 14128 function_that_never_returns (); 14129 __builtin_unreachable (); 14130 @} 14131 @} 14132 @end smallexample 14133 14134 @end deftypefn 14135 14136 @deftypefn {Built-in Function} @var{type} __builtin_assoc_barrier (@var{type} @var{expr}) 14137 This built-in inhibits re-association of the floating-point expression 14138 @var{expr} with expressions consuming the return value of the built-in. The 14139 expression @var{expr} itself can be reordered, and the whole expression 14140 @var{expr} can be reordered with operands after the barrier. The barrier is 14141 only relevant when @code{-fassociative-math} is active, since otherwise 14142 floating-point is not treated as associative. 14143 14144 @smallexample 14145 float x0 = a + b - b; 14146 float x1 = __builtin_assoc_barrier(a + b) - b; 14147 @end smallexample 14148 14149 @noindent 14150 means that, with @code{-fassociative-math}, @code{x0} can be optimized to 14151 @code{x0 = a} but @code{x1} cannot. 14152 @end deftypefn 14153 14154 @deftypefn {Built-in Function} {void *} __builtin_assume_aligned (const void *@var{exp}, size_t @var{align}, ...) 14155 This function returns its first argument, and allows the compiler 14156 to assume that the returned pointer is at least @var{align} bytes 14157 aligned. This built-in can have either two or three arguments, 14158 if it has three, the third argument should have integer type, and 14159 if it is nonzero means misalignment offset. For example: 14160 14161 @smallexample 14162 void *x = __builtin_assume_aligned (arg, 16); 14163 @end smallexample 14164 14165 @noindent 14166 means that the compiler can assume @code{x}, set to @code{arg}, is at least 14167 16-byte aligned, while: 14168 14169 @smallexample 14170 void *x = __builtin_assume_aligned (arg, 32, 8); 14171 @end smallexample 14172 14173 @noindent 14174 means that the compiler can assume for @code{x}, set to @code{arg}, that 14175 @code{(char *) x - 8} is 32-byte aligned. 14176 @end deftypefn 14177 14178 @deftypefn {Built-in Function} int __builtin_LINE () 14179 This function is the equivalent of the preprocessor @code{__LINE__} 14180 macro and returns a constant integer expression that evaluates to 14181 the line number of the invocation of the built-in. When used as a C++ 14182 default argument for a function @var{F}, it returns the line number 14183 of the call to @var{F}. 14184 @end deftypefn 14185 14186 @deftypefn {Built-in Function} {const char *} __builtin_FUNCTION () 14187 This function is the equivalent of the @code{__FUNCTION__} symbol 14188 and returns an address constant pointing to the name of the function 14189 from which the built-in was invoked, or the empty string if 14190 the invocation is not at function scope. When used as a C++ default 14191 argument for a function @var{F}, it returns the name of @var{F}'s 14192 caller or the empty string if the call was not made at function 14193 scope. 14194 @end deftypefn 14195 14196 @deftypefn {Built-in Function} {const char *} __builtin_FILE () 14197 This function is the equivalent of the preprocessor @code{__FILE__} 14198 macro and returns an address constant pointing to the file name 14199 containing the invocation of the built-in, or the empty string if 14200 the invocation is not at function scope. When used as a C++ default 14201 argument for a function @var{F}, it returns the file name of the call 14202 to @var{F} or the empty string if the call was not made at function 14203 scope. 14204 14205 For example, in the following, each call to function @code{foo} will 14206 print a line similar to @code{"file.c:123: foo: message"} with the name 14207 of the file and the line number of the @code{printf} call, the name of 14208 the function @code{foo}, followed by the word @code{message}. 14209 14210 @smallexample 14211 const char* 14212 function (const char *func = __builtin_FUNCTION ()) 14213 @{ 14214 return func; 14215 @} 14216 14217 void foo (void) 14218 @{ 14219 printf ("%s:%i: %s: message\n", file (), line (), function ()); 14220 @} 14221 @end smallexample 14222 14223 @end deftypefn 14224 14225 @deftypefn {Built-in Function} void __builtin___clear_cache (void *@var{begin}, void *@var{end}) 14226 This function is used to flush the processor's instruction cache for 14227 the region of memory between @var{begin} inclusive and @var{end} 14228 exclusive. Some targets require that the instruction cache be 14229 flushed, after modifying memory containing code, in order to obtain 14230 deterministic behavior. 14231 14232 If the target does not require instruction cache flushes, 14233 @code{__builtin___clear_cache} has no effect. Otherwise either 14234 instructions are emitted in-line to clear the instruction cache or a 14235 call to the @code{__clear_cache} function in libgcc is made. 14236 @end deftypefn 14237 14238 @deftypefn {Built-in Function} void __builtin_prefetch (const void *@var{addr}, ...) 14239 This function is used to minimize cache-miss latency by moving data into 14240 a cache before it is accessed. 14241 You can insert calls to @code{__builtin_prefetch} into code for which 14242 you know addresses of data in memory that is likely to be accessed soon. 14243 If the target supports them, data prefetch instructions are generated. 14244 If the prefetch is done early enough before the access then the data will 14245 be in the cache by the time it is accessed. 14246 14247 The value of @var{addr} is the address of the memory to prefetch. 14248 There are two optional arguments, @var{rw} and @var{locality}. 14249 The value of @var{rw} is a compile-time constant one or zero; one 14250 means that the prefetch is preparing for a write to the memory address 14251 and zero, the default, means that the prefetch is preparing for a read. 14252 The value @var{locality} must be a compile-time constant integer between 14253 zero and three. A value of zero means that the data has no temporal 14254 locality, so it need not be left in the cache after the access. A value 14255 of three means that the data has a high degree of temporal locality and 14256 should be left in all levels of cache possible. Values of one and two 14257 mean, respectively, a low or moderate degree of temporal locality. The 14258 default is three. 14259 14260 @smallexample 14261 for (i = 0; i < n; i++) 14262 @{ 14263 a[i] = a[i] + b[i]; 14264 __builtin_prefetch (&a[i+j], 1, 1); 14265 __builtin_prefetch (&b[i+j], 0, 1); 14266 /* @r{@dots{}} */ 14267 @} 14268 @end smallexample 14269 14270 Data prefetch does not generate faults if @var{addr} is invalid, but 14271 the address expression itself must be valid. For example, a prefetch 14272 of @code{p->next} does not fault if @code{p->next} is not a valid 14273 address, but evaluation faults if @code{p} is not a valid address. 14274 14275 If the target does not support data prefetch, the address expression 14276 is evaluated if it includes side effects but no other code is generated 14277 and GCC does not issue a warning. 14278 @end deftypefn 14279 14280 @deftypefn {Built-in Function}{size_t} __builtin_object_size (const void * @var{ptr}, int @var{type}) 14281 Returns the size of an object pointed to by @var{ptr}. @xref{Object Size 14282 Checking}, for a detailed description of the function. 14283 @end deftypefn 14284 14285 @deftypefn {Built-in Function} double __builtin_huge_val (void) 14286 Returns a positive infinity, if supported by the floating-point format, 14287 else @code{DBL_MAX}. This function is suitable for implementing the 14288 ISO C macro @code{HUGE_VAL}. 14289 @end deftypefn 14290 14291 @deftypefn {Built-in Function} float __builtin_huge_valf (void) 14292 Similar to @code{__builtin_huge_val}, except the return type is @code{float}. 14293 @end deftypefn 14294 14295 @deftypefn {Built-in Function} {long double} __builtin_huge_vall (void) 14296 Similar to @code{__builtin_huge_val}, except the return 14297 type is @code{long double}. 14298 @end deftypefn 14299 14300 @deftypefn {Built-in Function} _Float@var{n} __builtin_huge_valf@var{n} (void) 14301 Similar to @code{__builtin_huge_val}, except the return type is 14302 @code{_Float@var{n}}. 14303 @end deftypefn 14304 14305 @deftypefn {Built-in Function} _Float@var{n}x __builtin_huge_valf@var{n}x (void) 14306 Similar to @code{__builtin_huge_val}, except the return type is 14307 @code{_Float@var{n}x}. 14308 @end deftypefn 14309 14310 @deftypefn {Built-in Function} int __builtin_fpclassify (int, int, int, int, int, ...) 14311 This built-in implements the C99 fpclassify functionality. The first 14312 five int arguments should be the target library's notion of the 14313 possible FP classes and are used for return values. They must be 14314 constant values and they must appear in this order: @code{FP_NAN}, 14315 @code{FP_INFINITE}, @code{FP_NORMAL}, @code{FP_SUBNORMAL} and 14316 @code{FP_ZERO}. The ellipsis is for exactly one floating-point value 14317 to classify. GCC treats the last argument as type-generic, which 14318 means it does not do default promotion from float to double. 14319 @end deftypefn 14320 14321 @deftypefn {Built-in Function} double __builtin_inf (void) 14322 Similar to @code{__builtin_huge_val}, except a warning is generated 14323 if the target floating-point format does not support infinities. 14324 @end deftypefn 14325 14326 @deftypefn {Built-in Function} _Decimal32 __builtin_infd32 (void) 14327 Similar to @code{__builtin_inf}, except the return type is @code{_Decimal32}. 14328 @end deftypefn 14329 14330 @deftypefn {Built-in Function} _Decimal64 __builtin_infd64 (void) 14331 Similar to @code{__builtin_inf}, except the return type is @code{_Decimal64}. 14332 @end deftypefn 14333 14334 @deftypefn {Built-in Function} _Decimal128 __builtin_infd128 (void) 14335 Similar to @code{__builtin_inf}, except the return type is @code{_Decimal128}. 14336 @end deftypefn 14337 14338 @deftypefn {Built-in Function} float __builtin_inff (void) 14339 Similar to @code{__builtin_inf}, except the return type is @code{float}. 14340 This function is suitable for implementing the ISO C99 macro @code{INFINITY}. 14341 @end deftypefn 14342 14343 @deftypefn {Built-in Function} {long double} __builtin_infl (void) 14344 Similar to @code{__builtin_inf}, except the return 14345 type is @code{long double}. 14346 @end deftypefn 14347 14348 @deftypefn {Built-in Function} _Float@var{n} __builtin_inff@var{n} (void) 14349 Similar to @code{__builtin_inf}, except the return 14350 type is @code{_Float@var{n}}. 14351 @end deftypefn 14352 14353 @deftypefn {Built-in Function} _Float@var{n} __builtin_inff@var{n}x (void) 14354 Similar to @code{__builtin_inf}, except the return 14355 type is @code{_Float@var{n}x}. 14356 @end deftypefn 14357 14358 @deftypefn {Built-in Function} int __builtin_isinf_sign (...) 14359 Similar to @code{isinf}, except the return value is -1 for 14360 an argument of @code{-Inf} and 1 for an argument of @code{+Inf}. 14361 Note while the parameter list is an 14362 ellipsis, this function only accepts exactly one floating-point 14363 argument. GCC treats this parameter as type-generic, which means it 14364 does not do default promotion from float to double. 14365 @end deftypefn 14366 14367 @deftypefn {Built-in Function} double __builtin_nan (const char *str) 14368 This is an implementation of the ISO C99 function @code{nan}. 14369 14370 Since ISO C99 defines this function in terms of @code{strtod}, which we 14371 do not implement, a description of the parsing is in order. The string 14372 is parsed as by @code{strtol}; that is, the base is recognized by 14373 leading @samp{0} or @samp{0x} prefixes. The number parsed is placed 14374 in the significand such that the least significant bit of the number 14375 is at the least significant bit of the significand. The number is 14376 truncated to fit the significand field provided. The significand is 14377 forced to be a quiet NaN@. 14378 14379 This function, if given a string literal all of which would have been 14380 consumed by @code{strtol}, is evaluated early enough that it is considered a 14381 compile-time constant. 14382 @end deftypefn 14383 14384 @deftypefn {Built-in Function} _Decimal32 __builtin_nand32 (const char *str) 14385 Similar to @code{__builtin_nan}, except the return type is @code{_Decimal32}. 14386 @end deftypefn 14387 14388 @deftypefn {Built-in Function} _Decimal64 __builtin_nand64 (const char *str) 14389 Similar to @code{__builtin_nan}, except the return type is @code{_Decimal64}. 14390 @end deftypefn 14391 14392 @deftypefn {Built-in Function} _Decimal128 __builtin_nand128 (const char *str) 14393 Similar to @code{__builtin_nan}, except the return type is @code{_Decimal128}. 14394 @end deftypefn 14395 14396 @deftypefn {Built-in Function} float __builtin_nanf (const char *str) 14397 Similar to @code{__builtin_nan}, except the return type is @code{float}. 14398 @end deftypefn 14399 14400 @deftypefn {Built-in Function} {long double} __builtin_nanl (const char *str) 14401 Similar to @code{__builtin_nan}, except the return type is @code{long double}. 14402 @end deftypefn 14403 14404 @deftypefn {Built-in Function} _Float@var{n} __builtin_nanf@var{n} (const char *str) 14405 Similar to @code{__builtin_nan}, except the return type is 14406 @code{_Float@var{n}}. 14407 @end deftypefn 14408 14409 @deftypefn {Built-in Function} _Float@var{n}x __builtin_nanf@var{n}x (const char *str) 14410 Similar to @code{__builtin_nan}, except the return type is 14411 @code{_Float@var{n}x}. 14412 @end deftypefn 14413 14414 @deftypefn {Built-in Function} double __builtin_nans (const char *str) 14415 Similar to @code{__builtin_nan}, except the significand is forced 14416 to be a signaling NaN@. The @code{nans} function is proposed by 14417 @uref{http://www.open-std.org/jtc1/sc22/wg14/www/docs/n965.htm,,WG14 N965}. 14418 @end deftypefn 14419 14420 @deftypefn {Built-in Function} _Decimal32 __builtin_nansd32 (const char *str) 14421 Similar to @code{__builtin_nans}, except the return type is @code{_Decimal32}. 14422 @end deftypefn 14423 14424 @deftypefn {Built-in Function} _Decimal64 __builtin_nansd64 (const char *str) 14425 Similar to @code{__builtin_nans}, except the return type is @code{_Decimal64}. 14426 @end deftypefn 14427 14428 @deftypefn {Built-in Function} _Decimal128 __builtin_nansd128 (const char *str) 14429 Similar to @code{__builtin_nans}, except the return type is @code{_Decimal128}. 14430 @end deftypefn 14431 14432 @deftypefn {Built-in Function} float __builtin_nansf (const char *str) 14433 Similar to @code{__builtin_nans}, except the return type is @code{float}. 14434 @end deftypefn 14435 14436 @deftypefn {Built-in Function} {long double} __builtin_nansl (const char *str) 14437 Similar to @code{__builtin_nans}, except the return type is @code{long double}. 14438 @end deftypefn 14439 14440 @deftypefn {Built-in Function} _Float@var{n} __builtin_nansf@var{n} (const char *str) 14441 Similar to @code{__builtin_nans}, except the return type is 14442 @code{_Float@var{n}}. 14443 @end deftypefn 14444 14445 @deftypefn {Built-in Function} _Float@var{n}x __builtin_nansf@var{n}x (const char *str) 14446 Similar to @code{__builtin_nans}, except the return type is 14447 @code{_Float@var{n}x}. 14448 @end deftypefn 14449 14450 @deftypefn {Built-in Function} int __builtin_ffs (int x) 14451 Returns one plus the index of the least significant 1-bit of @var{x}, or 14452 if @var{x} is zero, returns zero. 14453 @end deftypefn 14454 14455 @deftypefn {Built-in Function} int __builtin_clz (unsigned int x) 14456 Returns the number of leading 0-bits in @var{x}, starting at the most 14457 significant bit position. If @var{x} is 0, the result is undefined. 14458 @end deftypefn 14459 14460 @deftypefn {Built-in Function} int __builtin_ctz (unsigned int x) 14461 Returns the number of trailing 0-bits in @var{x}, starting at the least 14462 significant bit position. If @var{x} is 0, the result is undefined. 14463 @end deftypefn 14464 14465 @deftypefn {Built-in Function} int __builtin_clrsb (int x) 14466 Returns the number of leading redundant sign bits in @var{x}, i.e.@: the 14467 number of bits following the most significant bit that are identical 14468 to it. There are no special cases for 0 or other values. 14469 @end deftypefn 14470 14471 @deftypefn {Built-in Function} int __builtin_popcount (unsigned int x) 14472 Returns the number of 1-bits in @var{x}. 14473 @end deftypefn 14474 14475 @deftypefn {Built-in Function} int __builtin_parity (unsigned int x) 14476 Returns the parity of @var{x}, i.e.@: the number of 1-bits in @var{x} 14477 modulo 2. 14478 @end deftypefn 14479 14480 @deftypefn {Built-in Function} int __builtin_ffsl (long) 14481 Similar to @code{__builtin_ffs}, except the argument type is 14482 @code{long}. 14483 @end deftypefn 14484 14485 @deftypefn {Built-in Function} int __builtin_clzl (unsigned long) 14486 Similar to @code{__builtin_clz}, except the argument type is 14487 @code{unsigned long}. 14488 @end deftypefn 14489 14490 @deftypefn {Built-in Function} int __builtin_ctzl (unsigned long) 14491 Similar to @code{__builtin_ctz}, except the argument type is 14492 @code{unsigned long}. 14493 @end deftypefn 14494 14495 @deftypefn {Built-in Function} int __builtin_clrsbl (long) 14496 Similar to @code{__builtin_clrsb}, except the argument type is 14497 @code{long}. 14498 @end deftypefn 14499 14500 @deftypefn {Built-in Function} int __builtin_popcountl (unsigned long) 14501 Similar to @code{__builtin_popcount}, except the argument type is 14502 @code{unsigned long}. 14503 @end deftypefn 14504 14505 @deftypefn {Built-in Function} int __builtin_parityl (unsigned long) 14506 Similar to @code{__builtin_parity}, except the argument type is 14507 @code{unsigned long}. 14508 @end deftypefn 14509 14510 @deftypefn {Built-in Function} int __builtin_ffsll (long long) 14511 Similar to @code{__builtin_ffs}, except the argument type is 14512 @code{long long}. 14513 @end deftypefn 14514 14515 @deftypefn {Built-in Function} int __builtin_clzll (unsigned long long) 14516 Similar to @code{__builtin_clz}, except the argument type is 14517 @code{unsigned long long}. 14518 @end deftypefn 14519 14520 @deftypefn {Built-in Function} int __builtin_ctzll (unsigned long long) 14521 Similar to @code{__builtin_ctz}, except the argument type is 14522 @code{unsigned long long}. 14523 @end deftypefn 14524 14525 @deftypefn {Built-in Function} int __builtin_clrsbll (long long) 14526 Similar to @code{__builtin_clrsb}, except the argument type is 14527 @code{long long}. 14528 @end deftypefn 14529 14530 @deftypefn {Built-in Function} int __builtin_popcountll (unsigned long long) 14531 Similar to @code{__builtin_popcount}, except the argument type is 14532 @code{unsigned long long}. 14533 @end deftypefn 14534 14535 @deftypefn {Built-in Function} int __builtin_parityll (unsigned long long) 14536 Similar to @code{__builtin_parity}, except the argument type is 14537 @code{unsigned long long}. 14538 @end deftypefn 14539 14540 @deftypefn {Built-in Function} double __builtin_powi (double, int) 14541 Returns the first argument raised to the power of the second. Unlike the 14542 @code{pow} function no guarantees about precision and rounding are made. 14543 @end deftypefn 14544 14545 @deftypefn {Built-in Function} float __builtin_powif (float, int) 14546 Similar to @code{__builtin_powi}, except the argument and return types 14547 are @code{float}. 14548 @end deftypefn 14549 14550 @deftypefn {Built-in Function} {long double} __builtin_powil (long double, int) 14551 Similar to @code{__builtin_powi}, except the argument and return types 14552 are @code{long double}. 14553 @end deftypefn 14554 14555 @deftypefn {Built-in Function} uint16_t __builtin_bswap16 (uint16_t x) 14556 Returns @var{x} with the order of the bytes reversed; for example, 14557 @code{0xaabb} becomes @code{0xbbaa}. Byte here always means 14558 exactly 8 bits. 14559 @end deftypefn 14560 14561 @deftypefn {Built-in Function} uint32_t __builtin_bswap32 (uint32_t x) 14562 Similar to @code{__builtin_bswap16}, except the argument and return types 14563 are 32-bit. 14564 @end deftypefn 14565 14566 @deftypefn {Built-in Function} uint64_t __builtin_bswap64 (uint64_t x) 14567 Similar to @code{__builtin_bswap32}, except the argument and return types 14568 are 64-bit. 14569 @end deftypefn 14570 14571 @deftypefn {Built-in Function} uint128_t __builtin_bswap128 (uint128_t x) 14572 Similar to @code{__builtin_bswap64}, except the argument and return types 14573 are 128-bit. Only supported on targets when 128-bit types are supported. 14574 @end deftypefn 14575 14576 14577 @deftypefn {Built-in Function} Pmode __builtin_extend_pointer (void * x) 14578 On targets where the user visible pointer size is smaller than the size 14579 of an actual hardware address this function returns the extended user 14580 pointer. Targets where this is true included ILP32 mode on x86_64 or 14581 Aarch64. This function is mainly useful when writing inline assembly 14582 code. 14583 @end deftypefn 14584 14585 @deftypefn {Built-in Function} int __builtin_goacc_parlevel_id (int x) 14586 Returns the openacc gang, worker or vector id depending on whether @var{x} is 14587 0, 1 or 2. 14588 @end deftypefn 14589 14590 @deftypefn {Built-in Function} int __builtin_goacc_parlevel_size (int x) 14591 Returns the openacc gang, worker or vector size depending on whether @var{x} is 14592 0, 1 or 2. 14593 @end deftypefn 14594 14595 @node Target Builtins 14596 @section Built-in Functions Specific to Particular Target Machines 14597 14598 On some target machines, GCC supports many built-in functions specific 14599 to those machines. Generally these generate calls to specific machine 14600 instructions, but allow the compiler to schedule those calls. 14601 14602 @menu 14603 * AArch64 Built-in Functions:: 14604 * Alpha Built-in Functions:: 14605 * Altera Nios II Built-in Functions:: 14606 * ARC Built-in Functions:: 14607 * ARC SIMD Built-in Functions:: 14608 * ARM iWMMXt Built-in Functions:: 14609 * ARM C Language Extensions (ACLE):: 14610 * ARM Floating Point Status and Control Intrinsics:: 14611 * ARM ARMv8-M Security Extensions:: 14612 * AVR Built-in Functions:: 14613 * Blackfin Built-in Functions:: 14614 * BPF Built-in Functions:: 14615 * FR-V Built-in Functions:: 14616 * LoongArch Base Built-in Functions:: 14617 * MIPS DSP Built-in Functions:: 14618 * MIPS Paired-Single Support:: 14619 * MIPS Loongson Built-in Functions:: 14620 * MIPS SIMD Architecture (MSA) Support:: 14621 * Other MIPS Built-in Functions:: 14622 * MSP430 Built-in Functions:: 14623 * NDS32 Built-in Functions:: 14624 * picoChip Built-in Functions:: 14625 * Basic PowerPC Built-in Functions:: 14626 * PowerPC AltiVec/VSX Built-in Functions:: 14627 * PowerPC Hardware Transactional Memory Built-in Functions:: 14628 * PowerPC Atomic Memory Operation Functions:: 14629 * PowerPC Matrix-Multiply Assist Built-in Functions:: 14630 * PRU Built-in Functions:: 14631 * RISC-V Built-in Functions:: 14632 * RX Built-in Functions:: 14633 * S/390 System z Built-in Functions:: 14634 * SH Built-in Functions:: 14635 * SPARC VIS Built-in Functions:: 14636 * TI C6X Built-in Functions:: 14637 * TILE-Gx Built-in Functions:: 14638 * TILEPro Built-in Functions:: 14639 * x86 Built-in Functions:: 14640 * x86 transactional memory intrinsics:: 14641 * x86 control-flow protection intrinsics:: 14642 @end menu 14643 14644 @node AArch64 Built-in Functions 14645 @subsection AArch64 Built-in Functions 14646 14647 These built-in functions are available for the AArch64 family of 14648 processors. 14649 @smallexample 14650 unsigned int __builtin_aarch64_get_fpcr (); 14651 void __builtin_aarch64_set_fpcr (unsigned int); 14652 unsigned int __builtin_aarch64_get_fpsr (); 14653 void __builtin_aarch64_set_fpsr (unsigned int); 14654 14655 unsigned long long __builtin_aarch64_get_fpcr64 (); 14656 void __builtin_aarch64_set_fpcr64 (unsigned long long); 14657 unsigned long long __builtin_aarch64_get_fpsr64 (); 14658 void __builtin_aarch64_set_fpsr64 (unsigned long long); 14659 @end smallexample 14660 14661 @node Alpha Built-in Functions 14662 @subsection Alpha Built-in Functions 14663 14664 These built-in functions are available for the Alpha family of 14665 processors, depending on the command-line switches used. 14666 14667 The following built-in functions are always available. They 14668 all generate the machine instruction that is part of the name. 14669 14670 @smallexample 14671 long __builtin_alpha_implver (void); 14672 long __builtin_alpha_rpcc (void); 14673 long __builtin_alpha_amask (long); 14674 long __builtin_alpha_cmpbge (long, long); 14675 long __builtin_alpha_extbl (long, long); 14676 long __builtin_alpha_extwl (long, long); 14677 long __builtin_alpha_extll (long, long); 14678 long __builtin_alpha_extql (long, long); 14679 long __builtin_alpha_extwh (long, long); 14680 long __builtin_alpha_extlh (long, long); 14681 long __builtin_alpha_extqh (long, long); 14682 long __builtin_alpha_insbl (long, long); 14683 long __builtin_alpha_inswl (long, long); 14684 long __builtin_alpha_insll (long, long); 14685 long __builtin_alpha_insql (long, long); 14686 long __builtin_alpha_inswh (long, long); 14687 long __builtin_alpha_inslh (long, long); 14688 long __builtin_alpha_insqh (long, long); 14689 long __builtin_alpha_mskbl (long, long); 14690 long __builtin_alpha_mskwl (long, long); 14691 long __builtin_alpha_mskll (long, long); 14692 long __builtin_alpha_mskql (long, long); 14693 long __builtin_alpha_mskwh (long, long); 14694 long __builtin_alpha_msklh (long, long); 14695 long __builtin_alpha_mskqh (long, long); 14696 long __builtin_alpha_umulh (long, long); 14697 long __builtin_alpha_zap (long, long); 14698 long __builtin_alpha_zapnot (long, long); 14699 @end smallexample 14700 14701 The following built-in functions are always with @option{-mmax} 14702 or @option{-mcpu=@var{cpu}} where @var{cpu} is @code{pca56} or 14703 later. They all generate the machine instruction that is part 14704 of the name. 14705 14706 @smallexample 14707 long __builtin_alpha_pklb (long); 14708 long __builtin_alpha_pkwb (long); 14709 long __builtin_alpha_unpkbl (long); 14710 long __builtin_alpha_unpkbw (long); 14711 long __builtin_alpha_minub8 (long, long); 14712 long __builtin_alpha_minsb8 (long, long); 14713 long __builtin_alpha_minuw4 (long, long); 14714 long __builtin_alpha_minsw4 (long, long); 14715 long __builtin_alpha_maxub8 (long, long); 14716 long __builtin_alpha_maxsb8 (long, long); 14717 long __builtin_alpha_maxuw4 (long, long); 14718 long __builtin_alpha_maxsw4 (long, long); 14719 long __builtin_alpha_perr (long, long); 14720 @end smallexample 14721 14722 The following built-in functions are always with @option{-mcix} 14723 or @option{-mcpu=@var{cpu}} where @var{cpu} is @code{ev67} or 14724 later. They all generate the machine instruction that is part 14725 of the name. 14726 14727 @smallexample 14728 long __builtin_alpha_cttz (long); 14729 long __builtin_alpha_ctlz (long); 14730 long __builtin_alpha_ctpop (long); 14731 @end smallexample 14732 14733 The following built-in functions are available on systems that use the OSF/1 14734 PALcode. Normally they invoke the @code{rduniq} and @code{wruniq} 14735 PAL calls, but when invoked with @option{-mtls-kernel}, they invoke 14736 @code{rdval} and @code{wrval}. 14737 14738 @smallexample 14739 void *__builtin_thread_pointer (void); 14740 void __builtin_set_thread_pointer (void *); 14741 @end smallexample 14742 14743 @node Altera Nios II Built-in Functions 14744 @subsection Altera Nios II Built-in Functions 14745 14746 These built-in functions are available for the Altera Nios II 14747 family of processors. 14748 14749 The following built-in functions are always available. They 14750 all generate the machine instruction that is part of the name. 14751 14752 @example 14753 int __builtin_ldbio (volatile const void *); 14754 int __builtin_ldbuio (volatile const void *); 14755 int __builtin_ldhio (volatile const void *); 14756 int __builtin_ldhuio (volatile const void *); 14757 int __builtin_ldwio (volatile const void *); 14758 void __builtin_stbio (volatile void *, int); 14759 void __builtin_sthio (volatile void *, int); 14760 void __builtin_stwio (volatile void *, int); 14761 void __builtin_sync (void); 14762 int __builtin_rdctl (int); 14763 int __builtin_rdprs (int, int); 14764 void __builtin_wrctl (int, int); 14765 void __builtin_flushd (volatile void *); 14766 void __builtin_flushda (volatile void *); 14767 int __builtin_wrpie (int); 14768 void __builtin_eni (int); 14769 int __builtin_ldex (volatile const void *); 14770 int __builtin_stex (volatile void *, int); 14771 int __builtin_ldsex (volatile const void *); 14772 int __builtin_stsex (volatile void *, int); 14773 @end example 14774 14775 The following built-in functions are always available. They 14776 all generate a Nios II Custom Instruction. The name of the 14777 function represents the types that the function takes and 14778 returns. The letter before the @code{n} is the return type 14779 or void if absent. The @code{n} represents the first parameter 14780 to all the custom instructions, the custom instruction number. 14781 The two letters after the @code{n} represent the up to two 14782 parameters to the function. 14783 14784 The letters represent the following data types: 14785 @table @code 14786 @item <no letter> 14787 @code{void} for return type and no parameter for parameter types. 14788 14789 @item i 14790 @code{int} for return type and parameter type 14791 14792 @item f 14793 @code{float} for return type and parameter type 14794 14795 @item p 14796 @code{void *} for return type and parameter type 14797 14798 @end table 14799 14800 And the function names are: 14801 @example 14802 void __builtin_custom_n (void); 14803 void __builtin_custom_ni (int); 14804 void __builtin_custom_nf (float); 14805 void __builtin_custom_np (void *); 14806 void __builtin_custom_nii (int, int); 14807 void __builtin_custom_nif (int, float); 14808 void __builtin_custom_nip (int, void *); 14809 void __builtin_custom_nfi (float, int); 14810 void __builtin_custom_nff (float, float); 14811 void __builtin_custom_nfp (float, void *); 14812 void __builtin_custom_npi (void *, int); 14813 void __builtin_custom_npf (void *, float); 14814 void __builtin_custom_npp (void *, void *); 14815 int __builtin_custom_in (void); 14816 int __builtin_custom_ini (int); 14817 int __builtin_custom_inf (float); 14818 int __builtin_custom_inp (void *); 14819 int __builtin_custom_inii (int, int); 14820 int __builtin_custom_inif (int, float); 14821 int __builtin_custom_inip (int, void *); 14822 int __builtin_custom_infi (float, int); 14823 int __builtin_custom_inff (float, float); 14824 int __builtin_custom_infp (float, void *); 14825 int __builtin_custom_inpi (void *, int); 14826 int __builtin_custom_inpf (void *, float); 14827 int __builtin_custom_inpp (void *, void *); 14828 float __builtin_custom_fn (void); 14829 float __builtin_custom_fni (int); 14830 float __builtin_custom_fnf (float); 14831 float __builtin_custom_fnp (void *); 14832 float __builtin_custom_fnii (int, int); 14833 float __builtin_custom_fnif (int, float); 14834 float __builtin_custom_fnip (int, void *); 14835 float __builtin_custom_fnfi (float, int); 14836 float __builtin_custom_fnff (float, float); 14837 float __builtin_custom_fnfp (float, void *); 14838 float __builtin_custom_fnpi (void *, int); 14839 float __builtin_custom_fnpf (void *, float); 14840 float __builtin_custom_fnpp (void *, void *); 14841 void * __builtin_custom_pn (void); 14842 void * __builtin_custom_pni (int); 14843 void * __builtin_custom_pnf (float); 14844 void * __builtin_custom_pnp (void *); 14845 void * __builtin_custom_pnii (int, int); 14846 void * __builtin_custom_pnif (int, float); 14847 void * __builtin_custom_pnip (int, void *); 14848 void * __builtin_custom_pnfi (float, int); 14849 void * __builtin_custom_pnff (float, float); 14850 void * __builtin_custom_pnfp (float, void *); 14851 void * __builtin_custom_pnpi (void *, int); 14852 void * __builtin_custom_pnpf (void *, float); 14853 void * __builtin_custom_pnpp (void *, void *); 14854 @end example 14855 14856 @node ARC Built-in Functions 14857 @subsection ARC Built-in Functions 14858 14859 The following built-in functions are provided for ARC targets. The 14860 built-ins generate the corresponding assembly instructions. In the 14861 examples given below, the generated code often requires an operand or 14862 result to be in a register. Where necessary further code will be 14863 generated to ensure this is true, but for brevity this is not 14864 described in each case. 14865 14866 @emph{Note:} Using a built-in to generate an instruction not supported 14867 by a target may cause problems. At present the compiler is not 14868 guaranteed to detect such misuse, and as a result an internal compiler 14869 error may be generated. 14870 14871 @deftypefn {Built-in Function} int __builtin_arc_aligned (void *@var{val}, int @var{alignval}) 14872 Return 1 if @var{val} is known to have the byte alignment given 14873 by @var{alignval}, otherwise return 0. 14874 Note that this is different from 14875 @smallexample 14876 __alignof__(*(char *)@var{val}) >= alignval 14877 @end smallexample 14878 because __alignof__ sees only the type of the dereference, whereas 14879 __builtin_arc_align uses alignment information from the pointer 14880 as well as from the pointed-to type. 14881 The information available will depend on optimization level. 14882 @end deftypefn 14883 14884 @deftypefn {Built-in Function} void __builtin_arc_brk (void) 14885 Generates 14886 @example 14887 brk 14888 @end example 14889 @end deftypefn 14890 14891 @deftypefn {Built-in Function} {unsigned int} __builtin_arc_core_read (unsigned int @var{regno}) 14892 The operand is the number of a register to be read. Generates: 14893 @example 14894 mov @var{dest}, r@var{regno} 14895 @end example 14896 where the value in @var{dest} will be the result returned from the 14897 built-in. 14898 @end deftypefn 14899 14900 @deftypefn {Built-in Function} void __builtin_arc_core_write (unsigned int @var{regno}, unsigned int @var{val}) 14901 The first operand is the number of a register to be written, the 14902 second operand is a compile time constant to write into that 14903 register. Generates: 14904 @example 14905 mov r@var{regno}, @var{val} 14906 @end example 14907 @end deftypefn 14908 14909 @deftypefn {Built-in Function} int __builtin_arc_divaw (int @var{a}, int @var{b}) 14910 Only available if either @option{-mcpu=ARC700} or @option{-meA} is set. 14911 Generates: 14912 @example 14913 divaw @var{dest}, @var{a}, @var{b} 14914 @end example 14915 where the value in @var{dest} will be the result returned from the 14916 built-in. 14917 @end deftypefn 14918 14919 @deftypefn {Built-in Function} void __builtin_arc_flag (unsigned int @var{a}) 14920 Generates 14921 @example 14922 flag @var{a} 14923 @end example 14924 @end deftypefn 14925 14926 @deftypefn {Built-in Function} {unsigned int} __builtin_arc_lr (unsigned int @var{auxr}) 14927 The operand, @var{auxv}, is the address of an auxiliary register and 14928 must be a compile time constant. Generates: 14929 @example 14930 lr @var{dest}, [@var{auxr}] 14931 @end example 14932 Where the value in @var{dest} will be the result returned from the 14933 built-in. 14934 @end deftypefn 14935 14936 @deftypefn {Built-in Function} void __builtin_arc_mul64 (int @var{a}, int @var{b}) 14937 Only available with @option{-mmul64}. Generates: 14938 @example 14939 mul64 @var{a}, @var{b} 14940 @end example 14941 @end deftypefn 14942 14943 @deftypefn {Built-in Function} void __builtin_arc_mulu64 (unsigned int @var{a}, unsigned int @var{b}) 14944 Only available with @option{-mmul64}. Generates: 14945 @example 14946 mulu64 @var{a}, @var{b} 14947 @end example 14948 @end deftypefn 14949 14950 @deftypefn {Built-in Function} void __builtin_arc_nop (void) 14951 Generates: 14952 @example 14953 nop 14954 @end example 14955 @end deftypefn 14956 14957 @deftypefn {Built-in Function} int __builtin_arc_norm (int @var{src}) 14958 Only valid if the @samp{norm} instruction is available through the 14959 @option{-mnorm} option or by default with @option{-mcpu=ARC700}. 14960 Generates: 14961 @example 14962 norm @var{dest}, @var{src} 14963 @end example 14964 Where the value in @var{dest} will be the result returned from the 14965 built-in. 14966 @end deftypefn 14967 14968 @deftypefn {Built-in Function} {short int} __builtin_arc_normw (short int @var{src}) 14969 Only valid if the @samp{normw} instruction is available through the 14970 @option{-mnorm} option or by default with @option{-mcpu=ARC700}. 14971 Generates: 14972 @example 14973 normw @var{dest}, @var{src} 14974 @end example 14975 Where the value in @var{dest} will be the result returned from the 14976 built-in. 14977 @end deftypefn 14978 14979 @deftypefn {Built-in Function} void __builtin_arc_rtie (void) 14980 Generates: 14981 @example 14982 rtie 14983 @end example 14984 @end deftypefn 14985 14986 @deftypefn {Built-in Function} void __builtin_arc_sleep (int @var{a} 14987 Generates: 14988 @example 14989 sleep @var{a} 14990 @end example 14991 @end deftypefn 14992 14993 @deftypefn {Built-in Function} void __builtin_arc_sr (unsigned int @var{val}, unsigned int @var{auxr}) 14994 The first argument, @var{val}, is a compile time constant to be 14995 written to the register, the second argument, @var{auxr}, is the 14996 address of an auxiliary register. Generates: 14997 @example 14998 sr @var{val}, [@var{auxr}] 14999 @end example 15000 @end deftypefn 15001 15002 @deftypefn {Built-in Function} int __builtin_arc_swap (int @var{src}) 15003 Only valid with @option{-mswap}. Generates: 15004 @example 15005 swap @var{dest}, @var{src} 15006 @end example 15007 Where the value in @var{dest} will be the result returned from the 15008 built-in. 15009 @end deftypefn 15010 15011 @deftypefn {Built-in Function} void __builtin_arc_swi (void) 15012 Generates: 15013 @example 15014 swi 15015 @end example 15016 @end deftypefn 15017 15018 @deftypefn {Built-in Function} void __builtin_arc_sync (void) 15019 Only available with @option{-mcpu=ARC700}. Generates: 15020 @example 15021 sync 15022 @end example 15023 @end deftypefn 15024 15025 @deftypefn {Built-in Function} void __builtin_arc_trap_s (unsigned int @var{c}) 15026 Only available with @option{-mcpu=ARC700}. Generates: 15027 @example 15028 trap_s @var{c} 15029 @end example 15030 @end deftypefn 15031 15032 @deftypefn {Built-in Function} void __builtin_arc_unimp_s (void) 15033 Only available with @option{-mcpu=ARC700}. Generates: 15034 @example 15035 unimp_s 15036 @end example 15037 @end deftypefn 15038 15039 The instructions generated by the following builtins are not 15040 considered as candidates for scheduling. They are not moved around by 15041 the compiler during scheduling, and thus can be expected to appear 15042 where they are put in the C code: 15043 @example 15044 __builtin_arc_brk() 15045 __builtin_arc_core_read() 15046 __builtin_arc_core_write() 15047 __builtin_arc_flag() 15048 __builtin_arc_lr() 15049 __builtin_arc_sleep() 15050 __builtin_arc_sr() 15051 __builtin_arc_swi() 15052 @end example 15053 15054 @node ARC SIMD Built-in Functions 15055 @subsection ARC SIMD Built-in Functions 15056 15057 SIMD builtins provided by the compiler can be used to generate the 15058 vector instructions. This section describes the available builtins 15059 and their usage in programs. With the @option{-msimd} option, the 15060 compiler provides 128-bit vector types, which can be specified using 15061 the @code{vector_size} attribute. The header file @file{arc-simd.h} 15062 can be included to use the following predefined types: 15063 @example 15064 typedef int __v4si __attribute__((vector_size(16))); 15065 typedef short __v8hi __attribute__((vector_size(16))); 15066 @end example 15067 15068 These types can be used to define 128-bit variables. The built-in 15069 functions listed in the following section can be used on these 15070 variables to generate the vector operations. 15071 15072 For all builtins, @code{__builtin_arc_@var{someinsn}}, the header file 15073 @file{arc-simd.h} also provides equivalent macros called 15074 @code{_@var{someinsn}} that can be used for programming ease and 15075 improved readability. The following macros for DMA control are also 15076 provided: 15077 @example 15078 #define _setup_dma_in_channel_reg _vdiwr 15079 #define _setup_dma_out_channel_reg _vdowr 15080 @end example 15081 15082 The following is a complete list of all the SIMD built-ins provided 15083 for ARC, grouped by calling signature. 15084 15085 The following take two @code{__v8hi} arguments and return a 15086 @code{__v8hi} result: 15087 @example 15088 __v8hi __builtin_arc_vaddaw (__v8hi, __v8hi); 15089 __v8hi __builtin_arc_vaddw (__v8hi, __v8hi); 15090 __v8hi __builtin_arc_vand (__v8hi, __v8hi); 15091 __v8hi __builtin_arc_vandaw (__v8hi, __v8hi); 15092 __v8hi __builtin_arc_vavb (__v8hi, __v8hi); 15093 __v8hi __builtin_arc_vavrb (__v8hi, __v8hi); 15094 __v8hi __builtin_arc_vbic (__v8hi, __v8hi); 15095 __v8hi __builtin_arc_vbicaw (__v8hi, __v8hi); 15096 __v8hi __builtin_arc_vdifaw (__v8hi, __v8hi); 15097 __v8hi __builtin_arc_vdifw (__v8hi, __v8hi); 15098 __v8hi __builtin_arc_veqw (__v8hi, __v8hi); 15099 __v8hi __builtin_arc_vh264f (__v8hi, __v8hi); 15100 __v8hi __builtin_arc_vh264ft (__v8hi, __v8hi); 15101 __v8hi __builtin_arc_vh264fw (__v8hi, __v8hi); 15102 __v8hi __builtin_arc_vlew (__v8hi, __v8hi); 15103 __v8hi __builtin_arc_vltw (__v8hi, __v8hi); 15104 __v8hi __builtin_arc_vmaxaw (__v8hi, __v8hi); 15105 __v8hi __builtin_arc_vmaxw (__v8hi, __v8hi); 15106 __v8hi __builtin_arc_vminaw (__v8hi, __v8hi); 15107 __v8hi __builtin_arc_vminw (__v8hi, __v8hi); 15108 __v8hi __builtin_arc_vmr1aw (__v8hi, __v8hi); 15109 __v8hi __builtin_arc_vmr1w (__v8hi, __v8hi); 15110 __v8hi __builtin_arc_vmr2aw (__v8hi, __v8hi); 15111 __v8hi __builtin_arc_vmr2w (__v8hi, __v8hi); 15112 __v8hi __builtin_arc_vmr3aw (__v8hi, __v8hi); 15113 __v8hi __builtin_arc_vmr3w (__v8hi, __v8hi); 15114 __v8hi __builtin_arc_vmr4aw (__v8hi, __v8hi); 15115 __v8hi __builtin_arc_vmr4w (__v8hi, __v8hi); 15116 __v8hi __builtin_arc_vmr5aw (__v8hi, __v8hi); 15117 __v8hi __builtin_arc_vmr5w (__v8hi, __v8hi); 15118 __v8hi __builtin_arc_vmr6aw (__v8hi, __v8hi); 15119 __v8hi __builtin_arc_vmr6w (__v8hi, __v8hi); 15120 __v8hi __builtin_arc_vmr7aw (__v8hi, __v8hi); 15121 __v8hi __builtin_arc_vmr7w (__v8hi, __v8hi); 15122 __v8hi __builtin_arc_vmrb (__v8hi, __v8hi); 15123 __v8hi __builtin_arc_vmulaw (__v8hi, __v8hi); 15124 __v8hi __builtin_arc_vmulfaw (__v8hi, __v8hi); 15125 __v8hi __builtin_arc_vmulfw (__v8hi, __v8hi); 15126 __v8hi __builtin_arc_vmulw (__v8hi, __v8hi); 15127 __v8hi __builtin_arc_vnew (__v8hi, __v8hi); 15128 __v8hi __builtin_arc_vor (__v8hi, __v8hi); 15129 __v8hi __builtin_arc_vsubaw (__v8hi, __v8hi); 15130 __v8hi __builtin_arc_vsubw (__v8hi, __v8hi); 15131 __v8hi __builtin_arc_vsummw (__v8hi, __v8hi); 15132 __v8hi __builtin_arc_vvc1f (__v8hi, __v8hi); 15133 __v8hi __builtin_arc_vvc1ft (__v8hi, __v8hi); 15134 __v8hi __builtin_arc_vxor (__v8hi, __v8hi); 15135 __v8hi __builtin_arc_vxoraw (__v8hi, __v8hi); 15136 @end example 15137 15138 The following take one @code{__v8hi} and one @code{int} argument and return a 15139 @code{__v8hi} result: 15140 15141 @example 15142 __v8hi __builtin_arc_vbaddw (__v8hi, int); 15143 __v8hi __builtin_arc_vbmaxw (__v8hi, int); 15144 __v8hi __builtin_arc_vbminw (__v8hi, int); 15145 __v8hi __builtin_arc_vbmulaw (__v8hi, int); 15146 __v8hi __builtin_arc_vbmulfw (__v8hi, int); 15147 __v8hi __builtin_arc_vbmulw (__v8hi, int); 15148 __v8hi __builtin_arc_vbrsubw (__v8hi, int); 15149 __v8hi __builtin_arc_vbsubw (__v8hi, int); 15150 @end example 15151 15152 The following take one @code{__v8hi} argument and one @code{int} argument which 15153 must be a 3-bit compile time constant indicating a register number 15154 I0-I7. They return a @code{__v8hi} result. 15155 @example 15156 __v8hi __builtin_arc_vasrw (__v8hi, const int); 15157 __v8hi __builtin_arc_vsr8 (__v8hi, const int); 15158 __v8hi __builtin_arc_vsr8aw (__v8hi, const int); 15159 @end example 15160 15161 The following take one @code{__v8hi} argument and one @code{int} 15162 argument which must be a 6-bit compile time constant. They return a 15163 @code{__v8hi} result. 15164 @example 15165 __v8hi __builtin_arc_vasrpwbi (__v8hi, const int); 15166 __v8hi __builtin_arc_vasrrpwbi (__v8hi, const int); 15167 __v8hi __builtin_arc_vasrrwi (__v8hi, const int); 15168 __v8hi __builtin_arc_vasrsrwi (__v8hi, const int); 15169 __v8hi __builtin_arc_vasrwi (__v8hi, const int); 15170 __v8hi __builtin_arc_vsr8awi (__v8hi, const int); 15171 __v8hi __builtin_arc_vsr8i (__v8hi, const int); 15172 @end example 15173 15174 The following take one @code{__v8hi} argument and one @code{int} argument which 15175 must be a 8-bit compile time constant. They return a @code{__v8hi} 15176 result. 15177 @example 15178 __v8hi __builtin_arc_vd6tapf (__v8hi, const int); 15179 __v8hi __builtin_arc_vmvaw (__v8hi, const int); 15180 __v8hi __builtin_arc_vmvw (__v8hi, const int); 15181 __v8hi __builtin_arc_vmvzw (__v8hi, const int); 15182 @end example 15183 15184 The following take two @code{int} arguments, the second of which which 15185 must be a 8-bit compile time constant. They return a @code{__v8hi} 15186 result: 15187 @example 15188 __v8hi __builtin_arc_vmovaw (int, const int); 15189 __v8hi __builtin_arc_vmovw (int, const int); 15190 __v8hi __builtin_arc_vmovzw (int, const int); 15191 @end example 15192 15193 The following take a single @code{__v8hi} argument and return a 15194 @code{__v8hi} result: 15195 @example 15196 __v8hi __builtin_arc_vabsaw (__v8hi); 15197 __v8hi __builtin_arc_vabsw (__v8hi); 15198 __v8hi __builtin_arc_vaddsuw (__v8hi); 15199 __v8hi __builtin_arc_vexch1 (__v8hi); 15200 __v8hi __builtin_arc_vexch2 (__v8hi); 15201 __v8hi __builtin_arc_vexch4 (__v8hi); 15202 __v8hi __builtin_arc_vsignw (__v8hi); 15203 __v8hi __builtin_arc_vupbaw (__v8hi); 15204 __v8hi __builtin_arc_vupbw (__v8hi); 15205 __v8hi __builtin_arc_vupsbaw (__v8hi); 15206 __v8hi __builtin_arc_vupsbw (__v8hi); 15207 @end example 15208 15209 The following take two @code{int} arguments and return no result: 15210 @example 15211 void __builtin_arc_vdirun (int, int); 15212 void __builtin_arc_vdorun (int, int); 15213 @end example 15214 15215 The following take two @code{int} arguments and return no result. The 15216 first argument must a 3-bit compile time constant indicating one of 15217 the DR0-DR7 DMA setup channels: 15218 @example 15219 void __builtin_arc_vdiwr (const int, int); 15220 void __builtin_arc_vdowr (const int, int); 15221 @end example 15222 15223 The following take an @code{int} argument and return no result: 15224 @example 15225 void __builtin_arc_vendrec (int); 15226 void __builtin_arc_vrec (int); 15227 void __builtin_arc_vrecrun (int); 15228 void __builtin_arc_vrun (int); 15229 @end example 15230 15231 The following take a @code{__v8hi} argument and two @code{int} 15232 arguments and return a @code{__v8hi} result. The second argument must 15233 be a 3-bit compile time constants, indicating one the registers I0-I7, 15234 and the third argument must be an 8-bit compile time constant. 15235 15236 @emph{Note:} Although the equivalent hardware instructions do not take 15237 an SIMD register as an operand, these builtins overwrite the relevant 15238 bits of the @code{__v8hi} register provided as the first argument with 15239 the value loaded from the @code{[Ib, u8]} location in the SDM. 15240 15241 @example 15242 __v8hi __builtin_arc_vld32 (__v8hi, const int, const int); 15243 __v8hi __builtin_arc_vld32wh (__v8hi, const int, const int); 15244 __v8hi __builtin_arc_vld32wl (__v8hi, const int, const int); 15245 __v8hi __builtin_arc_vld64 (__v8hi, const int, const int); 15246 @end example 15247 15248 The following take two @code{int} arguments and return a @code{__v8hi} 15249 result. The first argument must be a 3-bit compile time constants, 15250 indicating one the registers I0-I7, and the second argument must be an 15251 8-bit compile time constant. 15252 15253 @example 15254 __v8hi __builtin_arc_vld128 (const int, const int); 15255 __v8hi __builtin_arc_vld64w (const int, const int); 15256 @end example 15257 15258 The following take a @code{__v8hi} argument and two @code{int} 15259 arguments and return no result. The second argument must be a 3-bit 15260 compile time constants, indicating one the registers I0-I7, and the 15261 third argument must be an 8-bit compile time constant. 15262 15263 @example 15264 void __builtin_arc_vst128 (__v8hi, const int, const int); 15265 void __builtin_arc_vst64 (__v8hi, const int, const int); 15266 @end example 15267 15268 The following take a @code{__v8hi} argument and three @code{int} 15269 arguments and return no result. The second argument must be a 3-bit 15270 compile-time constant, identifying the 16-bit sub-register to be 15271 stored, the third argument must be a 3-bit compile time constants, 15272 indicating one the registers I0-I7, and the fourth argument must be an 15273 8-bit compile time constant. 15274 15275 @example 15276 void __builtin_arc_vst16_n (__v8hi, const int, const int, const int); 15277 void __builtin_arc_vst32_n (__v8hi, const int, const int, const int); 15278 @end example 15279 15280 @node ARM iWMMXt Built-in Functions 15281 @subsection ARM iWMMXt Built-in Functions 15282 15283 These built-in functions are available for the ARM family of 15284 processors when the @option{-mcpu=iwmmxt} switch is used: 15285 15286 @smallexample 15287 typedef int v2si __attribute__ ((vector_size (8))); 15288 typedef short v4hi __attribute__ ((vector_size (8))); 15289 typedef char v8qi __attribute__ ((vector_size (8))); 15290 15291 int __builtin_arm_getwcgr0 (void); 15292 void __builtin_arm_setwcgr0 (int); 15293 int __builtin_arm_getwcgr1 (void); 15294 void __builtin_arm_setwcgr1 (int); 15295 int __builtin_arm_getwcgr2 (void); 15296 void __builtin_arm_setwcgr2 (int); 15297 int __builtin_arm_getwcgr3 (void); 15298 void __builtin_arm_setwcgr3 (int); 15299 int __builtin_arm_textrmsb (v8qi, int); 15300 int __builtin_arm_textrmsh (v4hi, int); 15301 int __builtin_arm_textrmsw (v2si, int); 15302 int __builtin_arm_textrmub (v8qi, int); 15303 int __builtin_arm_textrmuh (v4hi, int); 15304 int __builtin_arm_textrmuw (v2si, int); 15305 v8qi __builtin_arm_tinsrb (v8qi, int, int); 15306 v4hi __builtin_arm_tinsrh (v4hi, int, int); 15307 v2si __builtin_arm_tinsrw (v2si, int, int); 15308 long long __builtin_arm_tmia (long long, int, int); 15309 long long __builtin_arm_tmiabb (long long, int, int); 15310 long long __builtin_arm_tmiabt (long long, int, int); 15311 long long __builtin_arm_tmiaph (long long, int, int); 15312 long long __builtin_arm_tmiatb (long long, int, int); 15313 long long __builtin_arm_tmiatt (long long, int, int); 15314 int __builtin_arm_tmovmskb (v8qi); 15315 int __builtin_arm_tmovmskh (v4hi); 15316 int __builtin_arm_tmovmskw (v2si); 15317 long long __builtin_arm_waccb (v8qi); 15318 long long __builtin_arm_wacch (v4hi); 15319 long long __builtin_arm_waccw (v2si); 15320 v8qi __builtin_arm_waddb (v8qi, v8qi); 15321 v8qi __builtin_arm_waddbss (v8qi, v8qi); 15322 v8qi __builtin_arm_waddbus (v8qi, v8qi); 15323 v4hi __builtin_arm_waddh (v4hi, v4hi); 15324 v4hi __builtin_arm_waddhss (v4hi, v4hi); 15325 v4hi __builtin_arm_waddhus (v4hi, v4hi); 15326 v2si __builtin_arm_waddw (v2si, v2si); 15327 v2si __builtin_arm_waddwss (v2si, v2si); 15328 v2si __builtin_arm_waddwus (v2si, v2si); 15329 v8qi __builtin_arm_walign (v8qi, v8qi, int); 15330 long long __builtin_arm_wand(long long, long long); 15331 long long __builtin_arm_wandn (long long, long long); 15332 v8qi __builtin_arm_wavg2b (v8qi, v8qi); 15333 v8qi __builtin_arm_wavg2br (v8qi, v8qi); 15334 v4hi __builtin_arm_wavg2h (v4hi, v4hi); 15335 v4hi __builtin_arm_wavg2hr (v4hi, v4hi); 15336 v8qi __builtin_arm_wcmpeqb (v8qi, v8qi); 15337 v4hi __builtin_arm_wcmpeqh (v4hi, v4hi); 15338 v2si __builtin_arm_wcmpeqw (v2si, v2si); 15339 v8qi __builtin_arm_wcmpgtsb (v8qi, v8qi); 15340 v4hi __builtin_arm_wcmpgtsh (v4hi, v4hi); 15341 v2si __builtin_arm_wcmpgtsw (v2si, v2si); 15342 v8qi __builtin_arm_wcmpgtub (v8qi, v8qi); 15343 v4hi __builtin_arm_wcmpgtuh (v4hi, v4hi); 15344 v2si __builtin_arm_wcmpgtuw (v2si, v2si); 15345 long long __builtin_arm_wmacs (long long, v4hi, v4hi); 15346 long long __builtin_arm_wmacsz (v4hi, v4hi); 15347 long long __builtin_arm_wmacu (long long, v4hi, v4hi); 15348 long long __builtin_arm_wmacuz (v4hi, v4hi); 15349 v4hi __builtin_arm_wmadds (v4hi, v4hi); 15350 v4hi __builtin_arm_wmaddu (v4hi, v4hi); 15351 v8qi __builtin_arm_wmaxsb (v8qi, v8qi); 15352 v4hi __builtin_arm_wmaxsh (v4hi, v4hi); 15353 v2si __builtin_arm_wmaxsw (v2si, v2si); 15354 v8qi __builtin_arm_wmaxub (v8qi, v8qi); 15355 v4hi __builtin_arm_wmaxuh (v4hi, v4hi); 15356 v2si __builtin_arm_wmaxuw (v2si, v2si); 15357 v8qi __builtin_arm_wminsb (v8qi, v8qi); 15358 v4hi __builtin_arm_wminsh (v4hi, v4hi); 15359 v2si __builtin_arm_wminsw (v2si, v2si); 15360 v8qi __builtin_arm_wminub (v8qi, v8qi); 15361 v4hi __builtin_arm_wminuh (v4hi, v4hi); 15362 v2si __builtin_arm_wminuw (v2si, v2si); 15363 v4hi __builtin_arm_wmulsm (v4hi, v4hi); 15364 v4hi __builtin_arm_wmulul (v4hi, v4hi); 15365 v4hi __builtin_arm_wmulum (v4hi, v4hi); 15366 long long __builtin_arm_wor (long long, long long); 15367 v2si __builtin_arm_wpackdss (long long, long long); 15368 v2si __builtin_arm_wpackdus (long long, long long); 15369 v8qi __builtin_arm_wpackhss (v4hi, v4hi); 15370 v8qi __builtin_arm_wpackhus (v4hi, v4hi); 15371 v4hi __builtin_arm_wpackwss (v2si, v2si); 15372 v4hi __builtin_arm_wpackwus (v2si, v2si); 15373 long long __builtin_arm_wrord (long long, long long); 15374 long long __builtin_arm_wrordi (long long, int); 15375 v4hi __builtin_arm_wrorh (v4hi, long long); 15376 v4hi __builtin_arm_wrorhi (v4hi, int); 15377 v2si __builtin_arm_wrorw (v2si, long long); 15378 v2si __builtin_arm_wrorwi (v2si, int); 15379 v2si __builtin_arm_wsadb (v2si, v8qi, v8qi); 15380 v2si __builtin_arm_wsadbz (v8qi, v8qi); 15381 v2si __builtin_arm_wsadh (v2si, v4hi, v4hi); 15382 v2si __builtin_arm_wsadhz (v4hi, v4hi); 15383 v4hi __builtin_arm_wshufh (v4hi, int); 15384 long long __builtin_arm_wslld (long long, long long); 15385 long long __builtin_arm_wslldi (long long, int); 15386 v4hi __builtin_arm_wsllh (v4hi, long long); 15387 v4hi __builtin_arm_wsllhi (v4hi, int); 15388 v2si __builtin_arm_wsllw (v2si, long long); 15389 v2si __builtin_arm_wsllwi (v2si, int); 15390 long long __builtin_arm_wsrad (long long, long long); 15391 long long __builtin_arm_wsradi (long long, int); 15392 v4hi __builtin_arm_wsrah (v4hi, long long); 15393 v4hi __builtin_arm_wsrahi (v4hi, int); 15394 v2si __builtin_arm_wsraw (v2si, long long); 15395 v2si __builtin_arm_wsrawi (v2si, int); 15396 long long __builtin_arm_wsrld (long long, long long); 15397 long long __builtin_arm_wsrldi (long long, int); 15398 v4hi __builtin_arm_wsrlh (v4hi, long long); 15399 v4hi __builtin_arm_wsrlhi (v4hi, int); 15400 v2si __builtin_arm_wsrlw (v2si, long long); 15401 v2si __builtin_arm_wsrlwi (v2si, int); 15402 v8qi __builtin_arm_wsubb (v8qi, v8qi); 15403 v8qi __builtin_arm_wsubbss (v8qi, v8qi); 15404 v8qi __builtin_arm_wsubbus (v8qi, v8qi); 15405 v4hi __builtin_arm_wsubh (v4hi, v4hi); 15406 v4hi __builtin_arm_wsubhss (v4hi, v4hi); 15407 v4hi __builtin_arm_wsubhus (v4hi, v4hi); 15408 v2si __builtin_arm_wsubw (v2si, v2si); 15409 v2si __builtin_arm_wsubwss (v2si, v2si); 15410 v2si __builtin_arm_wsubwus (v2si, v2si); 15411 v4hi __builtin_arm_wunpckehsb (v8qi); 15412 v2si __builtin_arm_wunpckehsh (v4hi); 15413 long long __builtin_arm_wunpckehsw (v2si); 15414 v4hi __builtin_arm_wunpckehub (v8qi); 15415 v2si __builtin_arm_wunpckehuh (v4hi); 15416 long long __builtin_arm_wunpckehuw (v2si); 15417 v4hi __builtin_arm_wunpckelsb (v8qi); 15418 v2si __builtin_arm_wunpckelsh (v4hi); 15419 long long __builtin_arm_wunpckelsw (v2si); 15420 v4hi __builtin_arm_wunpckelub (v8qi); 15421 v2si __builtin_arm_wunpckeluh (v4hi); 15422 long long __builtin_arm_wunpckeluw (v2si); 15423 v8qi __builtin_arm_wunpckihb (v8qi, v8qi); 15424 v4hi __builtin_arm_wunpckihh (v4hi, v4hi); 15425 v2si __builtin_arm_wunpckihw (v2si, v2si); 15426 v8qi __builtin_arm_wunpckilb (v8qi, v8qi); 15427 v4hi __builtin_arm_wunpckilh (v4hi, v4hi); 15428 v2si __builtin_arm_wunpckilw (v2si, v2si); 15429 long long __builtin_arm_wxor (long long, long long); 15430 long long __builtin_arm_wzero (); 15431 @end smallexample 15432 15433 15434 @node ARM C Language Extensions (ACLE) 15435 @subsection ARM C Language Extensions (ACLE) 15436 15437 GCC implements extensions for C as described in the ARM C Language 15438 Extensions (ACLE) specification, which can be found at 15439 @uref{https://developer.arm.com/documentation/ihi0053/latest/}. 15440 15441 As a part of ACLE, GCC implements extensions for Advanced SIMD as described in 15442 the ARM C Language Extensions Specification. The complete list of Advanced SIMD 15443 intrinsics can be found at 15444 @uref{https://developer.arm.com/documentation/ihi0073/latest/}. 15445 The built-in intrinsics for the Advanced SIMD extension are available when 15446 NEON is enabled. 15447 15448 Currently, ARM and AArch64 back ends do not support ACLE 2.0 fully. Both 15449 back ends support CRC32 intrinsics and the ARM back end supports the 15450 Coprocessor intrinsics, all from @file{arm_acle.h}. The ARM back end's 16-bit 15451 floating-point Advanced SIMD intrinsics currently comply to ACLE v1.1. 15452 AArch64's back end does not have support for 16-bit floating point Advanced SIMD 15453 intrinsics yet. 15454 15455 See @ref{ARM Options} and @ref{AArch64 Options} for more information on the 15456 availability of extensions. 15457 15458 @node ARM Floating Point Status and Control Intrinsics 15459 @subsection ARM Floating Point Status and Control Intrinsics 15460 15461 These built-in functions are available for the ARM family of 15462 processors with floating-point unit. 15463 15464 @smallexample 15465 unsigned int __builtin_arm_get_fpscr (); 15466 void __builtin_arm_set_fpscr (unsigned int); 15467 @end smallexample 15468 15469 @node ARM ARMv8-M Security Extensions 15470 @subsection ARM ARMv8-M Security Extensions 15471 15472 GCC implements the ARMv8-M Security Extensions as described in the ARMv8-M 15473 Security Extensions: Requirements on Development Tools Engineering 15474 Specification, which can be found at 15475 @uref{https://developer.arm.com/documentation/ecm0359818/latest/}. 15476 15477 As part of the Security Extensions GCC implements two new function attributes: 15478 @code{cmse_nonsecure_entry} and @code{cmse_nonsecure_call}. 15479 15480 As part of the Security Extensions GCC implements the intrinsics below. FPTR 15481 is used here to mean any function pointer type. 15482 15483 @smallexample 15484 cmse_address_info_t cmse_TT (void *); 15485 cmse_address_info_t cmse_TT_fptr (FPTR); 15486 cmse_address_info_t cmse_TTT (void *); 15487 cmse_address_info_t cmse_TTT_fptr (FPTR); 15488 cmse_address_info_t cmse_TTA (void *); 15489 cmse_address_info_t cmse_TTA_fptr (FPTR); 15490 cmse_address_info_t cmse_TTAT (void *); 15491 cmse_address_info_t cmse_TTAT_fptr (FPTR); 15492 void * cmse_check_address_range (void *, size_t, int); 15493 typeof(p) cmse_nsfptr_create (FPTR p); 15494 intptr_t cmse_is_nsfptr (FPTR); 15495 int cmse_nonsecure_caller (void); 15496 @end smallexample 15497 15498 @node AVR Built-in Functions 15499 @subsection AVR Built-in Functions 15500 15501 For each built-in function for AVR, there is an equally named, 15502 uppercase built-in macro defined. That way users can easily query if 15503 or if not a specific built-in is implemented or not. For example, if 15504 @code{__builtin_avr_nop} is available the macro 15505 @code{__BUILTIN_AVR_NOP} is defined to @code{1} and undefined otherwise. 15506 15507 @table @code 15508 15509 @item void __builtin_avr_nop (void) 15510 @itemx void __builtin_avr_sei (void) 15511 @itemx void __builtin_avr_cli (void) 15512 @itemx void __builtin_avr_sleep (void) 15513 @itemx void __builtin_avr_wdr (void) 15514 @itemx unsigned char __builtin_avr_swap (unsigned char) 15515 @itemx unsigned int __builtin_avr_fmul (unsigned char, unsigned char) 15516 @itemx int __builtin_avr_fmuls (char, char) 15517 @itemx int __builtin_avr_fmulsu (char, unsigned char) 15518 These built-in functions map to the respective machine 15519 instruction, i.e.@: @code{nop}, @code{sei}, @code{cli}, @code{sleep}, 15520 @code{wdr}, @code{swap}, @code{fmul}, @code{fmuls} 15521 resp. @code{fmulsu}. The three @code{fmul*} built-ins are implemented 15522 as library call if no hardware multiplier is available. 15523 15524 @item void __builtin_avr_delay_cycles (unsigned long ticks) 15525 Delay execution for @var{ticks} cycles. Note that this 15526 built-in does not take into account the effect of interrupts that 15527 might increase delay time. @var{ticks} must be a compile-time 15528 integer constant; delays with a variable number of cycles are not supported. 15529 15530 @item char __builtin_avr_flash_segment (const __memx void*) 15531 This built-in takes a byte address to the 24-bit 15532 @ref{AVR Named Address Spaces,address space} @code{__memx} and returns 15533 the number of the flash segment (the 64 KiB chunk) where the address 15534 points to. Counting starts at @code{0}. 15535 If the address does not point to flash memory, return @code{-1}. 15536 15537 @item uint8_t __builtin_avr_insert_bits (uint32_t map, uint8_t bits, uint8_t val) 15538 Insert bits from @var{bits} into @var{val} and return the resulting 15539 value. The nibbles of @var{map} determine how the insertion is 15540 performed: Let @var{X} be the @var{n}-th nibble of @var{map} 15541 @enumerate 15542 @item If @var{X} is @code{0xf}, 15543 then the @var{n}-th bit of @var{val} is returned unaltered. 15544 15545 @item If X is in the range 0@dots{}7, 15546 then the @var{n}-th result bit is set to the @var{X}-th bit of @var{bits} 15547 15548 @item If X is in the range 8@dots{}@code{0xe}, 15549 then the @var{n}-th result bit is undefined. 15550 @end enumerate 15551 15552 @noindent 15553 One typical use case for this built-in is adjusting input and 15554 output values to non-contiguous port layouts. Some examples: 15555 15556 @smallexample 15557 // same as val, bits is unused 15558 __builtin_avr_insert_bits (0xffffffff, bits, val); 15559 @end smallexample 15560 15561 @smallexample 15562 // same as bits, val is unused 15563 __builtin_avr_insert_bits (0x76543210, bits, val); 15564 @end smallexample 15565 15566 @smallexample 15567 // same as rotating bits by 4 15568 __builtin_avr_insert_bits (0x32107654, bits, 0); 15569 @end smallexample 15570 15571 @smallexample 15572 // high nibble of result is the high nibble of val 15573 // low nibble of result is the low nibble of bits 15574 __builtin_avr_insert_bits (0xffff3210, bits, val); 15575 @end smallexample 15576 15577 @smallexample 15578 // reverse the bit order of bits 15579 __builtin_avr_insert_bits (0x01234567, bits, 0); 15580 @end smallexample 15581 15582 @item void __builtin_avr_nops (unsigned count) 15583 Insert @var{count} @code{NOP} instructions. 15584 The number of instructions must be a compile-time integer constant. 15585 15586 @end table 15587 15588 @noindent 15589 There are many more AVR-specific built-in functions that are used to 15590 implement the ISO/IEC TR 18037 ``Embedded C'' fixed-point functions of 15591 section 7.18a.6. You don't need to use these built-ins directly. 15592 Instead, use the declarations as supplied by the @code{stdfix.h} header 15593 with GNU-C99: 15594 15595 @smallexample 15596 #include <stdfix.h> 15597 15598 // Re-interpret the bit representation of unsigned 16-bit 15599 // integer @var{uval} as Q-format 0.16 value. 15600 unsigned fract get_bits (uint_ur_t uval) 15601 @{ 15602 return urbits (uval); 15603 @} 15604 @end smallexample 15605 15606 @node Blackfin Built-in Functions 15607 @subsection Blackfin Built-in Functions 15608 15609 Currently, there are two Blackfin-specific built-in functions. These are 15610 used for generating @code{CSYNC} and @code{SSYNC} machine insns without 15611 using inline assembly; by using these built-in functions the compiler can 15612 automatically add workarounds for hardware errata involving these 15613 instructions. These functions are named as follows: 15614 15615 @smallexample 15616 void __builtin_bfin_csync (void); 15617 void __builtin_bfin_ssync (void); 15618 @end smallexample 15619 15620 @node BPF Built-in Functions 15621 @subsection BPF Built-in Functions 15622 15623 The following built-in functions are available for eBPF targets. 15624 15625 @deftypefn {Built-in Function} unsigned long long __builtin_bpf_load_byte (unsigned long long @var{offset}) 15626 Load a byte from the @code{struct sk_buff} packet data pointed by the register @code{%r6} and return it. 15627 @end deftypefn 15628 15629 @deftypefn {Built-in Function} unsigned long long __builtin_bpf_load_half (unsigned long long @var{offset}) 15630 Load 16-bits from the @code{struct sk_buff} packet data pointed by the register @code{%r6} and return it. 15631 @end deftypefn 15632 15633 @deftypefn {Built-in Function} unsigned long long __builtin_bpf_load_word (unsigned long long @var{offset}) 15634 Load 32-bits from the @code{struct sk_buff} packet data pointed by the register @code{%r6} and return it. 15635 @end deftypefn 15636 15637 @deftypefn {Built-in Function} void * __builtin_preserve_access_index (@var{expr}) 15638 BPF Compile Once-Run Everywhere (CO-RE) support. Instruct GCC to generate CO-RE relocation records for any accesses to aggregate data structures (struct, union, array types) in @var{expr}. This builtin is otherwise transparent, the return value is whatever @var{expr} evaluates to. It is also overloaded: @var{expr} may be of any type (not necessarily a pointer), the return type is the same. Has no effect if @code{-mco-re} is not in effect (either specified or implied). 15639 @end deftypefn 15640 15641 @node FR-V Built-in Functions 15642 @subsection FR-V Built-in Functions 15643 15644 GCC provides many FR-V-specific built-in functions. In general, 15645 these functions are intended to be compatible with those described 15646 by @cite{FR-V Family, Softune C/C++ Compiler Manual (V6), Fujitsu 15647 Semiconductor}. The two exceptions are @code{__MDUNPACKH} and 15648 @code{__MBTOHE}, the GCC forms of which pass 128-bit values by 15649 pointer rather than by value. 15650 15651 Most of the functions are named after specific FR-V instructions. 15652 Such functions are said to be ``directly mapped'' and are summarized 15653 here in tabular form. 15654 15655 @menu 15656 * Argument Types:: 15657 * Directly-mapped Integer Functions:: 15658 * Directly-mapped Media Functions:: 15659 * Raw read/write Functions:: 15660 * Other Built-in Functions:: 15661 @end menu 15662 15663 @node Argument Types 15664 @subsubsection Argument Types 15665 15666 The arguments to the built-in functions can be divided into three groups: 15667 register numbers, compile-time constants and run-time values. In order 15668 to make this classification clear at a glance, the arguments and return 15669 values are given the following pseudo types: 15670 15671 @multitable @columnfractions .20 .30 .15 .35 15672 @headitem Pseudo type @tab Real C type @tab Constant? @tab Description 15673 @item @code{uh} @tab @code{unsigned short} @tab No @tab an unsigned halfword 15674 @item @code{uw1} @tab @code{unsigned int} @tab No @tab an unsigned word 15675 @item @code{sw1} @tab @code{int} @tab No @tab a signed word 15676 @item @code{uw2} @tab @code{unsigned long long} @tab No 15677 @tab an unsigned doubleword 15678 @item @code{sw2} @tab @code{long long} @tab No @tab a signed doubleword 15679 @item @code{const} @tab @code{int} @tab Yes @tab an integer constant 15680 @item @code{acc} @tab @code{int} @tab Yes @tab an ACC register number 15681 @item @code{iacc} @tab @code{int} @tab Yes @tab an IACC register number 15682 @end multitable 15683 15684 These pseudo types are not defined by GCC, they are simply a notational 15685 convenience used in this manual. 15686 15687 Arguments of type @code{uh}, @code{uw1}, @code{sw1}, @code{uw2} 15688 and @code{sw2} are evaluated at run time. They correspond to 15689 register operands in the underlying FR-V instructions. 15690 15691 @code{const} arguments represent immediate operands in the underlying 15692 FR-V instructions. They must be compile-time constants. 15693 15694 @code{acc} arguments are evaluated at compile time and specify the number 15695 of an accumulator register. For example, an @code{acc} argument of 2 15696 selects the ACC2 register. 15697 15698 @code{iacc} arguments are similar to @code{acc} arguments but specify the 15699 number of an IACC register. See @pxref{Other Built-in Functions} 15700 for more details. 15701 15702 @node Directly-mapped Integer Functions 15703 @subsubsection Directly-Mapped Integer Functions 15704 15705 The functions listed below map directly to FR-V I-type instructions. 15706 15707 @multitable @columnfractions .45 .32 .23 15708 @headitem Function prototype @tab Example usage @tab Assembly output 15709 @item @code{sw1 __ADDSS (sw1, sw1)} 15710 @tab @code{@var{c} = __ADDSS (@var{a}, @var{b})} 15711 @tab @code{ADDSS @var{a},@var{b},@var{c}} 15712 @item @code{sw1 __SCAN (sw1, sw1)} 15713 @tab @code{@var{c} = __SCAN (@var{a}, @var{b})} 15714 @tab @code{SCAN @var{a},@var{b},@var{c}} 15715 @item @code{sw1 __SCUTSS (sw1)} 15716 @tab @code{@var{b} = __SCUTSS (@var{a})} 15717 @tab @code{SCUTSS @var{a},@var{b}} 15718 @item @code{sw1 __SLASS (sw1, sw1)} 15719 @tab @code{@var{c} = __SLASS (@var{a}, @var{b})} 15720 @tab @code{SLASS @var{a},@var{b},@var{c}} 15721 @item @code{void __SMASS (sw1, sw1)} 15722 @tab @code{__SMASS (@var{a}, @var{b})} 15723 @tab @code{SMASS @var{a},@var{b}} 15724 @item @code{void __SMSSS (sw1, sw1)} 15725 @tab @code{__SMSSS (@var{a}, @var{b})} 15726 @tab @code{SMSSS @var{a},@var{b}} 15727 @item @code{void __SMU (sw1, sw1)} 15728 @tab @code{__SMU (@var{a}, @var{b})} 15729 @tab @code{SMU @var{a},@var{b}} 15730 @item @code{sw2 __SMUL (sw1, sw1)} 15731 @tab @code{@var{c} = __SMUL (@var{a}, @var{b})} 15732 @tab @code{SMUL @var{a},@var{b},@var{c}} 15733 @item @code{sw1 __SUBSS (sw1, sw1)} 15734 @tab @code{@var{c} = __SUBSS (@var{a}, @var{b})} 15735 @tab @code{SUBSS @var{a},@var{b},@var{c}} 15736 @item @code{uw2 __UMUL (uw1, uw1)} 15737 @tab @code{@var{c} = __UMUL (@var{a}, @var{b})} 15738 @tab @code{UMUL @var{a},@var{b},@var{c}} 15739 @end multitable 15740 15741 @node Directly-mapped Media Functions 15742 @subsubsection Directly-Mapped Media Functions 15743 15744 The functions listed below map directly to FR-V M-type instructions. 15745 15746 @multitable @columnfractions .45 .32 .23 15747 @headitem Function prototype @tab Example usage @tab Assembly output 15748 @item @code{uw1 __MABSHS (sw1)} 15749 @tab @code{@var{b} = __MABSHS (@var{a})} 15750 @tab @code{MABSHS @var{a},@var{b}} 15751 @item @code{void __MADDACCS (acc, acc)} 15752 @tab @code{__MADDACCS (@var{b}, @var{a})} 15753 @tab @code{MADDACCS @var{a},@var{b}} 15754 @item @code{sw1 __MADDHSS (sw1, sw1)} 15755 @tab @code{@var{c} = __MADDHSS (@var{a}, @var{b})} 15756 @tab @code{MADDHSS @var{a},@var{b},@var{c}} 15757 @item @code{uw1 __MADDHUS (uw1, uw1)} 15758 @tab @code{@var{c} = __MADDHUS (@var{a}, @var{b})} 15759 @tab @code{MADDHUS @var{a},@var{b},@var{c}} 15760 @item @code{uw1 __MAND (uw1, uw1)} 15761 @tab @code{@var{c} = __MAND (@var{a}, @var{b})} 15762 @tab @code{MAND @var{a},@var{b},@var{c}} 15763 @item @code{void __MASACCS (acc, acc)} 15764 @tab @code{__MASACCS (@var{b}, @var{a})} 15765 @tab @code{MASACCS @var{a},@var{b}} 15766 @item @code{uw1 __MAVEH (uw1, uw1)} 15767 @tab @code{@var{c} = __MAVEH (@var{a}, @var{b})} 15768 @tab @code{MAVEH @var{a},@var{b},@var{c}} 15769 @item @code{uw2 __MBTOH (uw1)} 15770 @tab @code{@var{b} = __MBTOH (@var{a})} 15771 @tab @code{MBTOH @var{a},@var{b}} 15772 @item @code{void __MBTOHE (uw1 *, uw1)} 15773 @tab @code{__MBTOHE (&@var{b}, @var{a})} 15774 @tab @code{MBTOHE @var{a},@var{b}} 15775 @item @code{void __MCLRACC (acc)} 15776 @tab @code{__MCLRACC (@var{a})} 15777 @tab @code{MCLRACC @var{a}} 15778 @item @code{void __MCLRACCA (void)} 15779 @tab @code{__MCLRACCA ()} 15780 @tab @code{MCLRACCA} 15781 @item @code{uw1 __Mcop1 (uw1, uw1)} 15782 @tab @code{@var{c} = __Mcop1 (@var{a}, @var{b})} 15783 @tab @code{Mcop1 @var{a},@var{b},@var{c}} 15784 @item @code{uw1 __Mcop2 (uw1, uw1)} 15785 @tab @code{@var{c} = __Mcop2 (@var{a}, @var{b})} 15786 @tab @code{Mcop2 @var{a},@var{b},@var{c}} 15787 @item @code{uw1 __MCPLHI (uw2, const)} 15788 @tab @code{@var{c} = __MCPLHI (@var{a}, @var{b})} 15789 @tab @code{MCPLHI @var{a},#@var{b},@var{c}} 15790 @item @code{uw1 __MCPLI (uw2, const)} 15791 @tab @code{@var{c} = __MCPLI (@var{a}, @var{b})} 15792 @tab @code{MCPLI @var{a},#@var{b},@var{c}} 15793 @item @code{void __MCPXIS (acc, sw1, sw1)} 15794 @tab @code{__MCPXIS (@var{c}, @var{a}, @var{b})} 15795 @tab @code{MCPXIS @var{a},@var{b},@var{c}} 15796 @item @code{void __MCPXIU (acc, uw1, uw1)} 15797 @tab @code{__MCPXIU (@var{c}, @var{a}, @var{b})} 15798 @tab @code{MCPXIU @var{a},@var{b},@var{c}} 15799 @item @code{void __MCPXRS (acc, sw1, sw1)} 15800 @tab @code{__MCPXRS (@var{c}, @var{a}, @var{b})} 15801 @tab @code{MCPXRS @var{a},@var{b},@var{c}} 15802 @item @code{void __MCPXRU (acc, uw1, uw1)} 15803 @tab @code{__MCPXRU (@var{c}, @var{a}, @var{b})} 15804 @tab @code{MCPXRU @var{a},@var{b},@var{c}} 15805 @item @code{uw1 __MCUT (acc, uw1)} 15806 @tab @code{@var{c} = __MCUT (@var{a}, @var{b})} 15807 @tab @code{MCUT @var{a},@var{b},@var{c}} 15808 @item @code{uw1 __MCUTSS (acc, sw1)} 15809 @tab @code{@var{c} = __MCUTSS (@var{a}, @var{b})} 15810 @tab @code{MCUTSS @var{a},@var{b},@var{c}} 15811 @item @code{void __MDADDACCS (acc, acc)} 15812 @tab @code{__MDADDACCS (@var{b}, @var{a})} 15813 @tab @code{MDADDACCS @var{a},@var{b}} 15814 @item @code{void __MDASACCS (acc, acc)} 15815 @tab @code{__MDASACCS (@var{b}, @var{a})} 15816 @tab @code{MDASACCS @var{a},@var{b}} 15817 @item @code{uw2 __MDCUTSSI (acc, const)} 15818 @tab @code{@var{c} = __MDCUTSSI (@var{a}, @var{b})} 15819 @tab @code{MDCUTSSI @var{a},#@var{b},@var{c}} 15820 @item @code{uw2 __MDPACKH (uw2, uw2)} 15821 @tab @code{@var{c} = __MDPACKH (@var{a}, @var{b})} 15822 @tab @code{MDPACKH @var{a},@var{b},@var{c}} 15823 @item @code{uw2 __MDROTLI (uw2, const)} 15824 @tab @code{@var{c} = __MDROTLI (@var{a}, @var{b})} 15825 @tab @code{MDROTLI @var{a},#@var{b},@var{c}} 15826 @item @code{void __MDSUBACCS (acc, acc)} 15827 @tab @code{__MDSUBACCS (@var{b}, @var{a})} 15828 @tab @code{MDSUBACCS @var{a},@var{b}} 15829 @item @code{void __MDUNPACKH (uw1 *, uw2)} 15830 @tab @code{__MDUNPACKH (&@var{b}, @var{a})} 15831 @tab @code{MDUNPACKH @var{a},@var{b}} 15832 @item @code{uw2 __MEXPDHD (uw1, const)} 15833 @tab @code{@var{c} = __MEXPDHD (@var{a}, @var{b})} 15834 @tab @code{MEXPDHD @var{a},#@var{b},@var{c}} 15835 @item @code{uw1 __MEXPDHW (uw1, const)} 15836 @tab @code{@var{c} = __MEXPDHW (@var{a}, @var{b})} 15837 @tab @code{MEXPDHW @var{a},#@var{b},@var{c}} 15838 @item @code{uw1 __MHDSETH (uw1, const)} 15839 @tab @code{@var{c} = __MHDSETH (@var{a}, @var{b})} 15840 @tab @code{MHDSETH @var{a},#@var{b},@var{c}} 15841 @item @code{sw1 __MHDSETS (const)} 15842 @tab @code{@var{b} = __MHDSETS (@var{a})} 15843 @tab @code{MHDSETS #@var{a},@var{b}} 15844 @item @code{uw1 __MHSETHIH (uw1, const)} 15845 @tab @code{@var{b} = __MHSETHIH (@var{b}, @var{a})} 15846 @tab @code{MHSETHIH #@var{a},@var{b}} 15847 @item @code{sw1 __MHSETHIS (sw1, const)} 15848 @tab @code{@var{b} = __MHSETHIS (@var{b}, @var{a})} 15849 @tab @code{MHSETHIS #@var{a},@var{b}} 15850 @item @code{uw1 __MHSETLOH (uw1, const)} 15851 @tab @code{@var{b} = __MHSETLOH (@var{b}, @var{a})} 15852 @tab @code{MHSETLOH #@var{a},@var{b}} 15853 @item @code{sw1 __MHSETLOS (sw1, const)} 15854 @tab @code{@var{b} = __MHSETLOS (@var{b}, @var{a})} 15855 @tab @code{MHSETLOS #@var{a},@var{b}} 15856 @item @code{uw1 __MHTOB (uw2)} 15857 @tab @code{@var{b} = __MHTOB (@var{a})} 15858 @tab @code{MHTOB @var{a},@var{b}} 15859 @item @code{void __MMACHS (acc, sw1, sw1)} 15860 @tab @code{__MMACHS (@var{c}, @var{a}, @var{b})} 15861 @tab @code{MMACHS @var{a},@var{b},@var{c}} 15862 @item @code{void __MMACHU (acc, uw1, uw1)} 15863 @tab @code{__MMACHU (@var{c}, @var{a}, @var{b})} 15864 @tab @code{MMACHU @var{a},@var{b},@var{c}} 15865 @item @code{void __MMRDHS (acc, sw1, sw1)} 15866 @tab @code{__MMRDHS (@var{c}, @var{a}, @var{b})} 15867 @tab @code{MMRDHS @var{a},@var{b},@var{c}} 15868 @item @code{void __MMRDHU (acc, uw1, uw1)} 15869 @tab @code{__MMRDHU (@var{c}, @var{a}, @var{b})} 15870 @tab @code{MMRDHU @var{a},@var{b},@var{c}} 15871 @item @code{void __MMULHS (acc, sw1, sw1)} 15872 @tab @code{__MMULHS (@var{c}, @var{a}, @var{b})} 15873 @tab @code{MMULHS @var{a},@var{b},@var{c}} 15874 @item @code{void __MMULHU (acc, uw1, uw1)} 15875 @tab @code{__MMULHU (@var{c}, @var{a}, @var{b})} 15876 @tab @code{MMULHU @var{a},@var{b},@var{c}} 15877 @item @code{void __MMULXHS (acc, sw1, sw1)} 15878 @tab @code{__MMULXHS (@var{c}, @var{a}, @var{b})} 15879 @tab @code{MMULXHS @var{a},@var{b},@var{c}} 15880 @item @code{void __MMULXHU (acc, uw1, uw1)} 15881 @tab @code{__MMULXHU (@var{c}, @var{a}, @var{b})} 15882 @tab @code{MMULXHU @var{a},@var{b},@var{c}} 15883 @item @code{uw1 __MNOT (uw1)} 15884 @tab @code{@var{b} = __MNOT (@var{a})} 15885 @tab @code{MNOT @var{a},@var{b}} 15886 @item @code{uw1 __MOR (uw1, uw1)} 15887 @tab @code{@var{c} = __MOR (@var{a}, @var{b})} 15888 @tab @code{MOR @var{a},@var{b},@var{c}} 15889 @item @code{uw1 __MPACKH (uh, uh)} 15890 @tab @code{@var{c} = __MPACKH (@var{a}, @var{b})} 15891 @tab @code{MPACKH @var{a},@var{b},@var{c}} 15892 @item @code{sw2 __MQADDHSS (sw2, sw2)} 15893 @tab @code{@var{c} = __MQADDHSS (@var{a}, @var{b})} 15894 @tab @code{MQADDHSS @var{a},@var{b},@var{c}} 15895 @item @code{uw2 __MQADDHUS (uw2, uw2)} 15896 @tab @code{@var{c} = __MQADDHUS (@var{a}, @var{b})} 15897 @tab @code{MQADDHUS @var{a},@var{b},@var{c}} 15898 @item @code{void __MQCPXIS (acc, sw2, sw2)} 15899 @tab @code{__MQCPXIS (@var{c}, @var{a}, @var{b})} 15900 @tab @code{MQCPXIS @var{a},@var{b},@var{c}} 15901 @item @code{void __MQCPXIU (acc, uw2, uw2)} 15902 @tab @code{__MQCPXIU (@var{c}, @var{a}, @var{b})} 15903 @tab @code{MQCPXIU @var{a},@var{b},@var{c}} 15904 @item @code{void __MQCPXRS (acc, sw2, sw2)} 15905 @tab @code{__MQCPXRS (@var{c}, @var{a}, @var{b})} 15906 @tab @code{MQCPXRS @var{a},@var{b},@var{c}} 15907 @item @code{void __MQCPXRU (acc, uw2, uw2)} 15908 @tab @code{__MQCPXRU (@var{c}, @var{a}, @var{b})} 15909 @tab @code{MQCPXRU @var{a},@var{b},@var{c}} 15910 @item @code{sw2 __MQLCLRHS (sw2, sw2)} 15911 @tab @code{@var{c} = __MQLCLRHS (@var{a}, @var{b})} 15912 @tab @code{MQLCLRHS @var{a},@var{b},@var{c}} 15913 @item @code{sw2 __MQLMTHS (sw2, sw2)} 15914 @tab @code{@var{c} = __MQLMTHS (@var{a}, @var{b})} 15915 @tab @code{MQLMTHS @var{a},@var{b},@var{c}} 15916 @item @code{void __MQMACHS (acc, sw2, sw2)} 15917 @tab @code{__MQMACHS (@var{c}, @var{a}, @var{b})} 15918 @tab @code{MQMACHS @var{a},@var{b},@var{c}} 15919 @item @code{void __MQMACHU (acc, uw2, uw2)} 15920 @tab @code{__MQMACHU (@var{c}, @var{a}, @var{b})} 15921 @tab @code{MQMACHU @var{a},@var{b},@var{c}} 15922 @item @code{void __MQMACXHS (acc, sw2, sw2)} 15923 @tab @code{__MQMACXHS (@var{c}, @var{a}, @var{b})} 15924 @tab @code{MQMACXHS @var{a},@var{b},@var{c}} 15925 @item @code{void __MQMULHS (acc, sw2, sw2)} 15926 @tab @code{__MQMULHS (@var{c}, @var{a}, @var{b})} 15927 @tab @code{MQMULHS @var{a},@var{b},@var{c}} 15928 @item @code{void __MQMULHU (acc, uw2, uw2)} 15929 @tab @code{__MQMULHU (@var{c}, @var{a}, @var{b})} 15930 @tab @code{MQMULHU @var{a},@var{b},@var{c}} 15931 @item @code{void __MQMULXHS (acc, sw2, sw2)} 15932 @tab @code{__MQMULXHS (@var{c}, @var{a}, @var{b})} 15933 @tab @code{MQMULXHS @var{a},@var{b},@var{c}} 15934 @item @code{void __MQMULXHU (acc, uw2, uw2)} 15935 @tab @code{__MQMULXHU (@var{c}, @var{a}, @var{b})} 15936 @tab @code{MQMULXHU @var{a},@var{b},@var{c}} 15937 @item @code{sw2 __MQSATHS (sw2, sw2)} 15938 @tab @code{@var{c} = __MQSATHS (@var{a}, @var{b})} 15939 @tab @code{MQSATHS @var{a},@var{b},@var{c}} 15940 @item @code{uw2 __MQSLLHI (uw2, int)} 15941 @tab @code{@var{c} = __MQSLLHI (@var{a}, @var{b})} 15942 @tab @code{MQSLLHI @var{a},@var{b},@var{c}} 15943 @item @code{sw2 __MQSRAHI (sw2, int)} 15944 @tab @code{@var{c} = __MQSRAHI (@var{a}, @var{b})} 15945 @tab @code{MQSRAHI @var{a},@var{b},@var{c}} 15946 @item @code{sw2 __MQSUBHSS (sw2, sw2)} 15947 @tab @code{@var{c} = __MQSUBHSS (@var{a}, @var{b})} 15948 @tab @code{MQSUBHSS @var{a},@var{b},@var{c}} 15949 @item @code{uw2 __MQSUBHUS (uw2, uw2)} 15950 @tab @code{@var{c} = __MQSUBHUS (@var{a}, @var{b})} 15951 @tab @code{MQSUBHUS @var{a},@var{b},@var{c}} 15952 @item @code{void __MQXMACHS (acc, sw2, sw2)} 15953 @tab @code{__MQXMACHS (@var{c}, @var{a}, @var{b})} 15954 @tab @code{MQXMACHS @var{a},@var{b},@var{c}} 15955 @item @code{void __MQXMACXHS (acc, sw2, sw2)} 15956 @tab @code{__MQXMACXHS (@var{c}, @var{a}, @var{b})} 15957 @tab @code{MQXMACXHS @var{a},@var{b},@var{c}} 15958 @item @code{uw1 __MRDACC (acc)} 15959 @tab @code{@var{b} = __MRDACC (@var{a})} 15960 @tab @code{MRDACC @var{a},@var{b}} 15961 @item @code{uw1 __MRDACCG (acc)} 15962 @tab @code{@var{b} = __MRDACCG (@var{a})} 15963 @tab @code{MRDACCG @var{a},@var{b}} 15964 @item @code{uw1 __MROTLI (uw1, const)} 15965 @tab @code{@var{c} = __MROTLI (@var{a}, @var{b})} 15966 @tab @code{MROTLI @var{a},#@var{b},@var{c}} 15967 @item @code{uw1 __MROTRI (uw1, const)} 15968 @tab @code{@var{c} = __MROTRI (@var{a}, @var{b})} 15969 @tab @code{MROTRI @var{a},#@var{b},@var{c}} 15970 @item @code{sw1 __MSATHS (sw1, sw1)} 15971 @tab @code{@var{c} = __MSATHS (@var{a}, @var{b})} 15972 @tab @code{MSATHS @var{a},@var{b},@var{c}} 15973 @item @code{uw1 __MSATHU (uw1, uw1)} 15974 @tab @code{@var{c} = __MSATHU (@var{a}, @var{b})} 15975 @tab @code{MSATHU @var{a},@var{b},@var{c}} 15976 @item @code{uw1 __MSLLHI (uw1, const)} 15977 @tab @code{@var{c} = __MSLLHI (@var{a}, @var{b})} 15978 @tab @code{MSLLHI @var{a},#@var{b},@var{c}} 15979 @item @code{sw1 __MSRAHI (sw1, const)} 15980 @tab @code{@var{c} = __MSRAHI (@var{a}, @var{b})} 15981 @tab @code{MSRAHI @var{a},#@var{b},@var{c}} 15982 @item @code{uw1 __MSRLHI (uw1, const)} 15983 @tab @code{@var{c} = __MSRLHI (@var{a}, @var{b})} 15984 @tab @code{MSRLHI @var{a},#@var{b},@var{c}} 15985 @item @code{void __MSUBACCS (acc, acc)} 15986 @tab @code{__MSUBACCS (@var{b}, @var{a})} 15987 @tab @code{MSUBACCS @var{a},@var{b}} 15988 @item @code{sw1 __MSUBHSS (sw1, sw1)} 15989 @tab @code{@var{c} = __MSUBHSS (@var{a}, @var{b})} 15990 @tab @code{MSUBHSS @var{a},@var{b},@var{c}} 15991 @item @code{uw1 __MSUBHUS (uw1, uw1)} 15992 @tab @code{@var{c} = __MSUBHUS (@var{a}, @var{b})} 15993 @tab @code{MSUBHUS @var{a},@var{b},@var{c}} 15994 @item @code{void __MTRAP (void)} 15995 @tab @code{__MTRAP ()} 15996 @tab @code{MTRAP} 15997 @item @code{uw2 __MUNPACKH (uw1)} 15998 @tab @code{@var{b} = __MUNPACKH (@var{a})} 15999 @tab @code{MUNPACKH @var{a},@var{b}} 16000 @item @code{uw1 __MWCUT (uw2, uw1)} 16001 @tab @code{@var{c} = __MWCUT (@var{a}, @var{b})} 16002 @tab @code{MWCUT @var{a},@var{b},@var{c}} 16003 @item @code{void __MWTACC (acc, uw1)} 16004 @tab @code{__MWTACC (@var{b}, @var{a})} 16005 @tab @code{MWTACC @var{a},@var{b}} 16006 @item @code{void __MWTACCG (acc, uw1)} 16007 @tab @code{__MWTACCG (@var{b}, @var{a})} 16008 @tab @code{MWTACCG @var{a},@var{b}} 16009 @item @code{uw1 __MXOR (uw1, uw1)} 16010 @tab @code{@var{c} = __MXOR (@var{a}, @var{b})} 16011 @tab @code{MXOR @var{a},@var{b},@var{c}} 16012 @end multitable 16013 16014 @node Raw read/write Functions 16015 @subsubsection Raw Read/Write Functions 16016 16017 This sections describes built-in functions related to read and write 16018 instructions to access memory. These functions generate 16019 @code{membar} instructions to flush the I/O load and stores where 16020 appropriate, as described in Fujitsu's manual described above. 16021 16022 @table @code 16023 16024 @item unsigned char __builtin_read8 (void *@var{data}) 16025 @item unsigned short __builtin_read16 (void *@var{data}) 16026 @item unsigned long __builtin_read32 (void *@var{data}) 16027 @item unsigned long long __builtin_read64 (void *@var{data}) 16028 16029 @item void __builtin_write8 (void *@var{data}, unsigned char @var{datum}) 16030 @item void __builtin_write16 (void *@var{data}, unsigned short @var{datum}) 16031 @item void __builtin_write32 (void *@var{data}, unsigned long @var{datum}) 16032 @item void __builtin_write64 (void *@var{data}, unsigned long long @var{datum}) 16033 @end table 16034 16035 @node Other Built-in Functions 16036 @subsubsection Other Built-in Functions 16037 16038 This section describes built-in functions that are not named after 16039 a specific FR-V instruction. 16040 16041 @table @code 16042 @item sw2 __IACCreadll (iacc @var{reg}) 16043 Return the full 64-bit value of IACC0@. The @var{reg} argument is reserved 16044 for future expansion and must be 0. 16045 16046 @item sw1 __IACCreadl (iacc @var{reg}) 16047 Return the value of IACC0H if @var{reg} is 0 and IACC0L if @var{reg} is 1. 16048 Other values of @var{reg} are rejected as invalid. 16049 16050 @item void __IACCsetll (iacc @var{reg}, sw2 @var{x}) 16051 Set the full 64-bit value of IACC0 to @var{x}. The @var{reg} argument 16052 is reserved for future expansion and must be 0. 16053 16054 @item void __IACCsetl (iacc @var{reg}, sw1 @var{x}) 16055 Set IACC0H to @var{x} if @var{reg} is 0 and IACC0L to @var{x} if @var{reg} 16056 is 1. Other values of @var{reg} are rejected as invalid. 16057 16058 @item void __data_prefetch0 (const void *@var{x}) 16059 Use the @code{dcpl} instruction to load the contents of address @var{x} 16060 into the data cache. 16061 16062 @item void __data_prefetch (const void *@var{x}) 16063 Use the @code{nldub} instruction to load the contents of address @var{x} 16064 into the data cache. The instruction is issued in slot I1@. 16065 @end table 16066 16067 @node LoongArch Base Built-in Functions 16068 @subsection LoongArch Base Built-in Functions 16069 16070 These built-in functions are available for LoongArch. 16071 16072 Data Type Description: 16073 @itemize 16074 @item @code{imm0_31}, a compile-time constant in range 0 to 31; 16075 @item @code{imm0_16383}, a compile-time constant in range 0 to 16383; 16076 @item @code{imm0_32767}, a compile-time constant in range 0 to 32767; 16077 @item @code{imm_n2048_2047}, a compile-time constant in range -2048 to 2047; 16078 @end itemize 16079 16080 The intrinsics provided are listed below: 16081 @smallexample 16082 unsigned int __builtin_loongarch_movfcsr2gr (imm0_31) 16083 void __builtin_loongarch_movgr2fcsr (imm0_31, unsigned int) 16084 void __builtin_loongarch_cacop_d (imm0_31, unsigned long int, imm_n2048_2047) 16085 unsigned int __builtin_loongarch_cpucfg (unsigned int) 16086 void __builtin_loongarch_asrtle_d (long int, long int) 16087 void __builtin_loongarch_asrtgt_d (long int, long int) 16088 long int __builtin_loongarch_lddir_d (long int, imm0_31) 16089 void __builtin_loongarch_ldpte_d (long int, imm0_31) 16090 16091 int __builtin_loongarch_crc_w_b_w (char, int) 16092 int __builtin_loongarch_crc_w_h_w (short, int) 16093 int __builtin_loongarch_crc_w_w_w (int, int) 16094 int __builtin_loongarch_crc_w_d_w (long int, int) 16095 int __builtin_loongarch_crcc_w_b_w (char, int) 16096 int __builtin_loongarch_crcc_w_h_w (short, int) 16097 int __builtin_loongarch_crcc_w_w_w (int, int) 16098 int __builtin_loongarch_crcc_w_d_w (long int, int) 16099 16100 unsigned int __builtin_loongarch_csrrd_w (imm0_16383) 16101 unsigned int __builtin_loongarch_csrwr_w (unsigned int, imm0_16383) 16102 unsigned int __builtin_loongarch_csrxchg_w (unsigned int, unsigned int, imm0_16383) 16103 unsigned long int __builtin_loongarch_csrrd_d (imm0_16383) 16104 unsigned long int __builtin_loongarch_csrwr_d (unsigned long int, imm0_16383) 16105 unsigned long int __builtin_loongarch_csrxchg_d (unsigned long int, unsigned long int, imm0_16383) 16106 16107 unsigned char __builtin_loongarch_iocsrrd_b (unsigned int) 16108 unsigned short __builtin_loongarch_iocsrrd_h (unsigned int) 16109 unsigned int __builtin_loongarch_iocsrrd_w (unsigned int) 16110 unsigned long int __builtin_loongarch_iocsrrd_d (unsigned int) 16111 void __builtin_loongarch_iocsrwr_b (unsigned char, unsigned int) 16112 void __builtin_loongarch_iocsrwr_h (unsigned short, unsigned int) 16113 void __builtin_loongarch_iocsrwr_w (unsigned int, unsigned int) 16114 void __builtin_loongarch_iocsrwr_d (unsigned long int, unsigned int) 16115 16116 void __builtin_loongarch_dbar (imm0_32767) 16117 void __builtin_loongarch_ibar (imm0_32767) 16118 16119 void __builtin_loongarch_syscall (imm0_32767) 16120 void __builtin_loongarch_break (imm0_32767) 16121 @end smallexample 16122 16123 @emph{Note:}Since the control register is divided into 32-bit and 64-bit, 16124 but the access instruction is not distinguished. So GCC renames the control 16125 instructions when implementing intrinsics. 16126 16127 Take the csrrd instruction as an example, built-in functions are implemented as follows: 16128 @smallexample 16129 __builtin_loongarch_csrrd_w // When reading the 32-bit control register use. 16130 __builtin_loongarch_csrrd_d // When reading the 64-bit control register use. 16131 @end smallexample 16132 16133 For the convenience of use, the built-in functions are encapsulated, 16134 the encapsulated functions and @code{__drdtime_t, __rdtime_t} are 16135 defined in the @code{larchintrin.h}. So if you call the following 16136 function you need to include @code{larchintrin.h}. 16137 16138 @smallexample 16139 typedef struct drdtime@{ 16140 unsigned long dvalue; 16141 unsigned long dtimeid; 16142 @} __drdtime_t; 16143 16144 typedef struct rdtime@{ 16145 unsigned int value; 16146 unsigned int timeid; 16147 @} __rdtime_t; 16148 @end smallexample 16149 16150 @smallexample 16151 __drdtime_t __rdtime_d (void) 16152 __rdtime_t __rdtimel_w (void) 16153 __rdtime_t __rdtimeh_w (void) 16154 unsigned int __movfcsr2gr (imm0_31) 16155 void __movgr2fcsr (imm0_31, unsigned int) 16156 void __cacop_d (imm0_31, unsigned long, imm_n2048_2047) 16157 unsigned int __cpucfg (unsigned int) 16158 void __asrtle_d (long int, long int) 16159 void __asrtgt_d (long int, long int) 16160 long int __lddir_d (long int, imm0_31) 16161 void __ldpte_d (long int, imm0_31) 16162 16163 int __crc_w_b_w (char, int) 16164 int __crc_w_h_w (short, int) 16165 int __crc_w_w_w (int, int) 16166 int __crc_w_d_w (long int, int) 16167 int __crcc_w_b_w (char, int) 16168 int __crcc_w_h_w (short, int) 16169 int __crcc_w_w_w (int, int) 16170 int __crcc_w_d_w (long int, int) 16171 16172 unsigned int __csrrd_w (imm0_16383) 16173 unsigned int __csrwr_w (unsigned int, imm0_16383) 16174 unsigned int __csrxchg_w (unsigned int, unsigned int, imm0_16383) 16175 unsigned long __csrrd_d (imm0_16383) 16176 unsigned long __csrwr_d (unsigned long, imm0_16383) 16177 unsigned long __csrxchg_d (unsigned long, unsigned long, imm0_16383) 16178 16179 unsigned char __iocsrrd_b (unsigned int) 16180 unsigned short __iocsrrd_h (unsigned int) 16181 unsigned int __iocsrrd_w (unsigned int) 16182 unsigned long __iocsrrd_d (unsigned int) 16183 void __iocsrwr_b (unsigned char, unsigned int) 16184 void __iocsrwr_h (unsigned short, unsigned int) 16185 void __iocsrwr_w (unsigned int, unsigned int) 16186 void __iocsrwr_d (unsigned long, unsigned int) 16187 16188 void __dbar (imm0_32767) 16189 void __ibar (imm0_32767) 16190 16191 void __syscall (imm0_32767) 16192 void __break (imm0_32767) 16193 @end smallexample 16194 16195 Returns the value that is currently set in the @samp{tp} register. 16196 @smallexample 16197 void * __builtin_thread_pointer (void) 16198 @end smallexample 16199 16200 @node MIPS DSP Built-in Functions 16201 @subsection MIPS DSP Built-in Functions 16202 16203 The MIPS DSP Application-Specific Extension (ASE) includes new 16204 instructions that are designed to improve the performance of DSP and 16205 media applications. It provides instructions that operate on packed 16206 8-bit/16-bit integer data, Q7, Q15 and Q31 fractional data. 16207 16208 GCC supports MIPS DSP operations using both the generic 16209 vector extensions (@pxref{Vector Extensions}) and a collection of 16210 MIPS-specific built-in functions. Both kinds of support are 16211 enabled by the @option{-mdsp} command-line option. 16212 16213 Revision 2 of the ASE was introduced in the second half of 2006. 16214 This revision adds extra instructions to the original ASE, but is 16215 otherwise backwards-compatible with it. You can select revision 2 16216 using the command-line option @option{-mdspr2}; this option implies 16217 @option{-mdsp}. 16218 16219 The SCOUNT and POS bits of the DSP control register are global. The 16220 WRDSP, EXTPDP, EXTPDPV and MTHLIP instructions modify the SCOUNT and 16221 POS bits. During optimization, the compiler does not delete these 16222 instructions and it does not delete calls to functions containing 16223 these instructions. 16224 16225 At present, GCC only provides support for operations on 32-bit 16226 vectors. The vector type associated with 8-bit integer data is 16227 usually called @code{v4i8}, the vector type associated with Q7 16228 is usually called @code{v4q7}, the vector type associated with 16-bit 16229 integer data is usually called @code{v2i16}, and the vector type 16230 associated with Q15 is usually called @code{v2q15}. They can be 16231 defined in C as follows: 16232 16233 @smallexample 16234 typedef signed char v4i8 __attribute__ ((vector_size(4))); 16235 typedef signed char v4q7 __attribute__ ((vector_size(4))); 16236 typedef short v2i16 __attribute__ ((vector_size(4))); 16237 typedef short v2q15 __attribute__ ((vector_size(4))); 16238 @end smallexample 16239 16240 @code{v4i8}, @code{v4q7}, @code{v2i16} and @code{v2q15} values are 16241 initialized in the same way as aggregates. For example: 16242 16243 @smallexample 16244 v4i8 a = @{1, 2, 3, 4@}; 16245 v4i8 b; 16246 b = (v4i8) @{5, 6, 7, 8@}; 16247 16248 v2q15 c = @{0x0fcb, 0x3a75@}; 16249 v2q15 d; 16250 d = (v2q15) @{0.1234 * 0x1.0p15, 0.4567 * 0x1.0p15@}; 16251 @end smallexample 16252 16253 @emph{Note:} The CPU's endianness determines the order in which values 16254 are packed. On little-endian targets, the first value is the least 16255 significant and the last value is the most significant. The opposite 16256 order applies to big-endian targets. For example, the code above 16257 sets the lowest byte of @code{a} to @code{1} on little-endian targets 16258 and @code{4} on big-endian targets. 16259 16260 @emph{Note:} Q7, Q15 and Q31 values must be initialized with their integer 16261 representation. As shown in this example, the integer representation 16262 of a Q7 value can be obtained by multiplying the fractional value by 16263 @code{0x1.0p7}. The equivalent for Q15 values is to multiply by 16264 @code{0x1.0p15}. The equivalent for Q31 values is to multiply by 16265 @code{0x1.0p31}. 16266 16267 The table below lists the @code{v4i8} and @code{v2q15} operations for which 16268 hardware support exists. @code{a} and @code{b} are @code{v4i8} values, 16269 and @code{c} and @code{d} are @code{v2q15} values. 16270 16271 @multitable @columnfractions .50 .50 16272 @headitem C code @tab MIPS instruction 16273 @item @code{a + b} @tab @code{addu.qb} 16274 @item @code{c + d} @tab @code{addq.ph} 16275 @item @code{a - b} @tab @code{subu.qb} 16276 @item @code{c - d} @tab @code{subq.ph} 16277 @end multitable 16278 16279 The table below lists the @code{v2i16} operation for which 16280 hardware support exists for the DSP ASE REV 2. @code{e} and @code{f} are 16281 @code{v2i16} values. 16282 16283 @multitable @columnfractions .50 .50 16284 @headitem C code @tab MIPS instruction 16285 @item @code{e * f} @tab @code{mul.ph} 16286 @end multitable 16287 16288 It is easier to describe the DSP built-in functions if we first define 16289 the following types: 16290 16291 @smallexample 16292 typedef int q31; 16293 typedef int i32; 16294 typedef unsigned int ui32; 16295 typedef long long a64; 16296 @end smallexample 16297 16298 @code{q31} and @code{i32} are actually the same as @code{int}, but we 16299 use @code{q31} to indicate a Q31 fractional value and @code{i32} to 16300 indicate a 32-bit integer value. Similarly, @code{a64} is the same as 16301 @code{long long}, but we use @code{a64} to indicate values that are 16302 placed in one of the four DSP accumulators (@code{$ac0}, 16303 @code{$ac1}, @code{$ac2} or @code{$ac3}). 16304 16305 Also, some built-in functions prefer or require immediate numbers as 16306 parameters, because the corresponding DSP instructions accept both immediate 16307 numbers and register operands, or accept immediate numbers only. The 16308 immediate parameters are listed as follows. 16309 16310 @smallexample 16311 imm0_3: 0 to 3. 16312 imm0_7: 0 to 7. 16313 imm0_15: 0 to 15. 16314 imm0_31: 0 to 31. 16315 imm0_63: 0 to 63. 16316 imm0_255: 0 to 255. 16317 imm_n32_31: -32 to 31. 16318 imm_n512_511: -512 to 511. 16319 @end smallexample 16320 16321 The following built-in functions map directly to a particular MIPS DSP 16322 instruction. Please refer to the architecture specification 16323 for details on what each instruction does. 16324 16325 @smallexample 16326 v2q15 __builtin_mips_addq_ph (v2q15, v2q15); 16327 v2q15 __builtin_mips_addq_s_ph (v2q15, v2q15); 16328 q31 __builtin_mips_addq_s_w (q31, q31); 16329 v4i8 __builtin_mips_addu_qb (v4i8, v4i8); 16330 v4i8 __builtin_mips_addu_s_qb (v4i8, v4i8); 16331 v2q15 __builtin_mips_subq_ph (v2q15, v2q15); 16332 v2q15 __builtin_mips_subq_s_ph (v2q15, v2q15); 16333 q31 __builtin_mips_subq_s_w (q31, q31); 16334 v4i8 __builtin_mips_subu_qb (v4i8, v4i8); 16335 v4i8 __builtin_mips_subu_s_qb (v4i8, v4i8); 16336 i32 __builtin_mips_addsc (i32, i32); 16337 i32 __builtin_mips_addwc (i32, i32); 16338 i32 __builtin_mips_modsub (i32, i32); 16339 i32 __builtin_mips_raddu_w_qb (v4i8); 16340 v2q15 __builtin_mips_absq_s_ph (v2q15); 16341 q31 __builtin_mips_absq_s_w (q31); 16342 v4i8 __builtin_mips_precrq_qb_ph (v2q15, v2q15); 16343 v2q15 __builtin_mips_precrq_ph_w (q31, q31); 16344 v2q15 __builtin_mips_precrq_rs_ph_w (q31, q31); 16345 v4i8 __builtin_mips_precrqu_s_qb_ph (v2q15, v2q15); 16346 q31 __builtin_mips_preceq_w_phl (v2q15); 16347 q31 __builtin_mips_preceq_w_phr (v2q15); 16348 v2q15 __builtin_mips_precequ_ph_qbl (v4i8); 16349 v2q15 __builtin_mips_precequ_ph_qbr (v4i8); 16350 v2q15 __builtin_mips_precequ_ph_qbla (v4i8); 16351 v2q15 __builtin_mips_precequ_ph_qbra (v4i8); 16352 v2q15 __builtin_mips_preceu_ph_qbl (v4i8); 16353 v2q15 __builtin_mips_preceu_ph_qbr (v4i8); 16354 v2q15 __builtin_mips_preceu_ph_qbla (v4i8); 16355 v2q15 __builtin_mips_preceu_ph_qbra (v4i8); 16356 v4i8 __builtin_mips_shll_qb (v4i8, imm0_7); 16357 v4i8 __builtin_mips_shll_qb (v4i8, i32); 16358 v2q15 __builtin_mips_shll_ph (v2q15, imm0_15); 16359 v2q15 __builtin_mips_shll_ph (v2q15, i32); 16360 v2q15 __builtin_mips_shll_s_ph (v2q15, imm0_15); 16361 v2q15 __builtin_mips_shll_s_ph (v2q15, i32); 16362 q31 __builtin_mips_shll_s_w (q31, imm0_31); 16363 q31 __builtin_mips_shll_s_w (q31, i32); 16364 v4i8 __builtin_mips_shrl_qb (v4i8, imm0_7); 16365 v4i8 __builtin_mips_shrl_qb (v4i8, i32); 16366 v2q15 __builtin_mips_shra_ph (v2q15, imm0_15); 16367 v2q15 __builtin_mips_shra_ph (v2q15, i32); 16368 v2q15 __builtin_mips_shra_r_ph (v2q15, imm0_15); 16369 v2q15 __builtin_mips_shra_r_ph (v2q15, i32); 16370 q31 __builtin_mips_shra_r_w (q31, imm0_31); 16371 q31 __builtin_mips_shra_r_w (q31, i32); 16372 v2q15 __builtin_mips_muleu_s_ph_qbl (v4i8, v2q15); 16373 v2q15 __builtin_mips_muleu_s_ph_qbr (v4i8, v2q15); 16374 v2q15 __builtin_mips_mulq_rs_ph (v2q15, v2q15); 16375 q31 __builtin_mips_muleq_s_w_phl (v2q15, v2q15); 16376 q31 __builtin_mips_muleq_s_w_phr (v2q15, v2q15); 16377 a64 __builtin_mips_dpau_h_qbl (a64, v4i8, v4i8); 16378 a64 __builtin_mips_dpau_h_qbr (a64, v4i8, v4i8); 16379 a64 __builtin_mips_dpsu_h_qbl (a64, v4i8, v4i8); 16380 a64 __builtin_mips_dpsu_h_qbr (a64, v4i8, v4i8); 16381 a64 __builtin_mips_dpaq_s_w_ph (a64, v2q15, v2q15); 16382 a64 __builtin_mips_dpaq_sa_l_w (a64, q31, q31); 16383 a64 __builtin_mips_dpsq_s_w_ph (a64, v2q15, v2q15); 16384 a64 __builtin_mips_dpsq_sa_l_w (a64, q31, q31); 16385 a64 __builtin_mips_mulsaq_s_w_ph (a64, v2q15, v2q15); 16386 a64 __builtin_mips_maq_s_w_phl (a64, v2q15, v2q15); 16387 a64 __builtin_mips_maq_s_w_phr (a64, v2q15, v2q15); 16388 a64 __builtin_mips_maq_sa_w_phl (a64, v2q15, v2q15); 16389 a64 __builtin_mips_maq_sa_w_phr (a64, v2q15, v2q15); 16390 i32 __builtin_mips_bitrev (i32); 16391 i32 __builtin_mips_insv (i32, i32); 16392 v4i8 __builtin_mips_repl_qb (imm0_255); 16393 v4i8 __builtin_mips_repl_qb (i32); 16394 v2q15 __builtin_mips_repl_ph (imm_n512_511); 16395 v2q15 __builtin_mips_repl_ph (i32); 16396 void __builtin_mips_cmpu_eq_qb (v4i8, v4i8); 16397 void __builtin_mips_cmpu_lt_qb (v4i8, v4i8); 16398 void __builtin_mips_cmpu_le_qb (v4i8, v4i8); 16399 i32 __builtin_mips_cmpgu_eq_qb (v4i8, v4i8); 16400 i32 __builtin_mips_cmpgu_lt_qb (v4i8, v4i8); 16401 i32 __builtin_mips_cmpgu_le_qb (v4i8, v4i8); 16402 void __builtin_mips_cmp_eq_ph (v2q15, v2q15); 16403 void __builtin_mips_cmp_lt_ph (v2q15, v2q15); 16404 void __builtin_mips_cmp_le_ph (v2q15, v2q15); 16405 v4i8 __builtin_mips_pick_qb (v4i8, v4i8); 16406 v2q15 __builtin_mips_pick_ph (v2q15, v2q15); 16407 v2q15 __builtin_mips_packrl_ph (v2q15, v2q15); 16408 i32 __builtin_mips_extr_w (a64, imm0_31); 16409 i32 __builtin_mips_extr_w (a64, i32); 16410 i32 __builtin_mips_extr_r_w (a64, imm0_31); 16411 i32 __builtin_mips_extr_s_h (a64, i32); 16412 i32 __builtin_mips_extr_rs_w (a64, imm0_31); 16413 i32 __builtin_mips_extr_rs_w (a64, i32); 16414 i32 __builtin_mips_extr_s_h (a64, imm0_31); 16415 i32 __builtin_mips_extr_r_w (a64, i32); 16416 i32 __builtin_mips_extp (a64, imm0_31); 16417 i32 __builtin_mips_extp (a64, i32); 16418 i32 __builtin_mips_extpdp (a64, imm0_31); 16419 i32 __builtin_mips_extpdp (a64, i32); 16420 a64 __builtin_mips_shilo (a64, imm_n32_31); 16421 a64 __builtin_mips_shilo (a64, i32); 16422 a64 __builtin_mips_mthlip (a64, i32); 16423 void __builtin_mips_wrdsp (i32, imm0_63); 16424 i32 __builtin_mips_rddsp (imm0_63); 16425 i32 __builtin_mips_lbux (void *, i32); 16426 i32 __builtin_mips_lhx (void *, i32); 16427 i32 __builtin_mips_lwx (void *, i32); 16428 a64 __builtin_mips_ldx (void *, i32); /* MIPS64 only */ 16429 i32 __builtin_mips_bposge32 (void); 16430 a64 __builtin_mips_madd (a64, i32, i32); 16431 a64 __builtin_mips_maddu (a64, ui32, ui32); 16432 a64 __builtin_mips_msub (a64, i32, i32); 16433 a64 __builtin_mips_msubu (a64, ui32, ui32); 16434 a64 __builtin_mips_mult (i32, i32); 16435 a64 __builtin_mips_multu (ui32, ui32); 16436 @end smallexample 16437 16438 The following built-in functions map directly to a particular MIPS DSP REV 2 16439 instruction. Please refer to the architecture specification 16440 for details on what each instruction does. 16441 16442 @smallexample 16443 v4q7 __builtin_mips_absq_s_qb (v4q7); 16444 v2i16 __builtin_mips_addu_ph (v2i16, v2i16); 16445 v2i16 __builtin_mips_addu_s_ph (v2i16, v2i16); 16446 v4i8 __builtin_mips_adduh_qb (v4i8, v4i8); 16447 v4i8 __builtin_mips_adduh_r_qb (v4i8, v4i8); 16448 i32 __builtin_mips_append (i32, i32, imm0_31); 16449 i32 __builtin_mips_balign (i32, i32, imm0_3); 16450 i32 __builtin_mips_cmpgdu_eq_qb (v4i8, v4i8); 16451 i32 __builtin_mips_cmpgdu_lt_qb (v4i8, v4i8); 16452 i32 __builtin_mips_cmpgdu_le_qb (v4i8, v4i8); 16453 a64 __builtin_mips_dpa_w_ph (a64, v2i16, v2i16); 16454 a64 __builtin_mips_dps_w_ph (a64, v2i16, v2i16); 16455 v2i16 __builtin_mips_mul_ph (v2i16, v2i16); 16456 v2i16 __builtin_mips_mul_s_ph (v2i16, v2i16); 16457 q31 __builtin_mips_mulq_rs_w (q31, q31); 16458 v2q15 __builtin_mips_mulq_s_ph (v2q15, v2q15); 16459 q31 __builtin_mips_mulq_s_w (q31, q31); 16460 a64 __builtin_mips_mulsa_w_ph (a64, v2i16, v2i16); 16461 v4i8 __builtin_mips_precr_qb_ph (v2i16, v2i16); 16462 v2i16 __builtin_mips_precr_sra_ph_w (i32, i32, imm0_31); 16463 v2i16 __builtin_mips_precr_sra_r_ph_w (i32, i32, imm0_31); 16464 i32 __builtin_mips_prepend (i32, i32, imm0_31); 16465 v4i8 __builtin_mips_shra_qb (v4i8, imm0_7); 16466 v4i8 __builtin_mips_shra_r_qb (v4i8, imm0_7); 16467 v4i8 __builtin_mips_shra_qb (v4i8, i32); 16468 v4i8 __builtin_mips_shra_r_qb (v4i8, i32); 16469 v2i16 __builtin_mips_shrl_ph (v2i16, imm0_15); 16470 v2i16 __builtin_mips_shrl_ph (v2i16, i32); 16471 v2i16 __builtin_mips_subu_ph (v2i16, v2i16); 16472 v2i16 __builtin_mips_subu_s_ph (v2i16, v2i16); 16473 v4i8 __builtin_mips_subuh_qb (v4i8, v4i8); 16474 v4i8 __builtin_mips_subuh_r_qb (v4i8, v4i8); 16475 v2q15 __builtin_mips_addqh_ph (v2q15, v2q15); 16476 v2q15 __builtin_mips_addqh_r_ph (v2q15, v2q15); 16477 q31 __builtin_mips_addqh_w (q31, q31); 16478 q31 __builtin_mips_addqh_r_w (q31, q31); 16479 v2q15 __builtin_mips_subqh_ph (v2q15, v2q15); 16480 v2q15 __builtin_mips_subqh_r_ph (v2q15, v2q15); 16481 q31 __builtin_mips_subqh_w (q31, q31); 16482 q31 __builtin_mips_subqh_r_w (q31, q31); 16483 a64 __builtin_mips_dpax_w_ph (a64, v2i16, v2i16); 16484 a64 __builtin_mips_dpsx_w_ph (a64, v2i16, v2i16); 16485 a64 __builtin_mips_dpaqx_s_w_ph (a64, v2q15, v2q15); 16486 a64 __builtin_mips_dpaqx_sa_w_ph (a64, v2q15, v2q15); 16487 a64 __builtin_mips_dpsqx_s_w_ph (a64, v2q15, v2q15); 16488 a64 __builtin_mips_dpsqx_sa_w_ph (a64, v2q15, v2q15); 16489 @end smallexample 16490 16491 16492 @node MIPS Paired-Single Support 16493 @subsection MIPS Paired-Single Support 16494 16495 The MIPS64 architecture includes a number of instructions that 16496 operate on pairs of single-precision floating-point values. 16497 Each pair is packed into a 64-bit floating-point register, 16498 with one element being designated the ``upper half'' and 16499 the other being designated the ``lower half''. 16500 16501 GCC supports paired-single operations using both the generic 16502 vector extensions (@pxref{Vector Extensions}) and a collection of 16503 MIPS-specific built-in functions. Both kinds of support are 16504 enabled by the @option{-mpaired-single} command-line option. 16505 16506 The vector type associated with paired-single values is usually 16507 called @code{v2sf}. It can be defined in C as follows: 16508 16509 @smallexample 16510 typedef float v2sf __attribute__ ((vector_size (8))); 16511 @end smallexample 16512 16513 @code{v2sf} values are initialized in the same way as aggregates. 16514 For example: 16515 16516 @smallexample 16517 v2sf a = @{1.5, 9.1@}; 16518 v2sf b; 16519 float e, f; 16520 b = (v2sf) @{e, f@}; 16521 @end smallexample 16522 16523 @emph{Note:} The CPU's endianness determines which value is stored in 16524 the upper half of a register and which value is stored in the lower half. 16525 On little-endian targets, the first value is the lower one and the second 16526 value is the upper one. The opposite order applies to big-endian targets. 16527 For example, the code above sets the lower half of @code{a} to 16528 @code{1.5} on little-endian targets and @code{9.1} on big-endian targets. 16529 16530 @node MIPS Loongson Built-in Functions 16531 @subsection MIPS Loongson Built-in Functions 16532 16533 GCC provides intrinsics to access the SIMD instructions provided by the 16534 ST Microelectronics Loongson-2E and -2F processors. These intrinsics, 16535 available after inclusion of the @code{loongson.h} header file, 16536 operate on the following 64-bit vector types: 16537 16538 @itemize 16539 @item @code{uint8x8_t}, a vector of eight unsigned 8-bit integers; 16540 @item @code{uint16x4_t}, a vector of four unsigned 16-bit integers; 16541 @item @code{uint32x2_t}, a vector of two unsigned 32-bit integers; 16542 @item @code{int8x8_t}, a vector of eight signed 8-bit integers; 16543 @item @code{int16x4_t}, a vector of four signed 16-bit integers; 16544 @item @code{int32x2_t}, a vector of two signed 32-bit integers. 16545 @end itemize 16546 16547 The intrinsics provided are listed below; each is named after the 16548 machine instruction to which it corresponds, with suffixes added as 16549 appropriate to distinguish intrinsics that expand to the same machine 16550 instruction yet have different argument types. Refer to the architecture 16551 documentation for a description of the functionality of each 16552 instruction. 16553 16554 @smallexample 16555 int16x4_t packsswh (int32x2_t s, int32x2_t t); 16556 int8x8_t packsshb (int16x4_t s, int16x4_t t); 16557 uint8x8_t packushb (uint16x4_t s, uint16x4_t t); 16558 uint32x2_t paddw_u (uint32x2_t s, uint32x2_t t); 16559 uint16x4_t paddh_u (uint16x4_t s, uint16x4_t t); 16560 uint8x8_t paddb_u (uint8x8_t s, uint8x8_t t); 16561 int32x2_t paddw_s (int32x2_t s, int32x2_t t); 16562 int16x4_t paddh_s (int16x4_t s, int16x4_t t); 16563 int8x8_t paddb_s (int8x8_t s, int8x8_t t); 16564 uint64_t paddd_u (uint64_t s, uint64_t t); 16565 int64_t paddd_s (int64_t s, int64_t t); 16566 int16x4_t paddsh (int16x4_t s, int16x4_t t); 16567 int8x8_t paddsb (int8x8_t s, int8x8_t t); 16568 uint16x4_t paddush (uint16x4_t s, uint16x4_t t); 16569 uint8x8_t paddusb (uint8x8_t s, uint8x8_t t); 16570 uint64_t pandn_ud (uint64_t s, uint64_t t); 16571 uint32x2_t pandn_uw (uint32x2_t s, uint32x2_t t); 16572 uint16x4_t pandn_uh (uint16x4_t s, uint16x4_t t); 16573 uint8x8_t pandn_ub (uint8x8_t s, uint8x8_t t); 16574 int64_t pandn_sd (int64_t s, int64_t t); 16575 int32x2_t pandn_sw (int32x2_t s, int32x2_t t); 16576 int16x4_t pandn_sh (int16x4_t s, int16x4_t t); 16577 int8x8_t pandn_sb (int8x8_t s, int8x8_t t); 16578 uint16x4_t pavgh (uint16x4_t s, uint16x4_t t); 16579 uint8x8_t pavgb (uint8x8_t s, uint8x8_t t); 16580 uint32x2_t pcmpeqw_u (uint32x2_t s, uint32x2_t t); 16581 uint16x4_t pcmpeqh_u (uint16x4_t s, uint16x4_t t); 16582 uint8x8_t pcmpeqb_u (uint8x8_t s, uint8x8_t t); 16583 int32x2_t pcmpeqw_s (int32x2_t s, int32x2_t t); 16584 int16x4_t pcmpeqh_s (int16x4_t s, int16x4_t t); 16585 int8x8_t pcmpeqb_s (int8x8_t s, int8x8_t t); 16586 uint32x2_t pcmpgtw_u (uint32x2_t s, uint32x2_t t); 16587 uint16x4_t pcmpgth_u (uint16x4_t s, uint16x4_t t); 16588 uint8x8_t pcmpgtb_u (uint8x8_t s, uint8x8_t t); 16589 int32x2_t pcmpgtw_s (int32x2_t s, int32x2_t t); 16590 int16x4_t pcmpgth_s (int16x4_t s, int16x4_t t); 16591 int8x8_t pcmpgtb_s (int8x8_t s, int8x8_t t); 16592 uint16x4_t pextrh_u (uint16x4_t s, int field); 16593 int16x4_t pextrh_s (int16x4_t s, int field); 16594 uint16x4_t pinsrh_0_u (uint16x4_t s, uint16x4_t t); 16595 uint16x4_t pinsrh_1_u (uint16x4_t s, uint16x4_t t); 16596 uint16x4_t pinsrh_2_u (uint16x4_t s, uint16x4_t t); 16597 uint16x4_t pinsrh_3_u (uint16x4_t s, uint16x4_t t); 16598 int16x4_t pinsrh_0_s (int16x4_t s, int16x4_t t); 16599 int16x4_t pinsrh_1_s (int16x4_t s, int16x4_t t); 16600 int16x4_t pinsrh_2_s (int16x4_t s, int16x4_t t); 16601 int16x4_t pinsrh_3_s (int16x4_t s, int16x4_t t); 16602 int32x2_t pmaddhw (int16x4_t s, int16x4_t t); 16603 int16x4_t pmaxsh (int16x4_t s, int16x4_t t); 16604 uint8x8_t pmaxub (uint8x8_t s, uint8x8_t t); 16605 int16x4_t pminsh (int16x4_t s, int16x4_t t); 16606 uint8x8_t pminub (uint8x8_t s, uint8x8_t t); 16607 uint8x8_t pmovmskb_u (uint8x8_t s); 16608 int8x8_t pmovmskb_s (int8x8_t s); 16609 uint16x4_t pmulhuh (uint16x4_t s, uint16x4_t t); 16610 int16x4_t pmulhh (int16x4_t s, int16x4_t t); 16611 int16x4_t pmullh (int16x4_t s, int16x4_t t); 16612 int64_t pmuluw (uint32x2_t s, uint32x2_t t); 16613 uint8x8_t pasubub (uint8x8_t s, uint8x8_t t); 16614 uint16x4_t biadd (uint8x8_t s); 16615 uint16x4_t psadbh (uint8x8_t s, uint8x8_t t); 16616 uint16x4_t pshufh_u (uint16x4_t dest, uint16x4_t s, uint8_t order); 16617 int16x4_t pshufh_s (int16x4_t dest, int16x4_t s, uint8_t order); 16618 uint16x4_t psllh_u (uint16x4_t s, uint8_t amount); 16619 int16x4_t psllh_s (int16x4_t s, uint8_t amount); 16620 uint32x2_t psllw_u (uint32x2_t s, uint8_t amount); 16621 int32x2_t psllw_s (int32x2_t s, uint8_t amount); 16622 uint16x4_t psrlh_u (uint16x4_t s, uint8_t amount); 16623 int16x4_t psrlh_s (int16x4_t s, uint8_t amount); 16624 uint32x2_t psrlw_u (uint32x2_t s, uint8_t amount); 16625 int32x2_t psrlw_s (int32x2_t s, uint8_t amount); 16626 uint16x4_t psrah_u (uint16x4_t s, uint8_t amount); 16627 int16x4_t psrah_s (int16x4_t s, uint8_t amount); 16628 uint32x2_t psraw_u (uint32x2_t s, uint8_t amount); 16629 int32x2_t psraw_s (int32x2_t s, uint8_t amount); 16630 uint32x2_t psubw_u (uint32x2_t s, uint32x2_t t); 16631 uint16x4_t psubh_u (uint16x4_t s, uint16x4_t t); 16632 uint8x8_t psubb_u (uint8x8_t s, uint8x8_t t); 16633 int32x2_t psubw_s (int32x2_t s, int32x2_t t); 16634 int16x4_t psubh_s (int16x4_t s, int16x4_t t); 16635 int8x8_t psubb_s (int8x8_t s, int8x8_t t); 16636 uint64_t psubd_u (uint64_t s, uint64_t t); 16637 int64_t psubd_s (int64_t s, int64_t t); 16638 int16x4_t psubsh (int16x4_t s, int16x4_t t); 16639 int8x8_t psubsb (int8x8_t s, int8x8_t t); 16640 uint16x4_t psubush (uint16x4_t s, uint16x4_t t); 16641 uint8x8_t psubusb (uint8x8_t s, uint8x8_t t); 16642 uint32x2_t punpckhwd_u (uint32x2_t s, uint32x2_t t); 16643 uint16x4_t punpckhhw_u (uint16x4_t s, uint16x4_t t); 16644 uint8x8_t punpckhbh_u (uint8x8_t s, uint8x8_t t); 16645 int32x2_t punpckhwd_s (int32x2_t s, int32x2_t t); 16646 int16x4_t punpckhhw_s (int16x4_t s, int16x4_t t); 16647 int8x8_t punpckhbh_s (int8x8_t s, int8x8_t t); 16648 uint32x2_t punpcklwd_u (uint32x2_t s, uint32x2_t t); 16649 uint16x4_t punpcklhw_u (uint16x4_t s, uint16x4_t t); 16650 uint8x8_t punpcklbh_u (uint8x8_t s, uint8x8_t t); 16651 int32x2_t punpcklwd_s (int32x2_t s, int32x2_t t); 16652 int16x4_t punpcklhw_s (int16x4_t s, int16x4_t t); 16653 int8x8_t punpcklbh_s (int8x8_t s, int8x8_t t); 16654 @end smallexample 16655 16656 @menu 16657 * Paired-Single Arithmetic:: 16658 * Paired-Single Built-in Functions:: 16659 * MIPS-3D Built-in Functions:: 16660 @end menu 16661 16662 @node Paired-Single Arithmetic 16663 @subsubsection Paired-Single Arithmetic 16664 16665 The table below lists the @code{v2sf} operations for which hardware 16666 support exists. @code{a}, @code{b} and @code{c} are @code{v2sf} 16667 values and @code{x} is an integral value. 16668 16669 @multitable @columnfractions .50 .50 16670 @headitem C code @tab MIPS instruction 16671 @item @code{a + b} @tab @code{add.ps} 16672 @item @code{a - b} @tab @code{sub.ps} 16673 @item @code{-a} @tab @code{neg.ps} 16674 @item @code{a * b} @tab @code{mul.ps} 16675 @item @code{a * b + c} @tab @code{madd.ps} 16676 @item @code{a * b - c} @tab @code{msub.ps} 16677 @item @code{-(a * b + c)} @tab @code{nmadd.ps} 16678 @item @code{-(a * b - c)} @tab @code{nmsub.ps} 16679 @item @code{x ? a : b} @tab @code{movn.ps}/@code{movz.ps} 16680 @end multitable 16681 16682 Note that the multiply-accumulate instructions can be disabled 16683 using the command-line option @code{-mno-fused-madd}. 16684 16685 @node Paired-Single Built-in Functions 16686 @subsubsection Paired-Single Built-in Functions 16687 16688 The following paired-single functions map directly to a particular 16689 MIPS instruction. Please refer to the architecture specification 16690 for details on what each instruction does. 16691 16692 @table @code 16693 @item v2sf __builtin_mips_pll_ps (v2sf, v2sf) 16694 Pair lower lower (@code{pll.ps}). 16695 16696 @item v2sf __builtin_mips_pul_ps (v2sf, v2sf) 16697 Pair upper lower (@code{pul.ps}). 16698 16699 @item v2sf __builtin_mips_plu_ps (v2sf, v2sf) 16700 Pair lower upper (@code{plu.ps}). 16701 16702 @item v2sf __builtin_mips_puu_ps (v2sf, v2sf) 16703 Pair upper upper (@code{puu.ps}). 16704 16705 @item v2sf __builtin_mips_cvt_ps_s (float, float) 16706 Convert pair to paired single (@code{cvt.ps.s}). 16707 16708 @item float __builtin_mips_cvt_s_pl (v2sf) 16709 Convert pair lower to single (@code{cvt.s.pl}). 16710 16711 @item float __builtin_mips_cvt_s_pu (v2sf) 16712 Convert pair upper to single (@code{cvt.s.pu}). 16713 16714 @item v2sf __builtin_mips_abs_ps (v2sf) 16715 Absolute value (@code{abs.ps}). 16716 16717 @item v2sf __builtin_mips_alnv_ps (v2sf, v2sf, int) 16718 Align variable (@code{alnv.ps}). 16719 16720 @emph{Note:} The value of the third parameter must be 0 or 4 16721 modulo 8, otherwise the result is unpredictable. Please read the 16722 instruction description for details. 16723 @end table 16724 16725 The following multi-instruction functions are also available. 16726 In each case, @var{cond} can be any of the 16 floating-point conditions: 16727 @code{f}, @code{un}, @code{eq}, @code{ueq}, @code{olt}, @code{ult}, 16728 @code{ole}, @code{ule}, @code{sf}, @code{ngle}, @code{seq}, @code{ngl}, 16729 @code{lt}, @code{nge}, @code{le} or @code{ngt}. 16730 16731 @table @code 16732 @item v2sf __builtin_mips_movt_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d}) 16733 @itemx v2sf __builtin_mips_movf_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d}) 16734 Conditional move based on floating-point comparison (@code{c.@var{cond}.ps}, 16735 @code{movt.ps}/@code{movf.ps}). 16736 16737 The @code{movt} functions return the value @var{x} computed by: 16738 16739 @smallexample 16740 c.@var{cond}.ps @var{cc},@var{a},@var{b} 16741 mov.ps @var{x},@var{c} 16742 movt.ps @var{x},@var{d},@var{cc} 16743 @end smallexample 16744 16745 The @code{movf} functions are similar but use @code{movf.ps} instead 16746 of @code{movt.ps}. 16747 16748 @item int __builtin_mips_upper_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}) 16749 @itemx int __builtin_mips_lower_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}) 16750 Comparison of two paired-single values (@code{c.@var{cond}.ps}, 16751 @code{bc1t}/@code{bc1f}). 16752 16753 These functions compare @var{a} and @var{b} using @code{c.@var{cond}.ps} 16754 and return either the upper or lower half of the result. For example: 16755 16756 @smallexample 16757 v2sf a, b; 16758 if (__builtin_mips_upper_c_eq_ps (a, b)) 16759 upper_halves_are_equal (); 16760 else 16761 upper_halves_are_unequal (); 16762 16763 if (__builtin_mips_lower_c_eq_ps (a, b)) 16764 lower_halves_are_equal (); 16765 else 16766 lower_halves_are_unequal (); 16767 @end smallexample 16768 @end table 16769 16770 @node MIPS-3D Built-in Functions 16771 @subsubsection MIPS-3D Built-in Functions 16772 16773 The MIPS-3D Application-Specific Extension (ASE) includes additional 16774 paired-single instructions that are designed to improve the performance 16775 of 3D graphics operations. Support for these instructions is controlled 16776 by the @option{-mips3d} command-line option. 16777 16778 The functions listed below map directly to a particular MIPS-3D 16779 instruction. Please refer to the architecture specification for 16780 more details on what each instruction does. 16781 16782 @table @code 16783 @item v2sf __builtin_mips_addr_ps (v2sf, v2sf) 16784 Reduction add (@code{addr.ps}). 16785 16786 @item v2sf __builtin_mips_mulr_ps (v2sf, v2sf) 16787 Reduction multiply (@code{mulr.ps}). 16788 16789 @item v2sf __builtin_mips_cvt_pw_ps (v2sf) 16790 Convert paired single to paired word (@code{cvt.pw.ps}). 16791 16792 @item v2sf __builtin_mips_cvt_ps_pw (v2sf) 16793 Convert paired word to paired single (@code{cvt.ps.pw}). 16794 16795 @item float __builtin_mips_recip1_s (float) 16796 @itemx double __builtin_mips_recip1_d (double) 16797 @itemx v2sf __builtin_mips_recip1_ps (v2sf) 16798 Reduced-precision reciprocal (sequence step 1) (@code{recip1.@var{fmt}}). 16799 16800 @item float __builtin_mips_recip2_s (float, float) 16801 @itemx double __builtin_mips_recip2_d (double, double) 16802 @itemx v2sf __builtin_mips_recip2_ps (v2sf, v2sf) 16803 Reduced-precision reciprocal (sequence step 2) (@code{recip2.@var{fmt}}). 16804 16805 @item float __builtin_mips_rsqrt1_s (float) 16806 @itemx double __builtin_mips_rsqrt1_d (double) 16807 @itemx v2sf __builtin_mips_rsqrt1_ps (v2sf) 16808 Reduced-precision reciprocal square root (sequence step 1) 16809 (@code{rsqrt1.@var{fmt}}). 16810 16811 @item float __builtin_mips_rsqrt2_s (float, float) 16812 @itemx double __builtin_mips_rsqrt2_d (double, double) 16813 @itemx v2sf __builtin_mips_rsqrt2_ps (v2sf, v2sf) 16814 Reduced-precision reciprocal square root (sequence step 2) 16815 (@code{rsqrt2.@var{fmt}}). 16816 @end table 16817 16818 The following multi-instruction functions are also available. 16819 In each case, @var{cond} can be any of the 16 floating-point conditions: 16820 @code{f}, @code{un}, @code{eq}, @code{ueq}, @code{olt}, @code{ult}, 16821 @code{ole}, @code{ule}, @code{sf}, @code{ngle}, @code{seq}, 16822 @code{ngl}, @code{lt}, @code{nge}, @code{le} or @code{ngt}. 16823 16824 @table @code 16825 @item int __builtin_mips_cabs_@var{cond}_s (float @var{a}, float @var{b}) 16826 @itemx int __builtin_mips_cabs_@var{cond}_d (double @var{a}, double @var{b}) 16827 Absolute comparison of two scalar values (@code{cabs.@var{cond}.@var{fmt}}, 16828 @code{bc1t}/@code{bc1f}). 16829 16830 These functions compare @var{a} and @var{b} using @code{cabs.@var{cond}.s} 16831 or @code{cabs.@var{cond}.d} and return the result as a boolean value. 16832 For example: 16833 16834 @smallexample 16835 float a, b; 16836 if (__builtin_mips_cabs_eq_s (a, b)) 16837 true (); 16838 else 16839 false (); 16840 @end smallexample 16841 16842 @item int __builtin_mips_upper_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}) 16843 @itemx int __builtin_mips_lower_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}) 16844 Absolute comparison of two paired-single values (@code{cabs.@var{cond}.ps}, 16845 @code{bc1t}/@code{bc1f}). 16846 16847 These functions compare @var{a} and @var{b} using @code{cabs.@var{cond}.ps} 16848 and return either the upper or lower half of the result. For example: 16849 16850 @smallexample 16851 v2sf a, b; 16852 if (__builtin_mips_upper_cabs_eq_ps (a, b)) 16853 upper_halves_are_equal (); 16854 else 16855 upper_halves_are_unequal (); 16856 16857 if (__builtin_mips_lower_cabs_eq_ps (a, b)) 16858 lower_halves_are_equal (); 16859 else 16860 lower_halves_are_unequal (); 16861 @end smallexample 16862 16863 @item v2sf __builtin_mips_movt_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d}) 16864 @itemx v2sf __builtin_mips_movf_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d}) 16865 Conditional move based on absolute comparison (@code{cabs.@var{cond}.ps}, 16866 @code{movt.ps}/@code{movf.ps}). 16867 16868 The @code{movt} functions return the value @var{x} computed by: 16869 16870 @smallexample 16871 cabs.@var{cond}.ps @var{cc},@var{a},@var{b} 16872 mov.ps @var{x},@var{c} 16873 movt.ps @var{x},@var{d},@var{cc} 16874 @end smallexample 16875 16876 The @code{movf} functions are similar but use @code{movf.ps} instead 16877 of @code{movt.ps}. 16878 16879 @item int __builtin_mips_any_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}) 16880 @itemx int __builtin_mips_all_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}) 16881 @itemx int __builtin_mips_any_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}) 16882 @itemx int __builtin_mips_all_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}) 16883 Comparison of two paired-single values 16884 (@code{c.@var{cond}.ps}/@code{cabs.@var{cond}.ps}, 16885 @code{bc1any2t}/@code{bc1any2f}). 16886 16887 These functions compare @var{a} and @var{b} using @code{c.@var{cond}.ps} 16888 or @code{cabs.@var{cond}.ps}. The @code{any} forms return @code{true} if either 16889 result is @code{true} and the @code{all} forms return @code{true} if both results are @code{true}. 16890 For example: 16891 16892 @smallexample 16893 v2sf a, b; 16894 if (__builtin_mips_any_c_eq_ps (a, b)) 16895 one_is_true (); 16896 else 16897 both_are_false (); 16898 16899 if (__builtin_mips_all_c_eq_ps (a, b)) 16900 both_are_true (); 16901 else 16902 one_is_false (); 16903 @end smallexample 16904 16905 @item int __builtin_mips_any_c_@var{cond}_4s (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d}) 16906 @itemx int __builtin_mips_all_c_@var{cond}_4s (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d}) 16907 @itemx int __builtin_mips_any_cabs_@var{cond}_4s (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d}) 16908 @itemx int __builtin_mips_all_cabs_@var{cond}_4s (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d}) 16909 Comparison of four paired-single values 16910 (@code{c.@var{cond}.ps}/@code{cabs.@var{cond}.ps}, 16911 @code{bc1any4t}/@code{bc1any4f}). 16912 16913 These functions use @code{c.@var{cond}.ps} or @code{cabs.@var{cond}.ps} 16914 to compare @var{a} with @var{b} and to compare @var{c} with @var{d}. 16915 The @code{any} forms return @code{true} if any of the four results are @code{true} 16916 and the @code{all} forms return @code{true} if all four results are @code{true}. 16917 For example: 16918 16919 @smallexample 16920 v2sf a, b, c, d; 16921 if (__builtin_mips_any_c_eq_4s (a, b, c, d)) 16922 some_are_true (); 16923 else 16924 all_are_false (); 16925 16926 if (__builtin_mips_all_c_eq_4s (a, b, c, d)) 16927 all_are_true (); 16928 else 16929 some_are_false (); 16930 @end smallexample 16931 @end table 16932 16933 @node MIPS SIMD Architecture (MSA) Support 16934 @subsection MIPS SIMD Architecture (MSA) Support 16935 16936 @menu 16937 * MIPS SIMD Architecture Built-in Functions:: 16938 @end menu 16939 16940 GCC provides intrinsics to access the SIMD instructions provided by the 16941 MSA MIPS SIMD Architecture. The interface is made available by including 16942 @code{<msa.h>} and using @option{-mmsa -mhard-float -mfp64 -mnan=2008}. 16943 For each @code{__builtin_msa_*}, there is a shortened name of the intrinsic, 16944 @code{__msa_*}. 16945 16946 MSA implements 128-bit wide vector registers, operating on 8-, 16-, 32- and 16947 64-bit integer, 16- and 32-bit fixed-point, or 32- and 64-bit floating point 16948 data elements. The following vectors typedefs are included in @code{msa.h}: 16949 @itemize 16950 @item @code{v16i8}, a vector of sixteen signed 8-bit integers; 16951 @item @code{v16u8}, a vector of sixteen unsigned 8-bit integers; 16952 @item @code{v8i16}, a vector of eight signed 16-bit integers; 16953 @item @code{v8u16}, a vector of eight unsigned 16-bit integers; 16954 @item @code{v4i32}, a vector of four signed 32-bit integers; 16955 @item @code{v4u32}, a vector of four unsigned 32-bit integers; 16956 @item @code{v2i64}, a vector of two signed 64-bit integers; 16957 @item @code{v2u64}, a vector of two unsigned 64-bit integers; 16958 @item @code{v4f32}, a vector of four 32-bit floats; 16959 @item @code{v2f64}, a vector of two 64-bit doubles. 16960 @end itemize 16961 16962 Instructions and corresponding built-ins may have additional restrictions and/or 16963 input/output values manipulated: 16964 @itemize 16965 @item @code{imm0_1}, an integer literal in range 0 to 1; 16966 @item @code{imm0_3}, an integer literal in range 0 to 3; 16967 @item @code{imm0_7}, an integer literal in range 0 to 7; 16968 @item @code{imm0_15}, an integer literal in range 0 to 15; 16969 @item @code{imm0_31}, an integer literal in range 0 to 31; 16970 @item @code{imm0_63}, an integer literal in range 0 to 63; 16971 @item @code{imm0_255}, an integer literal in range 0 to 255; 16972 @item @code{imm_n16_15}, an integer literal in range -16 to 15; 16973 @item @code{imm_n512_511}, an integer literal in range -512 to 511; 16974 @item @code{imm_n1024_1022}, an integer literal in range -512 to 511 left 16975 shifted by 1 bit, i.e., -1024, -1022, @dots{}, 1020, 1022; 16976 @item @code{imm_n2048_2044}, an integer literal in range -512 to 511 left 16977 shifted by 2 bits, i.e., -2048, -2044, @dots{}, 2040, 2044; 16978 @item @code{imm_n4096_4088}, an integer literal in range -512 to 511 left 16979 shifted by 3 bits, i.e., -4096, -4088, @dots{}, 4080, 4088; 16980 @item @code{imm1_4}, an integer literal in range 1 to 4; 16981 @item @code{i32, i64, u32, u64, f32, f64}, defined as follows: 16982 @end itemize 16983 16984 @smallexample 16985 @{ 16986 typedef int i32; 16987 #if __LONG_MAX__ == __LONG_LONG_MAX__ 16988 typedef long i64; 16989 #else 16990 typedef long long i64; 16991 #endif 16992 16993 typedef unsigned int u32; 16994 #if __LONG_MAX__ == __LONG_LONG_MAX__ 16995 typedef unsigned long u64; 16996 #else 16997 typedef unsigned long long u64; 16998 #endif 16999 17000 typedef double f64; 17001 typedef float f32; 17002 @} 17003 @end smallexample 17004 17005 @node MIPS SIMD Architecture Built-in Functions 17006 @subsubsection MIPS SIMD Architecture Built-in Functions 17007 17008 The intrinsics provided are listed below; each is named after the 17009 machine instruction. 17010 17011 @smallexample 17012 v16i8 __builtin_msa_add_a_b (v16i8, v16i8); 17013 v8i16 __builtin_msa_add_a_h (v8i16, v8i16); 17014 v4i32 __builtin_msa_add_a_w (v4i32, v4i32); 17015 v2i64 __builtin_msa_add_a_d (v2i64, v2i64); 17016 17017 v16i8 __builtin_msa_adds_a_b (v16i8, v16i8); 17018 v8i16 __builtin_msa_adds_a_h (v8i16, v8i16); 17019 v4i32 __builtin_msa_adds_a_w (v4i32, v4i32); 17020 v2i64 __builtin_msa_adds_a_d (v2i64, v2i64); 17021 17022 v16i8 __builtin_msa_adds_s_b (v16i8, v16i8); 17023 v8i16 __builtin_msa_adds_s_h (v8i16, v8i16); 17024 v4i32 __builtin_msa_adds_s_w (v4i32, v4i32); 17025 v2i64 __builtin_msa_adds_s_d (v2i64, v2i64); 17026 17027 v16u8 __builtin_msa_adds_u_b (v16u8, v16u8); 17028 v8u16 __builtin_msa_adds_u_h (v8u16, v8u16); 17029 v4u32 __builtin_msa_adds_u_w (v4u32, v4u32); 17030 v2u64 __builtin_msa_adds_u_d (v2u64, v2u64); 17031 17032 v16i8 __builtin_msa_addv_b (v16i8, v16i8); 17033 v8i16 __builtin_msa_addv_h (v8i16, v8i16); 17034 v4i32 __builtin_msa_addv_w (v4i32, v4i32); 17035 v2i64 __builtin_msa_addv_d (v2i64, v2i64); 17036 17037 v16i8 __builtin_msa_addvi_b (v16i8, imm0_31); 17038 v8i16 __builtin_msa_addvi_h (v8i16, imm0_31); 17039 v4i32 __builtin_msa_addvi_w (v4i32, imm0_31); 17040 v2i64 __builtin_msa_addvi_d (v2i64, imm0_31); 17041 17042 v16u8 __builtin_msa_and_v (v16u8, v16u8); 17043 17044 v16u8 __builtin_msa_andi_b (v16u8, imm0_255); 17045 17046 v16i8 __builtin_msa_asub_s_b (v16i8, v16i8); 17047 v8i16 __builtin_msa_asub_s_h (v8i16, v8i16); 17048 v4i32 __builtin_msa_asub_s_w (v4i32, v4i32); 17049 v2i64 __builtin_msa_asub_s_d (v2i64, v2i64); 17050 17051 v16u8 __builtin_msa_asub_u_b (v16u8, v16u8); 17052 v8u16 __builtin_msa_asub_u_h (v8u16, v8u16); 17053 v4u32 __builtin_msa_asub_u_w (v4u32, v4u32); 17054 v2u64 __builtin_msa_asub_u_d (v2u64, v2u64); 17055 17056 v16i8 __builtin_msa_ave_s_b (v16i8, v16i8); 17057 v8i16 __builtin_msa_ave_s_h (v8i16, v8i16); 17058 v4i32 __builtin_msa_ave_s_w (v4i32, v4i32); 17059 v2i64 __builtin_msa_ave_s_d (v2i64, v2i64); 17060 17061 v16u8 __builtin_msa_ave_u_b (v16u8, v16u8); 17062 v8u16 __builtin_msa_ave_u_h (v8u16, v8u16); 17063 v4u32 __builtin_msa_ave_u_w (v4u32, v4u32); 17064 v2u64 __builtin_msa_ave_u_d (v2u64, v2u64); 17065 17066 v16i8 __builtin_msa_aver_s_b (v16i8, v16i8); 17067 v8i16 __builtin_msa_aver_s_h (v8i16, v8i16); 17068 v4i32 __builtin_msa_aver_s_w (v4i32, v4i32); 17069 v2i64 __builtin_msa_aver_s_d (v2i64, v2i64); 17070 17071 v16u8 __builtin_msa_aver_u_b (v16u8, v16u8); 17072 v8u16 __builtin_msa_aver_u_h (v8u16, v8u16); 17073 v4u32 __builtin_msa_aver_u_w (v4u32, v4u32); 17074 v2u64 __builtin_msa_aver_u_d (v2u64, v2u64); 17075 17076 v16u8 __builtin_msa_bclr_b (v16u8, v16u8); 17077 v8u16 __builtin_msa_bclr_h (v8u16, v8u16); 17078 v4u32 __builtin_msa_bclr_w (v4u32, v4u32); 17079 v2u64 __builtin_msa_bclr_d (v2u64, v2u64); 17080 17081 v16u8 __builtin_msa_bclri_b (v16u8, imm0_7); 17082 v8u16 __builtin_msa_bclri_h (v8u16, imm0_15); 17083 v4u32 __builtin_msa_bclri_w (v4u32, imm0_31); 17084 v2u64 __builtin_msa_bclri_d (v2u64, imm0_63); 17085 17086 v16u8 __builtin_msa_binsl_b (v16u8, v16u8, v16u8); 17087 v8u16 __builtin_msa_binsl_h (v8u16, v8u16, v8u16); 17088 v4u32 __builtin_msa_binsl_w (v4u32, v4u32, v4u32); 17089 v2u64 __builtin_msa_binsl_d (v2u64, v2u64, v2u64); 17090 17091 v16u8 __builtin_msa_binsli_b (v16u8, v16u8, imm0_7); 17092 v8u16 __builtin_msa_binsli_h (v8u16, v8u16, imm0_15); 17093 v4u32 __builtin_msa_binsli_w (v4u32, v4u32, imm0_31); 17094 v2u64 __builtin_msa_binsli_d (v2u64, v2u64, imm0_63); 17095 17096 v16u8 __builtin_msa_binsr_b (v16u8, v16u8, v16u8); 17097 v8u16 __builtin_msa_binsr_h (v8u16, v8u16, v8u16); 17098 v4u32 __builtin_msa_binsr_w (v4u32, v4u32, v4u32); 17099 v2u64 __builtin_msa_binsr_d (v2u64, v2u64, v2u64); 17100 17101 v16u8 __builtin_msa_binsri_b (v16u8, v16u8, imm0_7); 17102 v8u16 __builtin_msa_binsri_h (v8u16, v8u16, imm0_15); 17103 v4u32 __builtin_msa_binsri_w (v4u32, v4u32, imm0_31); 17104 v2u64 __builtin_msa_binsri_d (v2u64, v2u64, imm0_63); 17105 17106 v16u8 __builtin_msa_bmnz_v (v16u8, v16u8, v16u8); 17107 17108 v16u8 __builtin_msa_bmnzi_b (v16u8, v16u8, imm0_255); 17109 17110 v16u8 __builtin_msa_bmz_v (v16u8, v16u8, v16u8); 17111 17112 v16u8 __builtin_msa_bmzi_b (v16u8, v16u8, imm0_255); 17113 17114 v16u8 __builtin_msa_bneg_b (v16u8, v16u8); 17115 v8u16 __builtin_msa_bneg_h (v8u16, v8u16); 17116 v4u32 __builtin_msa_bneg_w (v4u32, v4u32); 17117 v2u64 __builtin_msa_bneg_d (v2u64, v2u64); 17118 17119 v16u8 __builtin_msa_bnegi_b (v16u8, imm0_7); 17120 v8u16 __builtin_msa_bnegi_h (v8u16, imm0_15); 17121 v4u32 __builtin_msa_bnegi_w (v4u32, imm0_31); 17122 v2u64 __builtin_msa_bnegi_d (v2u64, imm0_63); 17123 17124 i32 __builtin_msa_bnz_b (v16u8); 17125 i32 __builtin_msa_bnz_h (v8u16); 17126 i32 __builtin_msa_bnz_w (v4u32); 17127 i32 __builtin_msa_bnz_d (v2u64); 17128 17129 i32 __builtin_msa_bnz_v (v16u8); 17130 17131 v16u8 __builtin_msa_bsel_v (v16u8, v16u8, v16u8); 17132 17133 v16u8 __builtin_msa_bseli_b (v16u8, v16u8, imm0_255); 17134 17135 v16u8 __builtin_msa_bset_b (v16u8, v16u8); 17136 v8u16 __builtin_msa_bset_h (v8u16, v8u16); 17137 v4u32 __builtin_msa_bset_w (v4u32, v4u32); 17138 v2u64 __builtin_msa_bset_d (v2u64, v2u64); 17139 17140 v16u8 __builtin_msa_bseti_b (v16u8, imm0_7); 17141 v8u16 __builtin_msa_bseti_h (v8u16, imm0_15); 17142 v4u32 __builtin_msa_bseti_w (v4u32, imm0_31); 17143 v2u64 __builtin_msa_bseti_d (v2u64, imm0_63); 17144 17145 i32 __builtin_msa_bz_b (v16u8); 17146 i32 __builtin_msa_bz_h (v8u16); 17147 i32 __builtin_msa_bz_w (v4u32); 17148 i32 __builtin_msa_bz_d (v2u64); 17149 17150 i32 __builtin_msa_bz_v (v16u8); 17151 17152 v16i8 __builtin_msa_ceq_b (v16i8, v16i8); 17153 v8i16 __builtin_msa_ceq_h (v8i16, v8i16); 17154 v4i32 __builtin_msa_ceq_w (v4i32, v4i32); 17155 v2i64 __builtin_msa_ceq_d (v2i64, v2i64); 17156 17157 v16i8 __builtin_msa_ceqi_b (v16i8, imm_n16_15); 17158 v8i16 __builtin_msa_ceqi_h (v8i16, imm_n16_15); 17159 v4i32 __builtin_msa_ceqi_w (v4i32, imm_n16_15); 17160 v2i64 __builtin_msa_ceqi_d (v2i64, imm_n16_15); 17161 17162 i32 __builtin_msa_cfcmsa (imm0_31); 17163 17164 v16i8 __builtin_msa_cle_s_b (v16i8, v16i8); 17165 v8i16 __builtin_msa_cle_s_h (v8i16, v8i16); 17166 v4i32 __builtin_msa_cle_s_w (v4i32, v4i32); 17167 v2i64 __builtin_msa_cle_s_d (v2i64, v2i64); 17168 17169 v16i8 __builtin_msa_cle_u_b (v16u8, v16u8); 17170 v8i16 __builtin_msa_cle_u_h (v8u16, v8u16); 17171 v4i32 __builtin_msa_cle_u_w (v4u32, v4u32); 17172 v2i64 __builtin_msa_cle_u_d (v2u64, v2u64); 17173 17174 v16i8 __builtin_msa_clei_s_b (v16i8, imm_n16_15); 17175 v8i16 __builtin_msa_clei_s_h (v8i16, imm_n16_15); 17176 v4i32 __builtin_msa_clei_s_w (v4i32, imm_n16_15); 17177 v2i64 __builtin_msa_clei_s_d (v2i64, imm_n16_15); 17178 17179 v16i8 __builtin_msa_clei_u_b (v16u8, imm0_31); 17180 v8i16 __builtin_msa_clei_u_h (v8u16, imm0_31); 17181 v4i32 __builtin_msa_clei_u_w (v4u32, imm0_31); 17182 v2i64 __builtin_msa_clei_u_d (v2u64, imm0_31); 17183 17184 v16i8 __builtin_msa_clt_s_b (v16i8, v16i8); 17185 v8i16 __builtin_msa_clt_s_h (v8i16, v8i16); 17186 v4i32 __builtin_msa_clt_s_w (v4i32, v4i32); 17187 v2i64 __builtin_msa_clt_s_d (v2i64, v2i64); 17188 17189 v16i8 __builtin_msa_clt_u_b (v16u8, v16u8); 17190 v8i16 __builtin_msa_clt_u_h (v8u16, v8u16); 17191 v4i32 __builtin_msa_clt_u_w (v4u32, v4u32); 17192 v2i64 __builtin_msa_clt_u_d (v2u64, v2u64); 17193 17194 v16i8 __builtin_msa_clti_s_b (v16i8, imm_n16_15); 17195 v8i16 __builtin_msa_clti_s_h (v8i16, imm_n16_15); 17196 v4i32 __builtin_msa_clti_s_w (v4i32, imm_n16_15); 17197 v2i64 __builtin_msa_clti_s_d (v2i64, imm_n16_15); 17198 17199 v16i8 __builtin_msa_clti_u_b (v16u8, imm0_31); 17200 v8i16 __builtin_msa_clti_u_h (v8u16, imm0_31); 17201 v4i32 __builtin_msa_clti_u_w (v4u32, imm0_31); 17202 v2i64 __builtin_msa_clti_u_d (v2u64, imm0_31); 17203 17204 i32 __builtin_msa_copy_s_b (v16i8, imm0_15); 17205 i32 __builtin_msa_copy_s_h (v8i16, imm0_7); 17206 i32 __builtin_msa_copy_s_w (v4i32, imm0_3); 17207 i64 __builtin_msa_copy_s_d (v2i64, imm0_1); 17208 17209 u32 __builtin_msa_copy_u_b (v16i8, imm0_15); 17210 u32 __builtin_msa_copy_u_h (v8i16, imm0_7); 17211 u32 __builtin_msa_copy_u_w (v4i32, imm0_3); 17212 u64 __builtin_msa_copy_u_d (v2i64, imm0_1); 17213 17214 void __builtin_msa_ctcmsa (imm0_31, i32); 17215 17216 v16i8 __builtin_msa_div_s_b (v16i8, v16i8); 17217 v8i16 __builtin_msa_div_s_h (v8i16, v8i16); 17218 v4i32 __builtin_msa_div_s_w (v4i32, v4i32); 17219 v2i64 __builtin_msa_div_s_d (v2i64, v2i64); 17220 17221 v16u8 __builtin_msa_div_u_b (v16u8, v16u8); 17222 v8u16 __builtin_msa_div_u_h (v8u16, v8u16); 17223 v4u32 __builtin_msa_div_u_w (v4u32, v4u32); 17224 v2u64 __builtin_msa_div_u_d (v2u64, v2u64); 17225 17226 v8i16 __builtin_msa_dotp_s_h (v16i8, v16i8); 17227 v4i32 __builtin_msa_dotp_s_w (v8i16, v8i16); 17228 v2i64 __builtin_msa_dotp_s_d (v4i32, v4i32); 17229 17230 v8u16 __builtin_msa_dotp_u_h (v16u8, v16u8); 17231 v4u32 __builtin_msa_dotp_u_w (v8u16, v8u16); 17232 v2u64 __builtin_msa_dotp_u_d (v4u32, v4u32); 17233 17234 v8i16 __builtin_msa_dpadd_s_h (v8i16, v16i8, v16i8); 17235 v4i32 __builtin_msa_dpadd_s_w (v4i32, v8i16, v8i16); 17236 v2i64 __builtin_msa_dpadd_s_d (v2i64, v4i32, v4i32); 17237 17238 v8u16 __builtin_msa_dpadd_u_h (v8u16, v16u8, v16u8); 17239 v4u32 __builtin_msa_dpadd_u_w (v4u32, v8u16, v8u16); 17240 v2u64 __builtin_msa_dpadd_u_d (v2u64, v4u32, v4u32); 17241 17242 v8i16 __builtin_msa_dpsub_s_h (v8i16, v16i8, v16i8); 17243 v4i32 __builtin_msa_dpsub_s_w (v4i32, v8i16, v8i16); 17244 v2i64 __builtin_msa_dpsub_s_d (v2i64, v4i32, v4i32); 17245 17246 v8i16 __builtin_msa_dpsub_u_h (v8i16, v16u8, v16u8); 17247 v4i32 __builtin_msa_dpsub_u_w (v4i32, v8u16, v8u16); 17248 v2i64 __builtin_msa_dpsub_u_d (v2i64, v4u32, v4u32); 17249 17250 v4f32 __builtin_msa_fadd_w (v4f32, v4f32); 17251 v2f64 __builtin_msa_fadd_d (v2f64, v2f64); 17252 17253 v4i32 __builtin_msa_fcaf_w (v4f32, v4f32); 17254 v2i64 __builtin_msa_fcaf_d (v2f64, v2f64); 17255 17256 v4i32 __builtin_msa_fceq_w (v4f32, v4f32); 17257 v2i64 __builtin_msa_fceq_d (v2f64, v2f64); 17258 17259 v4i32 __builtin_msa_fclass_w (v4f32); 17260 v2i64 __builtin_msa_fclass_d (v2f64); 17261 17262 v4i32 __builtin_msa_fcle_w (v4f32, v4f32); 17263 v2i64 __builtin_msa_fcle_d (v2f64, v2f64); 17264 17265 v4i32 __builtin_msa_fclt_w (v4f32, v4f32); 17266 v2i64 __builtin_msa_fclt_d (v2f64, v2f64); 17267 17268 v4i32 __builtin_msa_fcne_w (v4f32, v4f32); 17269 v2i64 __builtin_msa_fcne_d (v2f64, v2f64); 17270 17271 v4i32 __builtin_msa_fcor_w (v4f32, v4f32); 17272 v2i64 __builtin_msa_fcor_d (v2f64, v2f64); 17273 17274 v4i32 __builtin_msa_fcueq_w (v4f32, v4f32); 17275 v2i64 __builtin_msa_fcueq_d (v2f64, v2f64); 17276 17277 v4i32 __builtin_msa_fcule_w (v4f32, v4f32); 17278 v2i64 __builtin_msa_fcule_d (v2f64, v2f64); 17279 17280 v4i32 __builtin_msa_fcult_w (v4f32, v4f32); 17281 v2i64 __builtin_msa_fcult_d (v2f64, v2f64); 17282 17283 v4i32 __builtin_msa_fcun_w (v4f32, v4f32); 17284 v2i64 __builtin_msa_fcun_d (v2f64, v2f64); 17285 17286 v4i32 __builtin_msa_fcune_w (v4f32, v4f32); 17287 v2i64 __builtin_msa_fcune_d (v2f64, v2f64); 17288 17289 v4f32 __builtin_msa_fdiv_w (v4f32, v4f32); 17290 v2f64 __builtin_msa_fdiv_d (v2f64, v2f64); 17291 17292 v8i16 __builtin_msa_fexdo_h (v4f32, v4f32); 17293 v4f32 __builtin_msa_fexdo_w (v2f64, v2f64); 17294 17295 v4f32 __builtin_msa_fexp2_w (v4f32, v4i32); 17296 v2f64 __builtin_msa_fexp2_d (v2f64, v2i64); 17297 17298 v4f32 __builtin_msa_fexupl_w (v8i16); 17299 v2f64 __builtin_msa_fexupl_d (v4f32); 17300 17301 v4f32 __builtin_msa_fexupr_w (v8i16); 17302 v2f64 __builtin_msa_fexupr_d (v4f32); 17303 17304 v4f32 __builtin_msa_ffint_s_w (v4i32); 17305 v2f64 __builtin_msa_ffint_s_d (v2i64); 17306 17307 v4f32 __builtin_msa_ffint_u_w (v4u32); 17308 v2f64 __builtin_msa_ffint_u_d (v2u64); 17309 17310 v4f32 __builtin_msa_ffql_w (v8i16); 17311 v2f64 __builtin_msa_ffql_d (v4i32); 17312 17313 v4f32 __builtin_msa_ffqr_w (v8i16); 17314 v2f64 __builtin_msa_ffqr_d (v4i32); 17315 17316 v16i8 __builtin_msa_fill_b (i32); 17317 v8i16 __builtin_msa_fill_h (i32); 17318 v4i32 __builtin_msa_fill_w (i32); 17319 v2i64 __builtin_msa_fill_d (i64); 17320 17321 v4f32 __builtin_msa_flog2_w (v4f32); 17322 v2f64 __builtin_msa_flog2_d (v2f64); 17323 17324 v4f32 __builtin_msa_fmadd_w (v4f32, v4f32, v4f32); 17325 v2f64 __builtin_msa_fmadd_d (v2f64, v2f64, v2f64); 17326 17327 v4f32 __builtin_msa_fmax_w (v4f32, v4f32); 17328 v2f64 __builtin_msa_fmax_d (v2f64, v2f64); 17329 17330 v4f32 __builtin_msa_fmax_a_w (v4f32, v4f32); 17331 v2f64 __builtin_msa_fmax_a_d (v2f64, v2f64); 17332 17333 v4f32 __builtin_msa_fmin_w (v4f32, v4f32); 17334 v2f64 __builtin_msa_fmin_d (v2f64, v2f64); 17335 17336 v4f32 __builtin_msa_fmin_a_w (v4f32, v4f32); 17337 v2f64 __builtin_msa_fmin_a_d (v2f64, v2f64); 17338 17339 v4f32 __builtin_msa_fmsub_w (v4f32, v4f32, v4f32); 17340 v2f64 __builtin_msa_fmsub_d (v2f64, v2f64, v2f64); 17341 17342 v4f32 __builtin_msa_fmul_w (v4f32, v4f32); 17343 v2f64 __builtin_msa_fmul_d (v2f64, v2f64); 17344 17345 v4f32 __builtin_msa_frint_w (v4f32); 17346 v2f64 __builtin_msa_frint_d (v2f64); 17347 17348 v4f32 __builtin_msa_frcp_w (v4f32); 17349 v2f64 __builtin_msa_frcp_d (v2f64); 17350 17351 v4f32 __builtin_msa_frsqrt_w (v4f32); 17352 v2f64 __builtin_msa_frsqrt_d (v2f64); 17353 17354 v4i32 __builtin_msa_fsaf_w (v4f32, v4f32); 17355 v2i64 __builtin_msa_fsaf_d (v2f64, v2f64); 17356 17357 v4i32 __builtin_msa_fseq_w (v4f32, v4f32); 17358 v2i64 __builtin_msa_fseq_d (v2f64, v2f64); 17359 17360 v4i32 __builtin_msa_fsle_w (v4f32, v4f32); 17361 v2i64 __builtin_msa_fsle_d (v2f64, v2f64); 17362 17363 v4i32 __builtin_msa_fslt_w (v4f32, v4f32); 17364 v2i64 __builtin_msa_fslt_d (v2f64, v2f64); 17365 17366 v4i32 __builtin_msa_fsne_w (v4f32, v4f32); 17367 v2i64 __builtin_msa_fsne_d (v2f64, v2f64); 17368 17369 v4i32 __builtin_msa_fsor_w (v4f32, v4f32); 17370 v2i64 __builtin_msa_fsor_d (v2f64, v2f64); 17371 17372 v4f32 __builtin_msa_fsqrt_w (v4f32); 17373 v2f64 __builtin_msa_fsqrt_d (v2f64); 17374 17375 v4f32 __builtin_msa_fsub_w (v4f32, v4f32); 17376 v2f64 __builtin_msa_fsub_d (v2f64, v2f64); 17377 17378 v4i32 __builtin_msa_fsueq_w (v4f32, v4f32); 17379 v2i64 __builtin_msa_fsueq_d (v2f64, v2f64); 17380 17381 v4i32 __builtin_msa_fsule_w (v4f32, v4f32); 17382 v2i64 __builtin_msa_fsule_d (v2f64, v2f64); 17383 17384 v4i32 __builtin_msa_fsult_w (v4f32, v4f32); 17385 v2i64 __builtin_msa_fsult_d (v2f64, v2f64); 17386 17387 v4i32 __builtin_msa_fsun_w (v4f32, v4f32); 17388 v2i64 __builtin_msa_fsun_d (v2f64, v2f64); 17389 17390 v4i32 __builtin_msa_fsune_w (v4f32, v4f32); 17391 v2i64 __builtin_msa_fsune_d (v2f64, v2f64); 17392 17393 v4i32 __builtin_msa_ftint_s_w (v4f32); 17394 v2i64 __builtin_msa_ftint_s_d (v2f64); 17395 17396 v4u32 __builtin_msa_ftint_u_w (v4f32); 17397 v2u64 __builtin_msa_ftint_u_d (v2f64); 17398 17399 v8i16 __builtin_msa_ftq_h (v4f32, v4f32); 17400 v4i32 __builtin_msa_ftq_w (v2f64, v2f64); 17401 17402 v4i32 __builtin_msa_ftrunc_s_w (v4f32); 17403 v2i64 __builtin_msa_ftrunc_s_d (v2f64); 17404 17405 v4u32 __builtin_msa_ftrunc_u_w (v4f32); 17406 v2u64 __builtin_msa_ftrunc_u_d (v2f64); 17407 17408 v8i16 __builtin_msa_hadd_s_h (v16i8, v16i8); 17409 v4i32 __builtin_msa_hadd_s_w (v8i16, v8i16); 17410 v2i64 __builtin_msa_hadd_s_d (v4i32, v4i32); 17411 17412 v8u16 __builtin_msa_hadd_u_h (v16u8, v16u8); 17413 v4u32 __builtin_msa_hadd_u_w (v8u16, v8u16); 17414 v2u64 __builtin_msa_hadd_u_d (v4u32, v4u32); 17415 17416 v8i16 __builtin_msa_hsub_s_h (v16i8, v16i8); 17417 v4i32 __builtin_msa_hsub_s_w (v8i16, v8i16); 17418 v2i64 __builtin_msa_hsub_s_d (v4i32, v4i32); 17419 17420 v8i16 __builtin_msa_hsub_u_h (v16u8, v16u8); 17421 v4i32 __builtin_msa_hsub_u_w (v8u16, v8u16); 17422 v2i64 __builtin_msa_hsub_u_d (v4u32, v4u32); 17423 17424 v16i8 __builtin_msa_ilvev_b (v16i8, v16i8); 17425 v8i16 __builtin_msa_ilvev_h (v8i16, v8i16); 17426 v4i32 __builtin_msa_ilvev_w (v4i32, v4i32); 17427 v2i64 __builtin_msa_ilvev_d (v2i64, v2i64); 17428 17429 v16i8 __builtin_msa_ilvl_b (v16i8, v16i8); 17430 v8i16 __builtin_msa_ilvl_h (v8i16, v8i16); 17431 v4i32 __builtin_msa_ilvl_w (v4i32, v4i32); 17432 v2i64 __builtin_msa_ilvl_d (v2i64, v2i64); 17433 17434 v16i8 __builtin_msa_ilvod_b (v16i8, v16i8); 17435 v8i16 __builtin_msa_ilvod_h (v8i16, v8i16); 17436 v4i32 __builtin_msa_ilvod_w (v4i32, v4i32); 17437 v2i64 __builtin_msa_ilvod_d (v2i64, v2i64); 17438 17439 v16i8 __builtin_msa_ilvr_b (v16i8, v16i8); 17440 v8i16 __builtin_msa_ilvr_h (v8i16, v8i16); 17441 v4i32 __builtin_msa_ilvr_w (v4i32, v4i32); 17442 v2i64 __builtin_msa_ilvr_d (v2i64, v2i64); 17443 17444 v16i8 __builtin_msa_insert_b (v16i8, imm0_15, i32); 17445 v8i16 __builtin_msa_insert_h (v8i16, imm0_7, i32); 17446 v4i32 __builtin_msa_insert_w (v4i32, imm0_3, i32); 17447 v2i64 __builtin_msa_insert_d (v2i64, imm0_1, i64); 17448 17449 v16i8 __builtin_msa_insve_b (v16i8, imm0_15, v16i8); 17450 v8i16 __builtin_msa_insve_h (v8i16, imm0_7, v8i16); 17451 v4i32 __builtin_msa_insve_w (v4i32, imm0_3, v4i32); 17452 v2i64 __builtin_msa_insve_d (v2i64, imm0_1, v2i64); 17453 17454 v16i8 __builtin_msa_ld_b (const void *, imm_n512_511); 17455 v8i16 __builtin_msa_ld_h (const void *, imm_n1024_1022); 17456 v4i32 __builtin_msa_ld_w (const void *, imm_n2048_2044); 17457 v2i64 __builtin_msa_ld_d (const void *, imm_n4096_4088); 17458 17459 v16i8 __builtin_msa_ldi_b (imm_n512_511); 17460 v8i16 __builtin_msa_ldi_h (imm_n512_511); 17461 v4i32 __builtin_msa_ldi_w (imm_n512_511); 17462 v2i64 __builtin_msa_ldi_d (imm_n512_511); 17463 17464 v8i16 __builtin_msa_madd_q_h (v8i16, v8i16, v8i16); 17465 v4i32 __builtin_msa_madd_q_w (v4i32, v4i32, v4i32); 17466 17467 v8i16 __builtin_msa_maddr_q_h (v8i16, v8i16, v8i16); 17468 v4i32 __builtin_msa_maddr_q_w (v4i32, v4i32, v4i32); 17469 17470 v16i8 __builtin_msa_maddv_b (v16i8, v16i8, v16i8); 17471 v8i16 __builtin_msa_maddv_h (v8i16, v8i16, v8i16); 17472 v4i32 __builtin_msa_maddv_w (v4i32, v4i32, v4i32); 17473 v2i64 __builtin_msa_maddv_d (v2i64, v2i64, v2i64); 17474 17475 v16i8 __builtin_msa_max_a_b (v16i8, v16i8); 17476 v8i16 __builtin_msa_max_a_h (v8i16, v8i16); 17477 v4i32 __builtin_msa_max_a_w (v4i32, v4i32); 17478 v2i64 __builtin_msa_max_a_d (v2i64, v2i64); 17479 17480 v16i8 __builtin_msa_max_s_b (v16i8, v16i8); 17481 v8i16 __builtin_msa_max_s_h (v8i16, v8i16); 17482 v4i32 __builtin_msa_max_s_w (v4i32, v4i32); 17483 v2i64 __builtin_msa_max_s_d (v2i64, v2i64); 17484 17485 v16u8 __builtin_msa_max_u_b (v16u8, v16u8); 17486 v8u16 __builtin_msa_max_u_h (v8u16, v8u16); 17487 v4u32 __builtin_msa_max_u_w (v4u32, v4u32); 17488 v2u64 __builtin_msa_max_u_d (v2u64, v2u64); 17489 17490 v16i8 __builtin_msa_maxi_s_b (v16i8, imm_n16_15); 17491 v8i16 __builtin_msa_maxi_s_h (v8i16, imm_n16_15); 17492 v4i32 __builtin_msa_maxi_s_w (v4i32, imm_n16_15); 17493 v2i64 __builtin_msa_maxi_s_d (v2i64, imm_n16_15); 17494 17495 v16u8 __builtin_msa_maxi_u_b (v16u8, imm0_31); 17496 v8u16 __builtin_msa_maxi_u_h (v8u16, imm0_31); 17497 v4u32 __builtin_msa_maxi_u_w (v4u32, imm0_31); 17498 v2u64 __builtin_msa_maxi_u_d (v2u64, imm0_31); 17499 17500 v16i8 __builtin_msa_min_a_b (v16i8, v16i8); 17501 v8i16 __builtin_msa_min_a_h (v8i16, v8i16); 17502 v4i32 __builtin_msa_min_a_w (v4i32, v4i32); 17503 v2i64 __builtin_msa_min_a_d (v2i64, v2i64); 17504 17505 v16i8 __builtin_msa_min_s_b (v16i8, v16i8); 17506 v8i16 __builtin_msa_min_s_h (v8i16, v8i16); 17507 v4i32 __builtin_msa_min_s_w (v4i32, v4i32); 17508 v2i64 __builtin_msa_min_s_d (v2i64, v2i64); 17509 17510 v16u8 __builtin_msa_min_u_b (v16u8, v16u8); 17511 v8u16 __builtin_msa_min_u_h (v8u16, v8u16); 17512 v4u32 __builtin_msa_min_u_w (v4u32, v4u32); 17513 v2u64 __builtin_msa_min_u_d (v2u64, v2u64); 17514 17515 v16i8 __builtin_msa_mini_s_b (v16i8, imm_n16_15); 17516 v8i16 __builtin_msa_mini_s_h (v8i16, imm_n16_15); 17517 v4i32 __builtin_msa_mini_s_w (v4i32, imm_n16_15); 17518 v2i64 __builtin_msa_mini_s_d (v2i64, imm_n16_15); 17519 17520 v16u8 __builtin_msa_mini_u_b (v16u8, imm0_31); 17521 v8u16 __builtin_msa_mini_u_h (v8u16, imm0_31); 17522 v4u32 __builtin_msa_mini_u_w (v4u32, imm0_31); 17523 v2u64 __builtin_msa_mini_u_d (v2u64, imm0_31); 17524 17525 v16i8 __builtin_msa_mod_s_b (v16i8, v16i8); 17526 v8i16 __builtin_msa_mod_s_h (v8i16, v8i16); 17527 v4i32 __builtin_msa_mod_s_w (v4i32, v4i32); 17528 v2i64 __builtin_msa_mod_s_d (v2i64, v2i64); 17529 17530 v16u8 __builtin_msa_mod_u_b (v16u8, v16u8); 17531 v8u16 __builtin_msa_mod_u_h (v8u16, v8u16); 17532 v4u32 __builtin_msa_mod_u_w (v4u32, v4u32); 17533 v2u64 __builtin_msa_mod_u_d (v2u64, v2u64); 17534 17535 v16i8 __builtin_msa_move_v (v16i8); 17536 17537 v8i16 __builtin_msa_msub_q_h (v8i16, v8i16, v8i16); 17538 v4i32 __builtin_msa_msub_q_w (v4i32, v4i32, v4i32); 17539 17540 v8i16 __builtin_msa_msubr_q_h (v8i16, v8i16, v8i16); 17541 v4i32 __builtin_msa_msubr_q_w (v4i32, v4i32, v4i32); 17542 17543 v16i8 __builtin_msa_msubv_b (v16i8, v16i8, v16i8); 17544 v8i16 __builtin_msa_msubv_h (v8i16, v8i16, v8i16); 17545 v4i32 __builtin_msa_msubv_w (v4i32, v4i32, v4i32); 17546 v2i64 __builtin_msa_msubv_d (v2i64, v2i64, v2i64); 17547 17548 v8i16 __builtin_msa_mul_q_h (v8i16, v8i16); 17549 v4i32 __builtin_msa_mul_q_w (v4i32, v4i32); 17550 17551 v8i16 __builtin_msa_mulr_q_h (v8i16, v8i16); 17552 v4i32 __builtin_msa_mulr_q_w (v4i32, v4i32); 17553 17554 v16i8 __builtin_msa_mulv_b (v16i8, v16i8); 17555 v8i16 __builtin_msa_mulv_h (v8i16, v8i16); 17556 v4i32 __builtin_msa_mulv_w (v4i32, v4i32); 17557 v2i64 __builtin_msa_mulv_d (v2i64, v2i64); 17558 17559 v16i8 __builtin_msa_nloc_b (v16i8); 17560 v8i16 __builtin_msa_nloc_h (v8i16); 17561 v4i32 __builtin_msa_nloc_w (v4i32); 17562 v2i64 __builtin_msa_nloc_d (v2i64); 17563 17564 v16i8 __builtin_msa_nlzc_b (v16i8); 17565 v8i16 __builtin_msa_nlzc_h (v8i16); 17566 v4i32 __builtin_msa_nlzc_w (v4i32); 17567 v2i64 __builtin_msa_nlzc_d (v2i64); 17568 17569 v16u8 __builtin_msa_nor_v (v16u8, v16u8); 17570 17571 v16u8 __builtin_msa_nori_b (v16u8, imm0_255); 17572 17573 v16u8 __builtin_msa_or_v (v16u8, v16u8); 17574 17575 v16u8 __builtin_msa_ori_b (v16u8, imm0_255); 17576 17577 v16i8 __builtin_msa_pckev_b (v16i8, v16i8); 17578 v8i16 __builtin_msa_pckev_h (v8i16, v8i16); 17579 v4i32 __builtin_msa_pckev_w (v4i32, v4i32); 17580 v2i64 __builtin_msa_pckev_d (v2i64, v2i64); 17581 17582 v16i8 __builtin_msa_pckod_b (v16i8, v16i8); 17583 v8i16 __builtin_msa_pckod_h (v8i16, v8i16); 17584 v4i32 __builtin_msa_pckod_w (v4i32, v4i32); 17585 v2i64 __builtin_msa_pckod_d (v2i64, v2i64); 17586 17587 v16i8 __builtin_msa_pcnt_b (v16i8); 17588 v8i16 __builtin_msa_pcnt_h (v8i16); 17589 v4i32 __builtin_msa_pcnt_w (v4i32); 17590 v2i64 __builtin_msa_pcnt_d (v2i64); 17591 17592 v16i8 __builtin_msa_sat_s_b (v16i8, imm0_7); 17593 v8i16 __builtin_msa_sat_s_h (v8i16, imm0_15); 17594 v4i32 __builtin_msa_sat_s_w (v4i32, imm0_31); 17595 v2i64 __builtin_msa_sat_s_d (v2i64, imm0_63); 17596 17597 v16u8 __builtin_msa_sat_u_b (v16u8, imm0_7); 17598 v8u16 __builtin_msa_sat_u_h (v8u16, imm0_15); 17599 v4u32 __builtin_msa_sat_u_w (v4u32, imm0_31); 17600 v2u64 __builtin_msa_sat_u_d (v2u64, imm0_63); 17601 17602 v16i8 __builtin_msa_shf_b (v16i8, imm0_255); 17603 v8i16 __builtin_msa_shf_h (v8i16, imm0_255); 17604 v4i32 __builtin_msa_shf_w (v4i32, imm0_255); 17605 17606 v16i8 __builtin_msa_sld_b (v16i8, v16i8, i32); 17607 v8i16 __builtin_msa_sld_h (v8i16, v8i16, i32); 17608 v4i32 __builtin_msa_sld_w (v4i32, v4i32, i32); 17609 v2i64 __builtin_msa_sld_d (v2i64, v2i64, i32); 17610 17611 v16i8 __builtin_msa_sldi_b (v16i8, v16i8, imm0_15); 17612 v8i16 __builtin_msa_sldi_h (v8i16, v8i16, imm0_7); 17613 v4i32 __builtin_msa_sldi_w (v4i32, v4i32, imm0_3); 17614 v2i64 __builtin_msa_sldi_d (v2i64, v2i64, imm0_1); 17615 17616 v16i8 __builtin_msa_sll_b (v16i8, v16i8); 17617 v8i16 __builtin_msa_sll_h (v8i16, v8i16); 17618 v4i32 __builtin_msa_sll_w (v4i32, v4i32); 17619 v2i64 __builtin_msa_sll_d (v2i64, v2i64); 17620 17621 v16i8 __builtin_msa_slli_b (v16i8, imm0_7); 17622 v8i16 __builtin_msa_slli_h (v8i16, imm0_15); 17623 v4i32 __builtin_msa_slli_w (v4i32, imm0_31); 17624 v2i64 __builtin_msa_slli_d (v2i64, imm0_63); 17625 17626 v16i8 __builtin_msa_splat_b (v16i8, i32); 17627 v8i16 __builtin_msa_splat_h (v8i16, i32); 17628 v4i32 __builtin_msa_splat_w (v4i32, i32); 17629 v2i64 __builtin_msa_splat_d (v2i64, i32); 17630 17631 v16i8 __builtin_msa_splati_b (v16i8, imm0_15); 17632 v8i16 __builtin_msa_splati_h (v8i16, imm0_7); 17633 v4i32 __builtin_msa_splati_w (v4i32, imm0_3); 17634 v2i64 __builtin_msa_splati_d (v2i64, imm0_1); 17635 17636 v16i8 __builtin_msa_sra_b (v16i8, v16i8); 17637 v8i16 __builtin_msa_sra_h (v8i16, v8i16); 17638 v4i32 __builtin_msa_sra_w (v4i32, v4i32); 17639 v2i64 __builtin_msa_sra_d (v2i64, v2i64); 17640 17641 v16i8 __builtin_msa_srai_b (v16i8, imm0_7); 17642 v8i16 __builtin_msa_srai_h (v8i16, imm0_15); 17643 v4i32 __builtin_msa_srai_w (v4i32, imm0_31); 17644 v2i64 __builtin_msa_srai_d (v2i64, imm0_63); 17645 17646 v16i8 __builtin_msa_srar_b (v16i8, v16i8); 17647 v8i16 __builtin_msa_srar_h (v8i16, v8i16); 17648 v4i32 __builtin_msa_srar_w (v4i32, v4i32); 17649 v2i64 __builtin_msa_srar_d (v2i64, v2i64); 17650 17651 v16i8 __builtin_msa_srari_b (v16i8, imm0_7); 17652 v8i16 __builtin_msa_srari_h (v8i16, imm0_15); 17653 v4i32 __builtin_msa_srari_w (v4i32, imm0_31); 17654 v2i64 __builtin_msa_srari_d (v2i64, imm0_63); 17655 17656 v16i8 __builtin_msa_srl_b (v16i8, v16i8); 17657 v8i16 __builtin_msa_srl_h (v8i16, v8i16); 17658 v4i32 __builtin_msa_srl_w (v4i32, v4i32); 17659 v2i64 __builtin_msa_srl_d (v2i64, v2i64); 17660 17661 v16i8 __builtin_msa_srli_b (v16i8, imm0_7); 17662 v8i16 __builtin_msa_srli_h (v8i16, imm0_15); 17663 v4i32 __builtin_msa_srli_w (v4i32, imm0_31); 17664 v2i64 __builtin_msa_srli_d (v2i64, imm0_63); 17665 17666 v16i8 __builtin_msa_srlr_b (v16i8, v16i8); 17667 v8i16 __builtin_msa_srlr_h (v8i16, v8i16); 17668 v4i32 __builtin_msa_srlr_w (v4i32, v4i32); 17669 v2i64 __builtin_msa_srlr_d (v2i64, v2i64); 17670 17671 v16i8 __builtin_msa_srlri_b (v16i8, imm0_7); 17672 v8i16 __builtin_msa_srlri_h (v8i16, imm0_15); 17673 v4i32 __builtin_msa_srlri_w (v4i32, imm0_31); 17674 v2i64 __builtin_msa_srlri_d (v2i64, imm0_63); 17675 17676 void __builtin_msa_st_b (v16i8, void *, imm_n512_511); 17677 void __builtin_msa_st_h (v8i16, void *, imm_n1024_1022); 17678 void __builtin_msa_st_w (v4i32, void *, imm_n2048_2044); 17679 void __builtin_msa_st_d (v2i64, void *, imm_n4096_4088); 17680 17681 v16i8 __builtin_msa_subs_s_b (v16i8, v16i8); 17682 v8i16 __builtin_msa_subs_s_h (v8i16, v8i16); 17683 v4i32 __builtin_msa_subs_s_w (v4i32, v4i32); 17684 v2i64 __builtin_msa_subs_s_d (v2i64, v2i64); 17685 17686 v16u8 __builtin_msa_subs_u_b (v16u8, v16u8); 17687 v8u16 __builtin_msa_subs_u_h (v8u16, v8u16); 17688 v4u32 __builtin_msa_subs_u_w (v4u32, v4u32); 17689 v2u64 __builtin_msa_subs_u_d (v2u64, v2u64); 17690 17691 v16u8 __builtin_msa_subsus_u_b (v16u8, v16i8); 17692 v8u16 __builtin_msa_subsus_u_h (v8u16, v8i16); 17693 v4u32 __builtin_msa_subsus_u_w (v4u32, v4i32); 17694 v2u64 __builtin_msa_subsus_u_d (v2u64, v2i64); 17695 17696 v16i8 __builtin_msa_subsuu_s_b (v16u8, v16u8); 17697 v8i16 __builtin_msa_subsuu_s_h (v8u16, v8u16); 17698 v4i32 __builtin_msa_subsuu_s_w (v4u32, v4u32); 17699 v2i64 __builtin_msa_subsuu_s_d (v2u64, v2u64); 17700 17701 v16i8 __builtin_msa_subv_b (v16i8, v16i8); 17702 v8i16 __builtin_msa_subv_h (v8i16, v8i16); 17703 v4i32 __builtin_msa_subv_w (v4i32, v4i32); 17704 v2i64 __builtin_msa_subv_d (v2i64, v2i64); 17705 17706 v16i8 __builtin_msa_subvi_b (v16i8, imm0_31); 17707 v8i16 __builtin_msa_subvi_h (v8i16, imm0_31); 17708 v4i32 __builtin_msa_subvi_w (v4i32, imm0_31); 17709 v2i64 __builtin_msa_subvi_d (v2i64, imm0_31); 17710 17711 v16i8 __builtin_msa_vshf_b (v16i8, v16i8, v16i8); 17712 v8i16 __builtin_msa_vshf_h (v8i16, v8i16, v8i16); 17713 v4i32 __builtin_msa_vshf_w (v4i32, v4i32, v4i32); 17714 v2i64 __builtin_msa_vshf_d (v2i64, v2i64, v2i64); 17715 17716 v16u8 __builtin_msa_xor_v (v16u8, v16u8); 17717 17718 v16u8 __builtin_msa_xori_b (v16u8, imm0_255); 17719 @end smallexample 17720 17721 @node Other MIPS Built-in Functions 17722 @subsection Other MIPS Built-in Functions 17723 17724 GCC provides other MIPS-specific built-in functions: 17725 17726 @table @code 17727 @item void __builtin_mips_cache (int @var{op}, const volatile void *@var{addr}) 17728 Insert a @samp{cache} instruction with operands @var{op} and @var{addr}. 17729 GCC defines the preprocessor macro @code{___GCC_HAVE_BUILTIN_MIPS_CACHE} 17730 when this function is available. 17731 17732 @item unsigned int __builtin_mips_get_fcsr (void) 17733 @itemx void __builtin_mips_set_fcsr (unsigned int @var{value}) 17734 Get and set the contents of the floating-point control and status register 17735 (FPU control register 31). These functions are only available in hard-float 17736 code but can be called in both MIPS16 and non-MIPS16 contexts. 17737 17738 @code{__builtin_mips_set_fcsr} can be used to change any bit of the 17739 register except the condition codes, which GCC assumes are preserved. 17740 @end table 17741 17742 @node MSP430 Built-in Functions 17743 @subsection MSP430 Built-in Functions 17744 17745 GCC provides a couple of special builtin functions to aid in the 17746 writing of interrupt handlers in C. 17747 17748 @table @code 17749 @item __bic_SR_register_on_exit (int @var{mask}) 17750 This clears the indicated bits in the saved copy of the status register 17751 currently residing on the stack. This only works inside interrupt 17752 handlers and the changes to the status register will only take affect 17753 once the handler returns. 17754 17755 @item __bis_SR_register_on_exit (int @var{mask}) 17756 This sets the indicated bits in the saved copy of the status register 17757 currently residing on the stack. This only works inside interrupt 17758 handlers and the changes to the status register will only take affect 17759 once the handler returns. 17760 17761 @item __delay_cycles (long long @var{cycles}) 17762 This inserts an instruction sequence that takes exactly @var{cycles} 17763 cycles (between 0 and about 17E9) to complete. The inserted sequence 17764 may use jumps, loops, or no-ops, and does not interfere with any other 17765 instructions. Note that @var{cycles} must be a compile-time constant 17766 integer - that is, you must pass a number, not a variable that may be 17767 optimized to a constant later. The number of cycles delayed by this 17768 builtin is exact. 17769 @end table 17770 17771 @node NDS32 Built-in Functions 17772 @subsection NDS32 Built-in Functions 17773 17774 These built-in functions are available for the NDS32 target: 17775 17776 @deftypefn {Built-in Function} void __builtin_nds32_isync (int *@var{addr}) 17777 Insert an ISYNC instruction into the instruction stream where 17778 @var{addr} is an instruction address for serialization. 17779 @end deftypefn 17780 17781 @deftypefn {Built-in Function} void __builtin_nds32_isb (void) 17782 Insert an ISB instruction into the instruction stream. 17783 @end deftypefn 17784 17785 @deftypefn {Built-in Function} int __builtin_nds32_mfsr (int @var{sr}) 17786 Return the content of a system register which is mapped by @var{sr}. 17787 @end deftypefn 17788 17789 @deftypefn {Built-in Function} int __builtin_nds32_mfusr (int @var{usr}) 17790 Return the content of a user space register which is mapped by @var{usr}. 17791 @end deftypefn 17792 17793 @deftypefn {Built-in Function} void __builtin_nds32_mtsr (int @var{value}, int @var{sr}) 17794 Move the @var{value} to a system register which is mapped by @var{sr}. 17795 @end deftypefn 17796 17797 @deftypefn {Built-in Function} void __builtin_nds32_mtusr (int @var{value}, int @var{usr}) 17798 Move the @var{value} to a user space register which is mapped by @var{usr}. 17799 @end deftypefn 17800 17801 @deftypefn {Built-in Function} void __builtin_nds32_setgie_en (void) 17802 Enable global interrupt. 17803 @end deftypefn 17804 17805 @deftypefn {Built-in Function} void __builtin_nds32_setgie_dis (void) 17806 Disable global interrupt. 17807 @end deftypefn 17808 17809 @node picoChip Built-in Functions 17810 @subsection picoChip Built-in Functions 17811 17812 GCC provides an interface to selected machine instructions from the 17813 picoChip instruction set. 17814 17815 @table @code 17816 @item int __builtin_sbc (int @var{value}) 17817 Sign bit count. Return the number of consecutive bits in @var{value} 17818 that have the same value as the sign bit. The result is the number of 17819 leading sign bits minus one, giving the number of redundant sign bits in 17820 @var{value}. 17821 17822 @item int __builtin_byteswap (int @var{value}) 17823 Byte swap. Return the result of swapping the upper and lower bytes of 17824 @var{value}. 17825 17826 @item int __builtin_brev (int @var{value}) 17827 Bit reversal. Return the result of reversing the bits in 17828 @var{value}. Bit 15 is swapped with bit 0, bit 14 is swapped with bit 1, 17829 and so on. 17830 17831 @item int __builtin_adds (int @var{x}, int @var{y}) 17832 Saturating addition. Return the result of adding @var{x} and @var{y}, 17833 storing the value 32767 if the result overflows. 17834 17835 @item int __builtin_subs (int @var{x}, int @var{y}) 17836 Saturating subtraction. Return the result of subtracting @var{y} from 17837 @var{x}, storing the value @minus{}32768 if the result overflows. 17838 17839 @item void __builtin_halt (void) 17840 Halt. The processor stops execution. This built-in is useful for 17841 implementing assertions. 17842 17843 @end table 17844 17845 @node Basic PowerPC Built-in Functions 17846 @subsection Basic PowerPC Built-in Functions 17847 17848 @menu 17849 * Basic PowerPC Built-in Functions Available on all Configurations:: 17850 * Basic PowerPC Built-in Functions Available on ISA 2.05:: 17851 * Basic PowerPC Built-in Functions Available on ISA 2.06:: 17852 * Basic PowerPC Built-in Functions Available on ISA 2.07:: 17853 * Basic PowerPC Built-in Functions Available on ISA 3.0:: 17854 * Basic PowerPC Built-in Functions Available on ISA 3.1:: 17855 @end menu 17856 17857 This section describes PowerPC built-in functions that do not require 17858 the inclusion of any special header files to declare prototypes or 17859 provide macro definitions. The sections that follow describe 17860 additional PowerPC built-in functions. 17861 17862 @node Basic PowerPC Built-in Functions Available on all Configurations 17863 @subsubsection Basic PowerPC Built-in Functions Available on all Configurations 17864 17865 @deftypefn {Built-in Function} void __builtin_cpu_init (void) 17866 This function is a @code{nop} on the PowerPC platform and is included solely 17867 to maintain API compatibility with the x86 builtins. 17868 @end deftypefn 17869 17870 @deftypefn {Built-in Function} int __builtin_cpu_is (const char *@var{cpuname}) 17871 This function returns a value of @code{1} if the run-time CPU is of type 17872 @var{cpuname} and returns @code{0} otherwise 17873 17874 The @code{__builtin_cpu_is} function requires GLIBC 2.23 or newer 17875 which exports the hardware capability bits. GCC defines the macro 17876 @code{__BUILTIN_CPU_SUPPORTS__} if the @code{__builtin_cpu_supports} 17877 built-in function is fully supported. 17878 17879 If GCC was configured to use a GLIBC before 2.23, the built-in 17880 function @code{__builtin_cpu_is} always returns a 0 and the compiler 17881 issues a warning. 17882 17883 The following CPU names can be detected: 17884 17885 @table @samp 17886 @item power10 17887 IBM POWER10 Server CPU. 17888 @item power9 17889 IBM POWER9 Server CPU. 17890 @item power8 17891 IBM POWER8 Server CPU. 17892 @item power7 17893 IBM POWER7 Server CPU. 17894 @item power6x 17895 IBM POWER6 Server CPU (RAW mode). 17896 @item power6 17897 IBM POWER6 Server CPU (Architected mode). 17898 @item power5+ 17899 IBM POWER5+ Server CPU. 17900 @item power5 17901 IBM POWER5 Server CPU. 17902 @item ppc970 17903 IBM 970 Server CPU (ie, Apple G5). 17904 @item power4 17905 IBM POWER4 Server CPU. 17906 @item ppca2 17907 IBM A2 64-bit Embedded CPU 17908 @item ppc476 17909 IBM PowerPC 476FP 32-bit Embedded CPU. 17910 @item ppc464 17911 IBM PowerPC 464 32-bit Embedded CPU. 17912 @item ppc440 17913 PowerPC 440 32-bit Embedded CPU. 17914 @item ppc405 17915 PowerPC 405 32-bit Embedded CPU. 17916 @item ppc-cell-be 17917 IBM PowerPC Cell Broadband Engine Architecture CPU. 17918 @end table 17919 17920 Here is an example: 17921 @smallexample 17922 #ifdef __BUILTIN_CPU_SUPPORTS__ 17923 if (__builtin_cpu_is ("power8")) 17924 @{ 17925 do_power8 (); // POWER8 specific implementation. 17926 @} 17927 else 17928 #endif 17929 @{ 17930 do_generic (); // Generic implementation. 17931 @} 17932 @end smallexample 17933 @end deftypefn 17934 17935 @deftypefn {Built-in Function} int __builtin_cpu_supports (const char *@var{feature}) 17936 This function returns a value of @code{1} if the run-time CPU supports the HWCAP 17937 feature @var{feature} and returns @code{0} otherwise. 17938 17939 The @code{__builtin_cpu_supports} function requires GLIBC 2.23 or 17940 newer which exports the hardware capability bits. GCC defines the 17941 macro @code{__BUILTIN_CPU_SUPPORTS__} if the 17942 @code{__builtin_cpu_supports} built-in function is fully supported. 17943 17944 If GCC was configured to use a GLIBC before 2.23, the built-in 17945 function @code{__builtin_cpu_supports} always returns a 0 and the 17946 compiler issues a warning. 17947 17948 The following features can be 17949 detected: 17950 17951 @table @samp 17952 @item 4xxmac 17953 4xx CPU has a Multiply Accumulator. 17954 @item altivec 17955 CPU has a SIMD/Vector Unit. 17956 @item arch_2_05 17957 CPU supports ISA 2.05 (eg, POWER6) 17958 @item arch_2_06 17959 CPU supports ISA 2.06 (eg, POWER7) 17960 @item arch_2_07 17961 CPU supports ISA 2.07 (eg, POWER8) 17962 @item arch_3_00 17963 CPU supports ISA 3.0 (eg, POWER9) 17964 @item arch_3_1 17965 CPU supports ISA 3.1 (eg, POWER10) 17966 @item archpmu 17967 CPU supports the set of compatible performance monitoring events. 17968 @item booke 17969 CPU supports the Embedded ISA category. 17970 @item cellbe 17971 CPU has a CELL broadband engine. 17972 @item darn 17973 CPU supports the @code{darn} (deliver a random number) instruction. 17974 @item dfp 17975 CPU has a decimal floating point unit. 17976 @item dscr 17977 CPU supports the data stream control register. 17978 @item ebb 17979 CPU supports event base branching. 17980 @item efpdouble 17981 CPU has a SPE double precision floating point unit. 17982 @item efpsingle 17983 CPU has a SPE single precision floating point unit. 17984 @item fpu 17985 CPU has a floating point unit. 17986 @item htm 17987 CPU has hardware transaction memory instructions. 17988 @item htm-nosc 17989 Kernel aborts hardware transactions when a syscall is made. 17990 @item htm-no-suspend 17991 CPU supports hardware transaction memory but does not support the 17992 @code{tsuspend.} instruction. 17993 @item ic_snoop 17994 CPU supports icache snooping capabilities. 17995 @item ieee128 17996 CPU supports 128-bit IEEE binary floating point instructions. 17997 @item isel 17998 CPU supports the integer select instruction. 17999 @item mma 18000 CPU supports the matrix-multiply assist instructions. 18001 @item mmu 18002 CPU has a memory management unit. 18003 @item notb 18004 CPU does not have a timebase (eg, 601 and 403gx). 18005 @item pa6t 18006 CPU supports the PA Semi 6T CORE ISA. 18007 @item power4 18008 CPU supports ISA 2.00 (eg, POWER4) 18009 @item power5 18010 CPU supports ISA 2.02 (eg, POWER5) 18011 @item power5+ 18012 CPU supports ISA 2.03 (eg, POWER5+) 18013 @item power6x 18014 CPU supports ISA 2.05 (eg, POWER6) extended opcodes mffgpr and mftgpr. 18015 @item ppc32 18016 CPU supports 32-bit mode execution. 18017 @item ppc601 18018 CPU supports the old POWER ISA (eg, 601) 18019 @item ppc64 18020 CPU supports 64-bit mode execution. 18021 @item ppcle 18022 CPU supports a little-endian mode that uses address swizzling. 18023 @item scv 18024 Kernel supports system call vectored. 18025 @item smt 18026 CPU support simultaneous multi-threading. 18027 @item spe 18028 CPU has a signal processing extension unit. 18029 @item tar 18030 CPU supports the target address register. 18031 @item true_le 18032 CPU supports true little-endian mode. 18033 @item ucache 18034 CPU has unified I/D cache. 18035 @item vcrypto 18036 CPU supports the vector cryptography instructions. 18037 @item vsx 18038 CPU supports the vector-scalar extension. 18039 @end table 18040 18041 Here is an example: 18042 @smallexample 18043 #ifdef __BUILTIN_CPU_SUPPORTS__ 18044 if (__builtin_cpu_supports ("fpu")) 18045 @{ 18046 asm("fadd %0,%1,%2" : "=d"(dst) : "d"(src1), "d"(src2)); 18047 @} 18048 else 18049 #endif 18050 @{ 18051 dst = __fadd (src1, src2); // Software FP addition function. 18052 @} 18053 @end smallexample 18054 @end deftypefn 18055 18056 The following built-in functions are also available on all PowerPC 18057 processors: 18058 @smallexample 18059 uint64_t __builtin_ppc_get_timebase (); 18060 unsigned long __builtin_ppc_mftb (); 18061 double __builtin_unpack_ibm128 (__ibm128, int); 18062 __ibm128 __builtin_pack_ibm128 (double, double); 18063 double __builtin_mffs (void); 18064 void __builtin_mtfsf (const int, double); 18065 void __builtin_mtfsb0 (const int); 18066 void __builtin_mtfsb1 (const int); 18067 void __builtin_set_fpscr_rn (int); 18068 @end smallexample 18069 18070 The @code{__builtin_ppc_get_timebase} and @code{__builtin_ppc_mftb} 18071 functions generate instructions to read the Time Base Register. The 18072 @code{__builtin_ppc_get_timebase} function may generate multiple 18073 instructions and always returns the 64 bits of the Time Base Register. 18074 The @code{__builtin_ppc_mftb} function always generates one instruction and 18075 returns the Time Base Register value as an unsigned long, throwing away 18076 the most significant word on 32-bit environments. The @code{__builtin_mffs} 18077 return the value of the FPSCR register. Note, ISA 3.0 supports the 18078 @code{__builtin_mffsl()} which permits software to read the control and 18079 non-sticky status bits in the FSPCR without the higher latency associated with 18080 accessing the sticky status bits. The @code{__builtin_mtfsf} takes a constant 18081 8-bit integer field mask and a double precision floating point argument 18082 and generates the @code{mtfsf} (extended mnemonic) instruction to write new 18083 values to selected fields of the FPSCR. The 18084 @code{__builtin_mtfsb0} and @code{__builtin_mtfsb1} take the bit to change 18085 as an argument. The valid bit range is between 0 and 31. The builtins map to 18086 the @code{mtfsb0} and @code{mtfsb1} instructions which take the argument and 18087 add 32. Hence these instructions only modify the FPSCR[32:63] bits by 18088 changing the specified bit to a zero or one respectively. The 18089 @code{__builtin_set_fpscr_rn} builtin allows changing both of the floating 18090 point rounding mode bits. The argument is a 2-bit value. The argument can 18091 either be a @code{const int} or stored in a variable. The builtin uses 18092 the ISA 3.0 18093 instruction @code{mffscrn} if available, otherwise it reads the FPSCR, masks 18094 the current rounding mode bits out and OR's in the new value. 18095 18096 @node Basic PowerPC Built-in Functions Available on ISA 2.05 18097 @subsubsection Basic PowerPC Built-in Functions Available on ISA 2.05 18098 18099 The basic built-in functions described in this section are 18100 available on the PowerPC family of processors starting with ISA 2.05 18101 or later. Unless specific options are explicitly disabled on the 18102 command line, specifying option @option{-mcpu=power6} has the effect of 18103 enabling the @option{-mpowerpc64}, @option{-mpowerpc-gpopt}, 18104 @option{-mpowerpc-gfxopt}, @option{-mmfcrf}, @option{-mpopcntb}, 18105 @option{-mfprnd}, @option{-mcmpb}, @option{-mhard-dfp}, and 18106 @option{-mrecip-precision} options. Specify the 18107 @option{-maltivec} option explicitly in 18108 combination with the above options if desired. 18109 18110 The following functions require option @option{-mcmpb}. 18111 @smallexample 18112 unsigned long long __builtin_cmpb (unsigned long long int, unsigned long long int); 18113 unsigned int __builtin_cmpb (unsigned int, unsigned int); 18114 @end smallexample 18115 18116 The @code{__builtin_cmpb} function 18117 performs a byte-wise compare on the contents of its two arguments, 18118 returning the result of the byte-wise comparison as the returned 18119 value. For each byte comparison, the corresponding byte of the return 18120 value holds 0xff if the input bytes are equal and 0 if the input bytes 18121 are not equal. If either of the arguments to this built-in function 18122 is wider than 32 bits, the function call expands into the form that 18123 expects @code{unsigned long long int} arguments 18124 which is only available on 64-bit targets. 18125 18126 The following built-in functions are available 18127 when hardware decimal floating point 18128 (@option{-mhard-dfp}) is available: 18129 @smallexample 18130 void __builtin_set_fpscr_drn(int); 18131 _Decimal64 __builtin_ddedpd (int, _Decimal64); 18132 _Decimal128 __builtin_ddedpdq (int, _Decimal128); 18133 _Decimal64 __builtin_denbcd (int, _Decimal64); 18134 _Decimal128 __builtin_denbcdq (int, _Decimal128); 18135 _Decimal64 __builtin_diex (long long, _Decimal64); 18136 _Decimal128 _builtin_diexq (long long, _Decimal128); 18137 _Decimal64 __builtin_dscli (_Decimal64, int); 18138 _Decimal128 __builtin_dscliq (_Decimal128, int); 18139 _Decimal64 __builtin_dscri (_Decimal64, int); 18140 _Decimal128 __builtin_dscriq (_Decimal128, int); 18141 long long __builtin_dxex (_Decimal64); 18142 long long __builtin_dxexq (_Decimal128); 18143 _Decimal128 __builtin_pack_dec128 (unsigned long long, unsigned long long); 18144 unsigned long long __builtin_unpack_dec128 (_Decimal128, int); 18145 18146 The @code{__builtin_set_fpscr_drn} builtin allows changing the three decimal 18147 floating point rounding mode bits. The argument is a 3-bit value. The 18148 argument can either be a @code{const int} or the value can be stored in 18149 a variable. 18150 The builtin uses the ISA 3.0 instruction @code{mffscdrn} if available. 18151 Otherwise the builtin reads the FPSCR, masks the current decimal rounding 18152 mode bits out and OR's in the new value. 18153 18154 @end smallexample 18155 18156 The following functions require @option{-mhard-float}, 18157 @option{-mpowerpc-gfxopt}, and @option{-mpopcntb} options. 18158 18159 @smallexample 18160 double __builtin_recipdiv (double, double); 18161 float __builtin_recipdivf (float, float); 18162 double __builtin_rsqrt (double); 18163 float __builtin_rsqrtf (float); 18164 @end smallexample 18165 18166 The @code{vec_rsqrt}, @code{__builtin_rsqrt}, and 18167 @code{__builtin_rsqrtf} functions generate multiple instructions to 18168 implement the reciprocal sqrt functionality using reciprocal sqrt 18169 estimate instructions. 18170 18171 The @code{__builtin_recipdiv}, and @code{__builtin_recipdivf} 18172 functions generate multiple instructions to implement division using 18173 the reciprocal estimate instructions. 18174 18175 The following functions require @option{-mhard-float} and 18176 @option{-mmultiple} options. 18177 18178 The @code{__builtin_unpack_longdouble} function takes a 18179 @code{long double} argument and a compile time constant of 0 or 1. If 18180 the constant is 0, the first @code{double} within the 18181 @code{long double} is returned, otherwise the second @code{double} 18182 is returned. The @code{__builtin_unpack_longdouble} function is only 18183 available if @code{long double} uses the IBM extended double 18184 representation. 18185 18186 The @code{__builtin_pack_longdouble} function takes two @code{double} 18187 arguments and returns a @code{long double} value that combines the two 18188 arguments. The @code{__builtin_pack_longdouble} function is only 18189 available if @code{long double} uses the IBM extended double 18190 representation. 18191 18192 The @code{__builtin_unpack_ibm128} function takes a @code{__ibm128} 18193 argument and a compile time constant of 0 or 1. If the constant is 0, 18194 the first @code{double} within the @code{__ibm128} is returned, 18195 otherwise the second @code{double} is returned. 18196 18197 The @code{__builtin_pack_ibm128} function takes two @code{double} 18198 arguments and returns a @code{__ibm128} value that combines the two 18199 arguments. 18200 18201 Additional built-in functions are available for the 64-bit PowerPC 18202 family of processors, for efficient use of 128-bit floating point 18203 (@code{__float128}) values. 18204 18205 @node Basic PowerPC Built-in Functions Available on ISA 2.06 18206 @subsubsection Basic PowerPC Built-in Functions Available on ISA 2.06 18207 18208 The basic built-in functions described in this section are 18209 available on the PowerPC family of processors starting with ISA 2.05 18210 or later. Unless specific options are explicitly disabled on the 18211 command line, specifying option @option{-mcpu=power7} has the effect of 18212 enabling all the same options as for @option{-mcpu=power6} in 18213 addition to the @option{-maltivec}, @option{-mpopcntd}, and 18214 @option{-mvsx} options. 18215 18216 The following basic built-in functions require @option{-mpopcntd}: 18217 @smallexample 18218 unsigned int __builtin_addg6s (unsigned int, unsigned int); 18219 long long __builtin_bpermd (long long, long long); 18220 unsigned int __builtin_cbcdtd (unsigned int); 18221 unsigned int __builtin_cdtbcd (unsigned int); 18222 long long __builtin_divde (long long, long long); 18223 unsigned long long __builtin_divdeu (unsigned long long, unsigned long long); 18224 int __builtin_divwe (int, int); 18225 unsigned int __builtin_divweu (unsigned int, unsigned int); 18226 vector __int128 __builtin_pack_vector_int128 (long long, long long); 18227 void __builtin_rs6000_speculation_barrier (void); 18228 long long __builtin_unpack_vector_int128 (vector __int128, signed char); 18229 @end smallexample 18230 18231 Of these, the @code{__builtin_divde} and @code{__builtin_divdeu} functions 18232 require a 64-bit environment. 18233 18234 The following basic built-in functions, which are also supported on 18235 x86 targets, require @option{-mfloat128}. 18236 @smallexample 18237 __float128 __builtin_fabsq (__float128); 18238 __float128 __builtin_copysignq (__float128, __float128); 18239 __float128 __builtin_infq (void); 18240 __float128 __builtin_huge_valq (void); 18241 __float128 __builtin_nanq (void); 18242 __float128 __builtin_nansq (void); 18243 18244 __float128 __builtin_sqrtf128 (__float128); 18245 __float128 __builtin_fmaf128 (__float128, __float128, __float128); 18246 @end smallexample 18247 18248 @node Basic PowerPC Built-in Functions Available on ISA 2.07 18249 @subsubsection Basic PowerPC Built-in Functions Available on ISA 2.07 18250 18251 The basic built-in functions described in this section are 18252 available on the PowerPC family of processors starting with ISA 2.07 18253 or later. Unless specific options are explicitly disabled on the 18254 command line, specifying option @option{-mcpu=power8} has the effect of 18255 enabling all the same options as for @option{-mcpu=power7} in 18256 addition to the @option{-mpower8-fusion}, @option{-mpower8-vector}, 18257 @option{-mcrypto}, @option{-mhtm}, @option{-mquad-memory}, and 18258 @option{-mquad-memory-atomic} options. 18259 18260 This section intentionally empty. 18261 18262 @node Basic PowerPC Built-in Functions Available on ISA 3.0 18263 @subsubsection Basic PowerPC Built-in Functions Available on ISA 3.0 18264 18265 The basic built-in functions described in this section are 18266 available on the PowerPC family of processors starting with ISA 3.0 18267 or later. Unless specific options are explicitly disabled on the 18268 command line, specifying option @option{-mcpu=power9} has the effect of 18269 enabling all the same options as for @option{-mcpu=power8} in 18270 addition to the @option{-misel} option. 18271 18272 The following built-in functions are available on Linux 64-bit systems 18273 that use the ISA 3.0 instruction set (@option{-mcpu=power9}): 18274 18275 @table @code 18276 @item __float128 __builtin_addf128_round_to_odd (__float128, __float128) 18277 Perform a 128-bit IEEE floating point add using round to odd as the 18278 rounding mode. 18279 @findex __builtin_addf128_round_to_odd 18280 18281 @item __float128 __builtin_subf128_round_to_odd (__float128, __float128) 18282 Perform a 128-bit IEEE floating point subtract using round to odd as 18283 the rounding mode. 18284 @findex __builtin_subf128_round_to_odd 18285 18286 @item __float128 __builtin_mulf128_round_to_odd (__float128, __float128) 18287 Perform a 128-bit IEEE floating point multiply using round to odd as 18288 the rounding mode. 18289 @findex __builtin_mulf128_round_to_odd 18290 18291 @item __float128 __builtin_divf128_round_to_odd (__float128, __float128) 18292 Perform a 128-bit IEEE floating point divide using round to odd as 18293 the rounding mode. 18294 @findex __builtin_divf128_round_to_odd 18295 18296 @item __float128 __builtin_sqrtf128_round_to_odd (__float128) 18297 Perform a 128-bit IEEE floating point square root using round to odd 18298 as the rounding mode. 18299 @findex __builtin_sqrtf128_round_to_odd 18300 18301 @item __float128 __builtin_fmaf128_round_to_odd (__float128, __float128, __float128) 18302 Perform a 128-bit IEEE floating point fused multiply and add operation 18303 using round to odd as the rounding mode. 18304 @findex __builtin_fmaf128_round_to_odd 18305 18306 @item double __builtin_truncf128_round_to_odd (__float128) 18307 Convert a 128-bit IEEE floating point value to @code{double} using 18308 round to odd as the rounding mode. 18309 @findex __builtin_truncf128_round_to_odd 18310 @end table 18311 18312 The following additional built-in functions are also available for the 18313 PowerPC family of processors, starting with ISA 3.0 or later: 18314 @smallexample 18315 long long __builtin_darn (void); 18316 long long __builtin_darn_raw (void); 18317 int __builtin_darn_32 (void); 18318 @end smallexample 18319 18320 The @code{__builtin_darn} and @code{__builtin_darn_raw} 18321 functions require a 18322 64-bit environment supporting ISA 3.0 or later. 18323 The @code{__builtin_darn} function provides a 64-bit conditioned 18324 random number. The @code{__builtin_darn_raw} function provides a 18325 64-bit raw random number. The @code{__builtin_darn_32} function 18326 provides a 32-bit conditioned random number. 18327 18328 The following additional built-in functions are also available for the 18329 PowerPC family of processors, starting with ISA 3.0 or later: 18330 18331 @smallexample 18332 int __builtin_byte_in_set (unsigned char u, unsigned long long set); 18333 int __builtin_byte_in_range (unsigned char u, unsigned int range); 18334 int __builtin_byte_in_either_range (unsigned char u, unsigned int ranges); 18335 18336 int __builtin_dfp_dtstsfi_lt (unsigned int comparison, _Decimal64 value); 18337 int __builtin_dfp_dtstsfi_lt (unsigned int comparison, _Decimal128 value); 18338 int __builtin_dfp_dtstsfi_lt_dd (unsigned int comparison, _Decimal64 value); 18339 int __builtin_dfp_dtstsfi_lt_td (unsigned int comparison, _Decimal128 value); 18340 18341 int __builtin_dfp_dtstsfi_gt (unsigned int comparison, _Decimal64 value); 18342 int __builtin_dfp_dtstsfi_gt (unsigned int comparison, _Decimal128 value); 18343 int __builtin_dfp_dtstsfi_gt_dd (unsigned int comparison, _Decimal64 value); 18344 int __builtin_dfp_dtstsfi_gt_td (unsigned int comparison, _Decimal128 value); 18345 18346 int __builtin_dfp_dtstsfi_eq (unsigned int comparison, _Decimal64 value); 18347 int __builtin_dfp_dtstsfi_eq (unsigned int comparison, _Decimal128 value); 18348 int __builtin_dfp_dtstsfi_eq_dd (unsigned int comparison, _Decimal64 value); 18349 int __builtin_dfp_dtstsfi_eq_td (unsigned int comparison, _Decimal128 value); 18350 18351 int __builtin_dfp_dtstsfi_ov (unsigned int comparison, _Decimal64 value); 18352 int __builtin_dfp_dtstsfi_ov (unsigned int comparison, _Decimal128 value); 18353 int __builtin_dfp_dtstsfi_ov_dd (unsigned int comparison, _Decimal64 value); 18354 int __builtin_dfp_dtstsfi_ov_td (unsigned int comparison, _Decimal128 value); 18355 18356 double __builtin_mffsl(void); 18357 18358 @end smallexample 18359 The @code{__builtin_byte_in_set} function requires a 18360 64-bit environment supporting ISA 3.0 or later. This function returns 18361 a non-zero value if and only if its @code{u} argument exactly equals one of 18362 the eight bytes contained within its 64-bit @code{set} argument. 18363 18364 The @code{__builtin_byte_in_range} and 18365 @code{__builtin_byte_in_either_range} require an environment 18366 supporting ISA 3.0 or later. For these two functions, the 18367 @code{range} argument is encoded as 4 bytes, organized as 18368 @code{hi_1:lo_1:hi_2:lo_2}. 18369 The @code{__builtin_byte_in_range} function returns a 18370 non-zero value if and only if its @code{u} argument is within the 18371 range bounded between @code{lo_2} and @code{hi_2} inclusive. 18372 The @code{__builtin_byte_in_either_range} function returns non-zero if 18373 and only if its @code{u} argument is within either the range bounded 18374 between @code{lo_1} and @code{hi_1} inclusive or the range bounded 18375 between @code{lo_2} and @code{hi_2} inclusive. 18376 18377 The @code{__builtin_dfp_dtstsfi_lt} function returns a non-zero value 18378 if and only if the number of signficant digits of its @code{value} argument 18379 is less than its @code{comparison} argument. The 18380 @code{__builtin_dfp_dtstsfi_lt_dd} and 18381 @code{__builtin_dfp_dtstsfi_lt_td} functions behave similarly, but 18382 require that the type of the @code{value} argument be 18383 @code{__Decimal64} and @code{__Decimal128} respectively. 18384 18385 The @code{__builtin_dfp_dtstsfi_gt} function returns a non-zero value 18386 if and only if the number of signficant digits of its @code{value} argument 18387 is greater than its @code{comparison} argument. The 18388 @code{__builtin_dfp_dtstsfi_gt_dd} and 18389 @code{__builtin_dfp_dtstsfi_gt_td} functions behave similarly, but 18390 require that the type of the @code{value} argument be 18391 @code{__Decimal64} and @code{__Decimal128} respectively. 18392 18393 The @code{__builtin_dfp_dtstsfi_eq} function returns a non-zero value 18394 if and only if the number of signficant digits of its @code{value} argument 18395 equals its @code{comparison} argument. The 18396 @code{__builtin_dfp_dtstsfi_eq_dd} and 18397 @code{__builtin_dfp_dtstsfi_eq_td} functions behave similarly, but 18398 require that the type of the @code{value} argument be 18399 @code{__Decimal64} and @code{__Decimal128} respectively. 18400 18401 The @code{__builtin_dfp_dtstsfi_ov} function returns a non-zero value 18402 if and only if its @code{value} argument has an undefined number of 18403 significant digits, such as when @code{value} is an encoding of @code{NaN}. 18404 The @code{__builtin_dfp_dtstsfi_ov_dd} and 18405 @code{__builtin_dfp_dtstsfi_ov_td} functions behave similarly, but 18406 require that the type of the @code{value} argument be 18407 @code{__Decimal64} and @code{__Decimal128} respectively. 18408 18409 The @code{__builtin_mffsl} uses the ISA 3.0 @code{mffsl} instruction to read 18410 the FPSCR. The instruction is a lower latency version of the @code{mffs} 18411 instruction. If the @code{mffsl} instruction is not available, then the 18412 builtin uses the older @code{mffs} instruction to read the FPSCR. 18413 18414 @node Basic PowerPC Built-in Functions Available on ISA 3.1 18415 @subsubsection Basic PowerPC Built-in Functions Available on ISA 3.1 18416 18417 The basic built-in functions described in this section are 18418 available on the PowerPC family of processors starting with ISA 3.1. 18419 Unless specific options are explicitly disabled on the 18420 command line, specifying option @option{-mcpu=power10} has the effect of 18421 enabling all the same options as for @option{-mcpu=power9}. 18422 18423 The following built-in functions are available on Linux 64-bit systems 18424 that use a future architecture instruction set (@option{-mcpu=power10}): 18425 18426 @smallexample 18427 @exdent unsigned long long 18428 @exdent __builtin_cfuged (unsigned long long, unsigned long long) 18429 @end smallexample 18430 Perform a 64-bit centrifuge operation, as if implemented by the 18431 @code{cfuged} instruction. 18432 @findex __builtin_cfuged 18433 18434 @smallexample 18435 @exdent unsigned long long 18436 @exdent __builtin_cntlzdm (unsigned long long, unsigned long long) 18437 @end smallexample 18438 Perform a 64-bit count leading zeros operation under mask, as if 18439 implemented by the @code{cntlzdm} instruction. 18440 @findex __builtin_cntlzdm 18441 18442 @smallexample 18443 @exdent unsigned long long 18444 @exdent __builtin_cnttzdm (unsigned long long, unsigned long long) 18445 @end smallexample 18446 Perform a 64-bit count trailing zeros operation under mask, as if 18447 implemented by the @code{cnttzdm} instruction. 18448 @findex __builtin_cnttzdm 18449 18450 @smallexample 18451 @exdent unsigned long long 18452 @exdent __builtin_pdepd (unsigned long long, unsigned long long) 18453 @end smallexample 18454 Perform a 64-bit parallel bits deposit operation, as if implemented by the 18455 @code{pdepd} instruction. 18456 @findex __builtin_pdepd 18457 18458 @smallexample 18459 @exdent unsigned long long 18460 @exdent __builtin_pextd (unsigned long long, unsigned long long) 18461 @end smallexample 18462 Perform a 64-bit parallel bits extract operation, as if implemented by the 18463 @code{pextd} instruction. 18464 @findex __builtin_pextd 18465 18466 @smallexample 18467 @exdent vector signed __int128 vsx_xl_sext (signed long long, signed char *) 18468 18469 @exdent vector signed __int128 vsx_xl_sext (signed long long, signed short *) 18470 18471 @exdent vector signed __int128 vsx_xl_sext (signed long long, signed int *) 18472 18473 @exdent vector signed __int128 vsx_xl_sext (signed long long, signed long long *) 18474 18475 @exdent vector unsigned __int128 vsx_xl_zext (signed long long, unsigned char *) 18476 18477 @exdent vector unsigned __int128 vsx_xl_zext (signed long long, unsigned short *) 18478 18479 @exdent vector unsigned __int128 vsx_xl_zext (signed long long, unsigned int *) 18480 18481 @exdent vector unsigned __int128 vsx_xl_zext (signed long long, unsigned long long *) 18482 @end smallexample 18483 18484 Load (and sign extend) to an __int128 vector, as if implemented by the ISA 3.1 18485 @code{lxvrbx}, @code{lxvrhx}, @code{lxvrwx}, and @code{lxvrdx} instructions. 18486 @findex vsx_xl_sext 18487 @findex vsx_xl_zext 18488 18489 @smallexample 18490 @exdent void vec_xst_trunc (vector signed __int128, signed long long, signed char *) 18491 18492 @exdent void vec_xst_trunc (vector signed __int128, signed long long, signed short *) 18493 18494 @exdent void vec_xst_trunc (vector signed __int128, signed long long, signed int *) 18495 18496 @exdent void vec_xst_trunc (vector signed __int128, signed long long, signed long long *) 18497 18498 @exdent void vec_xst_trunc (vector unsigned __int128, signed long long, unsigned char *) 18499 18500 @exdent void vec_xst_trunc (vector unsigned __int128, signed long long, unsigned short *) 18501 18502 @exdent void vec_xst_trunc (vector unsigned __int128, signed long long, unsigned int *) 18503 18504 @exdent void vec_xst_trunc (vector unsigned __int128, signed long long, unsigned long long *) 18505 @end smallexample 18506 18507 Truncate and store the rightmost element of a vector, as if implemented by the 18508 ISA 3.1 @code{stxvrbx}, @code{stxvrhx}, @code{stxvrwx}, and @code{stxvrdx} 18509 instructions. 18510 @findex vec_xst_trunc 18511 18512 @node PowerPC AltiVec/VSX Built-in Functions 18513 @subsection PowerPC AltiVec/VSX Built-in Functions 18514 18515 GCC provides an interface for the PowerPC family of processors to access 18516 the AltiVec operations described in Motorola's AltiVec Programming 18517 Interface Manual. The interface is made available by including 18518 @code{<altivec.h>} and using @option{-maltivec} and 18519 @option{-mabi=altivec}. The interface supports the following vector 18520 types. 18521 18522 @smallexample 18523 vector unsigned char 18524 vector signed char 18525 vector bool char 18526 18527 vector unsigned short 18528 vector signed short 18529 vector bool short 18530 vector pixel 18531 18532 vector unsigned int 18533 vector signed int 18534 vector bool int 18535 vector float 18536 @end smallexample 18537 18538 GCC's implementation of the high-level language interface available from 18539 C and C++ code differs from Motorola's documentation in several ways. 18540 18541 @itemize @bullet 18542 18543 @item 18544 A vector constant is a list of constant expressions within curly braces. 18545 18546 @item 18547 A vector initializer requires no cast if the vector constant is of the 18548 same type as the variable it is initializing. 18549 18550 @item 18551 If @code{signed} or @code{unsigned} is omitted, the signedness of the 18552 vector type is the default signedness of the base type. The default 18553 varies depending on the operating system, so a portable program should 18554 always specify the signedness. 18555 18556 @item 18557 Compiling with @option{-maltivec} adds keywords @code{__vector}, 18558 @code{vector}, @code{__pixel}, @code{pixel}, @code{__bool} and 18559 @code{bool}. When compiling ISO C, the context-sensitive substitution 18560 of the keywords @code{vector}, @code{pixel} and @code{bool} is 18561 disabled. To use them, you must include @code{<altivec.h>} instead. 18562 18563 @item 18564 GCC allows using a @code{typedef} name as the type specifier for a 18565 vector type, but only under the following circumstances: 18566 18567 @itemize @bullet 18568 18569 @item 18570 When using @code{__vector} instead of @code{vector}; for example, 18571 18572 @smallexample 18573 typedef signed short int16; 18574 __vector int16 data; 18575 @end smallexample 18576 18577 @item 18578 When using @code{vector} in keyword-and-predefine mode; for example, 18579 18580 @smallexample 18581 typedef signed short int16; 18582 vector int16 data; 18583 @end smallexample 18584 18585 Note that keyword-and-predefine mode is enabled by disabling GNU 18586 extensions (e.g., by using @code{-std=c11}) and including 18587 @code{<altivec.h>}. 18588 @end itemize 18589 18590 @item 18591 For C, overloaded functions are implemented with macros so the following 18592 does not work: 18593 18594 @smallexample 18595 vec_add ((vector signed int)@{1, 2, 3, 4@}, foo); 18596 @end smallexample 18597 18598 @noindent 18599 Since @code{vec_add} is a macro, the vector constant in the example 18600 is treated as four separate arguments. Wrap the entire argument in 18601 parentheses for this to work. 18602 @end itemize 18603 18604 @emph{Note:} Only the @code{<altivec.h>} interface is supported. 18605 Internally, GCC uses built-in functions to achieve the functionality in 18606 the aforementioned header file, but they are not supported and are 18607 subject to change without notice. 18608 18609 GCC complies with the Power Vector Intrinsic Programming Reference (PVIPR), 18610 which may be found at 18611 @uref{https://openpowerfoundation.org/?resource_lib=power-vector-intrinsic-programming-reference}. 18612 Chapter 4 of this document fully documents the vector API interfaces 18613 that must be 18614 provided by compliant compilers. Programmers should preferentially use 18615 the interfaces described therein. However, historically GCC has provided 18616 additional interfaces for access to vector instructions. These are 18617 briefly described below. Where the PVIPR provides a portable interface, 18618 other functions in GCC that provide the same capabilities should be 18619 considered deprecated. 18620 18621 The PVIPR documents the following overloaded functions: 18622 18623 @multitable @columnfractions 0.33 0.33 0.33 18624 18625 @item @code{vec_abs} 18626 @tab @code{vec_absd} 18627 @tab @code{vec_abss} 18628 @item @code{vec_add} 18629 @tab @code{vec_addc} 18630 @tab @code{vec_adde} 18631 @item @code{vec_addec} 18632 @tab @code{vec_adds} 18633 @tab @code{vec_all_eq} 18634 @item @code{vec_all_ge} 18635 @tab @code{vec_all_gt} 18636 @tab @code{vec_all_in} 18637 @item @code{vec_all_le} 18638 @tab @code{vec_all_lt} 18639 @tab @code{vec_all_nan} 18640 @item @code{vec_all_ne} 18641 @tab @code{vec_all_nge} 18642 @tab @code{vec_all_ngt} 18643 @item @code{vec_all_nle} 18644 @tab @code{vec_all_nlt} 18645 @tab @code{vec_all_numeric} 18646 @item @code{vec_and} 18647 @tab @code{vec_andc} 18648 @tab @code{vec_any_eq} 18649 @item @code{vec_any_ge} 18650 @tab @code{vec_any_gt} 18651 @tab @code{vec_any_le} 18652 @item @code{vec_any_lt} 18653 @tab @code{vec_any_nan} 18654 @tab @code{vec_any_ne} 18655 @item @code{vec_any_nge} 18656 @tab @code{vec_any_ngt} 18657 @tab @code{vec_any_nle} 18658 @item @code{vec_any_nlt} 18659 @tab @code{vec_any_numeric} 18660 @tab @code{vec_any_out} 18661 @item @code{vec_avg} 18662 @tab @code{vec_bperm} 18663 @tab @code{vec_ceil} 18664 @item @code{vec_cipher_be} 18665 @tab @code{vec_cipherlast_be} 18666 @tab @code{vec_cmpb} 18667 @item @code{vec_cmpeq} 18668 @tab @code{vec_cmpge} 18669 @tab @code{vec_cmpgt} 18670 @item @code{vec_cmple} 18671 @tab @code{vec_cmplt} 18672 @tab @code{vec_cmpne} 18673 @item @code{vec_cmpnez} 18674 @tab @code{vec_cntlz} 18675 @tab @code{vec_cntlz_lsbb} 18676 @item @code{vec_cnttz} 18677 @tab @code{vec_cnttz_lsbb} 18678 @tab @code{vec_cpsgn} 18679 @item @code{vec_ctf} 18680 @tab @code{vec_cts} 18681 @tab @code{vec_ctu} 18682 @item @code{vec_div} 18683 @tab @code{vec_double} 18684 @tab @code{vec_doublee} 18685 @item @code{vec_doubleh} 18686 @tab @code{vec_doublel} 18687 @tab @code{vec_doubleo} 18688 @item @code{vec_eqv} 18689 @tab @code{vec_expte} 18690 @tab @code{vec_extract} 18691 @item @code{vec_extract_exp} 18692 @tab @code{vec_extract_fp32_from_shorth} 18693 @tab @code{vec_extract_fp32_from_shortl} 18694 @item @code{vec_extract_sig} 18695 @tab @code{vec_extract_4b} 18696 @tab @code{vec_first_match_index} 18697 @item @code{vec_first_match_or_eos_index} 18698 @tab @code{vec_first_mismatch_index} 18699 @tab @code{vec_first_mismatch_or_eos_index} 18700 @item @code{vec_float} 18701 @tab @code{vec_float2} 18702 @tab @code{vec_floate} 18703 @item @code{vec_floato} 18704 @tab @code{vec_floor} 18705 @tab @code{vec_gb} 18706 @item @code{vec_insert} 18707 @tab @code{vec_insert_exp} 18708 @tab @code{vec_insert4b} 18709 @item @code{vec_ld} 18710 @tab @code{vec_lde} 18711 @tab @code{vec_ldl} 18712 @item @code{vec_loge} 18713 @tab @code{vec_madd} 18714 @tab @code{vec_madds} 18715 @item @code{vec_max} 18716 @tab @code{vec_mergee} 18717 @tab @code{vec_mergeh} 18718 @item @code{vec_mergel} 18719 @tab @code{vec_mergeo} 18720 @tab @code{vec_mfvscr} 18721 @item @code{vec_min} 18722 @tab @code{vec_mradds} 18723 @tab @code{vec_msub} 18724 @item @code{vec_msum} 18725 @tab @code{vec_msums} 18726 @tab @code{vec_mtvscr} 18727 @item @code{vec_mul} 18728 @tab @code{vec_mule} 18729 @tab @code{vec_mulo} 18730 @item @code{vec_nabs} 18731 @tab @code{vec_nand} 18732 @tab @code{vec_ncipher_be} 18733 @item @code{vec_ncipherlast_be} 18734 @tab @code{vec_nearbyint} 18735 @tab @code{vec_neg} 18736 @item @code{vec_nmadd} 18737 @tab @code{vec_nmsub} 18738 @tab @code{vec_nor} 18739 @item @code{vec_or} 18740 @tab @code{vec_orc} 18741 @tab @code{vec_pack} 18742 @item @code{vec_pack_to_short_fp32} 18743 @tab @code{vec_packpx} 18744 @tab @code{vec_packs} 18745 @item @code{vec_packsu} 18746 @tab @code{vec_parity_lsbb} 18747 @tab @code{vec_perm} 18748 @item @code{vec_permxor} 18749 @tab @code{vec_pmsum_be} 18750 @tab @code{vec_popcnt} 18751 @item @code{vec_re} 18752 @tab @code{vec_recipdiv} 18753 @tab @code{vec_revb} 18754 @item @code{vec_reve} 18755 @tab @code{vec_rint} 18756 @tab @code{vec_rl} 18757 @item @code{vec_rlmi} 18758 @tab @code{vec_rlnm} 18759 @tab @code{vec_round} 18760 @item @code{vec_rsqrt} 18761 @tab @code{vec_rsqrte} 18762 @tab @code{vec_sbox_be} 18763 @item @code{vec_sel} 18764 @tab @code{vec_shasigma_be} 18765 @tab @code{vec_signed} 18766 @item @code{vec_signed2} 18767 @tab @code{vec_signede} 18768 @tab @code{vec_signedo} 18769 @item @code{vec_sl} 18770 @tab @code{vec_sld} 18771 @tab @code{vec_sldw} 18772 @item @code{vec_sll} 18773 @tab @code{vec_slo} 18774 @tab @code{vec_slv} 18775 @item @code{vec_splat} 18776 @tab @code{vec_splat_s8} 18777 @tab @code{vec_splat_s16} 18778 @item @code{vec_splat_s32} 18779 @tab @code{vec_splat_u8} 18780 @tab @code{vec_splat_u16} 18781 @item @code{vec_splat_u32} 18782 @tab @code{vec_splats} 18783 @tab @code{vec_sqrt} 18784 @item @code{vec_sr} 18785 @tab @code{vec_sra} 18786 @tab @code{vec_srl} 18787 @item @code{vec_sro} 18788 @tab @code{vec_srv} 18789 @tab @code{vec_st} 18790 @item @code{vec_ste} 18791 @tab @code{vec_stl} 18792 @tab @code{vec_sub} 18793 @item @code{vec_subc} 18794 @tab @code{vec_sube} 18795 @tab @code{vec_subec} 18796 @item @code{vec_subs} 18797 @tab @code{vec_sum2s} 18798 @tab @code{vec_sum4s} 18799 @item @code{vec_sums} 18800 @tab @code{vec_test_data_class} 18801 @tab @code{vec_trunc} 18802 @item @code{vec_unpackh} 18803 @tab @code{vec_unpackl} 18804 @tab @code{vec_unsigned} 18805 @item @code{vec_unsigned2} 18806 @tab @code{vec_unsignede} 18807 @tab @code{vec_unsignedo} 18808 @item @code{vec_xl} 18809 @tab @code{vec_xl_be} 18810 @tab @code{vec_xl_len} 18811 @item @code{vec_xl_len_r} 18812 @tab @code{vec_xor} 18813 @tab @code{vec_xst} 18814 @item @code{vec_xst_be} 18815 @tab @code{vec_xst_len} 18816 @tab @code{vec_xst_len_r} 18817 18818 @end multitable 18819 18820 @menu 18821 * PowerPC AltiVec Built-in Functions on ISA 2.05:: 18822 * PowerPC AltiVec Built-in Functions Available on ISA 2.06:: 18823 * PowerPC AltiVec Built-in Functions Available on ISA 2.07:: 18824 * PowerPC AltiVec Built-in Functions Available on ISA 3.0:: 18825 * PowerPC AltiVec Built-in Functions Available on ISA 3.1:: 18826 @end menu 18827 18828 @node PowerPC AltiVec Built-in Functions on ISA 2.05 18829 @subsubsection PowerPC AltiVec Built-in Functions on ISA 2.05 18830 18831 The following interfaces are supported for the generic and specific 18832 AltiVec operations and the AltiVec predicates. In cases where there 18833 is a direct mapping between generic and specific operations, only the 18834 generic names are shown here, although the specific operations can also 18835 be used. 18836 18837 Arguments that are documented as @code{const int} require literal 18838 integral values within the range required for that operation. 18839 18840 Only functions excluded from the PVIPR are listed here. 18841 18842 @smallexample 18843 void vec_dss (const int); 18844 18845 void vec_dssall (void); 18846 18847 void vec_dst (const vector unsigned char *, int, const int); 18848 void vec_dst (const vector signed char *, int, const int); 18849 void vec_dst (const vector bool char *, int, const int); 18850 void vec_dst (const vector unsigned short *, int, const int); 18851 void vec_dst (const vector signed short *, int, const int); 18852 void vec_dst (const vector bool short *, int, const int); 18853 void vec_dst (const vector pixel *, int, const int); 18854 void vec_dst (const vector unsigned int *, int, const int); 18855 void vec_dst (const vector signed int *, int, const int); 18856 void vec_dst (const vector bool int *, int, const int); 18857 void vec_dst (const vector float *, int, const int); 18858 void vec_dst (const unsigned char *, int, const int); 18859 void vec_dst (const signed char *, int, const int); 18860 void vec_dst (const unsigned short *, int, const int); 18861 void vec_dst (const short *, int, const int); 18862 void vec_dst (const unsigned int *, int, const int); 18863 void vec_dst (const int *, int, const int); 18864 void vec_dst (const float *, int, const int); 18865 18866 void vec_dstst (const vector unsigned char *, int, const int); 18867 void vec_dstst (const vector signed char *, int, const int); 18868 void vec_dstst (const vector bool char *, int, const int); 18869 void vec_dstst (const vector unsigned short *, int, const int); 18870 void vec_dstst (const vector signed short *, int, const int); 18871 void vec_dstst (const vector bool short *, int, const int); 18872 void vec_dstst (const vector pixel *, int, const int); 18873 void vec_dstst (const vector unsigned int *, int, const int); 18874 void vec_dstst (const vector signed int *, int, const int); 18875 void vec_dstst (const vector bool int *, int, const int); 18876 void vec_dstst (const vector float *, int, const int); 18877 void vec_dstst (const unsigned char *, int, const int); 18878 void vec_dstst (const signed char *, int, const int); 18879 void vec_dstst (const unsigned short *, int, const int); 18880 void vec_dstst (const short *, int, const int); 18881 void vec_dstst (const unsigned int *, int, const int); 18882 void vec_dstst (const int *, int, const int); 18883 void vec_dstst (const unsigned long *, int, const int); 18884 void vec_dstst (const long *, int, const int); 18885 void vec_dstst (const float *, int, const int); 18886 18887 void vec_dststt (const vector unsigned char *, int, const int); 18888 void vec_dststt (const vector signed char *, int, const int); 18889 void vec_dststt (const vector bool char *, int, const int); 18890 void vec_dststt (const vector unsigned short *, int, const int); 18891 void vec_dststt (const vector signed short *, int, const int); 18892 void vec_dststt (const vector bool short *, int, const int); 18893 void vec_dststt (const vector pixel *, int, const int); 18894 void vec_dststt (const vector unsigned int *, int, const int); 18895 void vec_dststt (const vector signed int *, int, const int); 18896 void vec_dststt (const vector bool int *, int, const int); 18897 void vec_dststt (const vector float *, int, const int); 18898 void vec_dststt (const unsigned char *, int, const int); 18899 void vec_dststt (const signed char *, int, const int); 18900 void vec_dststt (const unsigned short *, int, const int); 18901 void vec_dststt (const short *, int, const int); 18902 void vec_dststt (const unsigned int *, int, const int); 18903 void vec_dststt (const int *, int, const int); 18904 void vec_dststt (const float *, int, const int); 18905 18906 void vec_dstt (const vector unsigned char *, int, const int); 18907 void vec_dstt (const vector signed char *, int, const int); 18908 void vec_dstt (const vector bool char *, int, const int); 18909 void vec_dstt (const vector unsigned short *, int, const int); 18910 void vec_dstt (const vector signed short *, int, const int); 18911 void vec_dstt (const vector bool short *, int, const int); 18912 void vec_dstt (const vector pixel *, int, const int); 18913 void vec_dstt (const vector unsigned int *, int, const int); 18914 void vec_dstt (const vector signed int *, int, const int); 18915 void vec_dstt (const vector bool int *, int, const int); 18916 void vec_dstt (const vector float *, int, const int); 18917 void vec_dstt (const unsigned char *, int, const int); 18918 void vec_dstt (const signed char *, int, const int); 18919 void vec_dstt (const unsigned short *, int, const int); 18920 void vec_dstt (const short *, int, const int); 18921 void vec_dstt (const unsigned int *, int, const int); 18922 void vec_dstt (const int *, int, const int); 18923 void vec_dstt (const float *, int, const int); 18924 18925 vector signed char vec_lvebx (int, char *); 18926 vector unsigned char vec_lvebx (int, unsigned char *); 18927 18928 vector signed short vec_lvehx (int, short *); 18929 vector unsigned short vec_lvehx (int, unsigned short *); 18930 18931 vector float vec_lvewx (int, float *); 18932 vector signed int vec_lvewx (int, int *); 18933 vector unsigned int vec_lvewx (int, unsigned int *); 18934 18935 vector unsigned char vec_lvsl (int, const unsigned char *); 18936 vector unsigned char vec_lvsl (int, const signed char *); 18937 vector unsigned char vec_lvsl (int, const unsigned short *); 18938 vector unsigned char vec_lvsl (int, const short *); 18939 vector unsigned char vec_lvsl (int, const unsigned int *); 18940 vector unsigned char vec_lvsl (int, const int *); 18941 vector unsigned char vec_lvsl (int, const float *); 18942 18943 vector unsigned char vec_lvsr (int, const unsigned char *); 18944 vector unsigned char vec_lvsr (int, const signed char *); 18945 vector unsigned char vec_lvsr (int, const unsigned short *); 18946 vector unsigned char vec_lvsr (int, const short *); 18947 vector unsigned char vec_lvsr (int, const unsigned int *); 18948 vector unsigned char vec_lvsr (int, const int *); 18949 vector unsigned char vec_lvsr (int, const float *); 18950 18951 void vec_stvebx (vector signed char, int, signed char *); 18952 void vec_stvebx (vector unsigned char, int, unsigned char *); 18953 void vec_stvebx (vector bool char, int, signed char *); 18954 void vec_stvebx (vector bool char, int, unsigned char *); 18955 18956 void vec_stvehx (vector signed short, int, short *); 18957 void vec_stvehx (vector unsigned short, int, unsigned short *); 18958 void vec_stvehx (vector bool short, int, short *); 18959 void vec_stvehx (vector bool short, int, unsigned short *); 18960 18961 void vec_stvewx (vector float, int, float *); 18962 void vec_stvewx (vector signed int, int, int *); 18963 void vec_stvewx (vector unsigned int, int, unsigned int *); 18964 void vec_stvewx (vector bool int, int, int *); 18965 void vec_stvewx (vector bool int, int, unsigned int *); 18966 18967 vector float vec_vaddfp (vector float, vector float); 18968 18969 vector signed char vec_vaddsbs (vector bool char, vector signed char); 18970 vector signed char vec_vaddsbs (vector signed char, vector bool char); 18971 vector signed char vec_vaddsbs (vector signed char, vector signed char); 18972 18973 vector signed short vec_vaddshs (vector bool short, vector signed short); 18974 vector signed short vec_vaddshs (vector signed short, vector bool short); 18975 vector signed short vec_vaddshs (vector signed short, vector signed short); 18976 18977 vector signed int vec_vaddsws (vector bool int, vector signed int); 18978 vector signed int vec_vaddsws (vector signed int, vector bool int); 18979 vector signed int vec_vaddsws (vector signed int, vector signed int); 18980 18981 vector signed char vec_vaddubm (vector bool char, vector signed char); 18982 vector signed char vec_vaddubm (vector signed char, vector bool char); 18983 vector signed char vec_vaddubm (vector signed char, vector signed char); 18984 vector unsigned char vec_vaddubm (vector bool char, vector unsigned char); 18985 vector unsigned char vec_vaddubm (vector unsigned char, vector bool char); 18986 vector unsigned char vec_vaddubm (vector unsigned char, vector unsigned char); 18987 18988 vector unsigned char vec_vaddubs (vector bool char, vector unsigned char); 18989 vector unsigned char vec_vaddubs (vector unsigned char, vector bool char); 18990 vector unsigned char vec_vaddubs (vector unsigned char, vector unsigned char); 18991 18992 vector signed short vec_vadduhm (vector bool short, vector signed short); 18993 vector signed short vec_vadduhm (vector signed short, vector bool short); 18994 vector signed short vec_vadduhm (vector signed short, vector signed short); 18995 vector unsigned short vec_vadduhm (vector bool short, vector unsigned short); 18996 vector unsigned short vec_vadduhm (vector unsigned short, vector bool short); 18997 vector unsigned short vec_vadduhm (vector unsigned short, vector unsigned short); 18998 18999 vector unsigned short vec_vadduhs (vector bool short, vector unsigned short); 19000 vector unsigned short vec_vadduhs (vector unsigned short, vector bool short); 19001 vector unsigned short vec_vadduhs (vector unsigned short, vector unsigned short); 19002 19003 vector signed int vec_vadduwm (vector bool int, vector signed int); 19004 vector signed int vec_vadduwm (vector signed int, vector bool int); 19005 vector signed int vec_vadduwm (vector signed int, vector signed int); 19006 vector unsigned int vec_vadduwm (vector bool int, vector unsigned int); 19007 vector unsigned int vec_vadduwm (vector unsigned int, vector bool int); 19008 vector unsigned int vec_vadduwm (vector unsigned int, vector unsigned int); 19009 19010 vector unsigned int vec_vadduws (vector bool int, vector unsigned int); 19011 vector unsigned int vec_vadduws (vector unsigned int, vector bool int); 19012 vector unsigned int vec_vadduws (vector unsigned int, vector unsigned int); 19013 19014 vector signed char vec_vavgsb (vector signed char, vector signed char); 19015 19016 vector signed short vec_vavgsh (vector signed short, vector signed short); 19017 19018 vector signed int vec_vavgsw (vector signed int, vector signed int); 19019 19020 vector unsigned char vec_vavgub (vector unsigned char, vector unsigned char); 19021 19022 vector unsigned short vec_vavguh (vector unsigned short, vector unsigned short); 19023 19024 vector unsigned int vec_vavguw (vector unsigned int, vector unsigned int); 19025 19026 vector float vec_vcfsx (vector signed int, const int); 19027 19028 vector float vec_vcfux (vector unsigned int, const int); 19029 19030 vector bool int vec_vcmpeqfp (vector float, vector float); 19031 19032 vector bool char vec_vcmpequb (vector signed char, vector signed char); 19033 vector bool char vec_vcmpequb (vector unsigned char, vector unsigned char); 19034 19035 vector bool short vec_vcmpequh (vector signed short, vector signed short); 19036 vector bool short vec_vcmpequh (vector unsigned short, vector unsigned short); 19037 19038 vector bool int vec_vcmpequw (vector signed int, vector signed int); 19039 vector bool int vec_vcmpequw (vector unsigned int, vector unsigned int); 19040 19041 vector bool int vec_vcmpgtfp (vector float, vector float); 19042 19043 vector bool char vec_vcmpgtsb (vector signed char, vector signed char); 19044 19045 vector bool short vec_vcmpgtsh (vector signed short, vector signed short); 19046 19047 vector bool int vec_vcmpgtsw (vector signed int, vector signed int); 19048 19049 vector bool char vec_vcmpgtub (vector unsigned char, vector unsigned char); 19050 19051 vector bool short vec_vcmpgtuh (vector unsigned short, vector unsigned short); 19052 19053 vector bool int vec_vcmpgtuw (vector unsigned int, vector unsigned int); 19054 19055 vector float vec_vmaxfp (vector float, vector float); 19056 19057 vector signed char vec_vmaxsb (vector bool char, vector signed char); 19058 vector signed char vec_vmaxsb (vector signed char, vector bool char); 19059 vector signed char vec_vmaxsb (vector signed char, vector signed char); 19060 19061 vector signed short vec_vmaxsh (vector bool short, vector signed short); 19062 vector signed short vec_vmaxsh (vector signed short, vector bool short); 19063 vector signed short vec_vmaxsh (vector signed short, vector signed short); 19064 19065 vector signed int vec_vmaxsw (vector bool int, vector signed int); 19066 vector signed int vec_vmaxsw (vector signed int, vector bool int); 19067 vector signed int vec_vmaxsw (vector signed int, vector signed int); 19068 19069 vector unsigned char vec_vmaxub (vector bool char, vector unsigned char); 19070 vector unsigned char vec_vmaxub (vector unsigned char, vector bool char); 19071 vector unsigned char vec_vmaxub (vector unsigned char, vector unsigned char); 19072 19073 vector unsigned short vec_vmaxuh (vector bool short, vector unsigned short); 19074 vector unsigned short vec_vmaxuh (vector unsigned short, vector bool short); 19075 vector unsigned short vec_vmaxuh (vector unsigned short, vector unsigned short); 19076 19077 vector unsigned int vec_vmaxuw (vector bool int, vector unsigned int); 19078 vector unsigned int vec_vmaxuw (vector unsigned int, vector bool int); 19079 vector unsigned int vec_vmaxuw (vector unsigned int, vector unsigned int); 19080 19081 vector float vec_vminfp (vector float, vector float); 19082 19083 vector signed char vec_vminsb (vector bool char, vector signed char); 19084 vector signed char vec_vminsb (vector signed char, vector bool char); 19085 vector signed char vec_vminsb (vector signed char, vector signed char); 19086 19087 vector signed short vec_vminsh (vector bool short, vector signed short); 19088 vector signed short vec_vminsh (vector signed short, vector bool short); 19089 vector signed short vec_vminsh (vector signed short, vector signed short); 19090 19091 vector signed int vec_vminsw (vector bool int, vector signed int); 19092 vector signed int vec_vminsw (vector signed int, vector bool int); 19093 vector signed int vec_vminsw (vector signed int, vector signed int); 19094 19095 vector unsigned char vec_vminub (vector bool char, vector unsigned char); 19096 vector unsigned char vec_vminub (vector unsigned char, vector bool char); 19097 vector unsigned char vec_vminub (vector unsigned char, vector unsigned char); 19098 19099 vector unsigned short vec_vminuh (vector bool short, vector unsigned short); 19100 vector unsigned short vec_vminuh (vector unsigned short, vector bool short); 19101 vector unsigned short vec_vminuh (vector unsigned short, vector unsigned short); 19102 19103 vector unsigned int vec_vminuw (vector bool int, vector unsigned int); 19104 vector unsigned int vec_vminuw (vector unsigned int, vector bool int); 19105 vector unsigned int vec_vminuw (vector unsigned int, vector unsigned int); 19106 19107 vector bool char vec_vmrghb (vector bool char, vector bool char); 19108 vector signed char vec_vmrghb (vector signed char, vector signed char); 19109 vector unsigned char vec_vmrghb (vector unsigned char, vector unsigned char); 19110 19111 vector bool short vec_vmrghh (vector bool short, vector bool short); 19112 vector signed short vec_vmrghh (vector signed short, vector signed short); 19113 vector unsigned short vec_vmrghh (vector unsigned short, vector unsigned short); 19114 vector pixel vec_vmrghh (vector pixel, vector pixel); 19115 19116 vector float vec_vmrghw (vector float, vector float); 19117 vector bool int vec_vmrghw (vector bool int, vector bool int); 19118 vector signed int vec_vmrghw (vector signed int, vector signed int); 19119 vector unsigned int vec_vmrghw (vector unsigned int, vector unsigned int); 19120 19121 vector bool char vec_vmrglb (vector bool char, vector bool char); 19122 vector signed char vec_vmrglb (vector signed char, vector signed char); 19123 vector unsigned char vec_vmrglb (vector unsigned char, vector unsigned char); 19124 19125 vector bool short vec_vmrglh (vector bool short, vector bool short); 19126 vector signed short vec_vmrglh (vector signed short, vector signed short); 19127 vector unsigned short vec_vmrglh (vector unsigned short, vector unsigned short); 19128 vector pixel vec_vmrglh (vector pixel, vector pixel); 19129 19130 vector float vec_vmrglw (vector float, vector float); 19131 vector signed int vec_vmrglw (vector signed int, vector signed int); 19132 vector unsigned int vec_vmrglw (vector unsigned int, vector unsigned int); 19133 vector bool int vec_vmrglw (vector bool int, vector bool int); 19134 19135 vector signed int vec_vmsummbm (vector signed char, vector unsigned char, 19136 vector signed int); 19137 19138 vector signed int vec_vmsumshm (vector signed short, vector signed short, 19139 vector signed int); 19140 19141 vector signed int vec_vmsumshs (vector signed short, vector signed short, 19142 vector signed int); 19143 19144 vector unsigned int vec_vmsumubm (vector unsigned char, vector unsigned char, 19145 vector unsigned int); 19146 19147 vector unsigned int vec_vmsumuhm (vector unsigned short, vector unsigned short, 19148 vector unsigned int); 19149 19150 vector unsigned int vec_vmsumuhs (vector unsigned short, vector unsigned short, 19151 vector unsigned int); 19152 19153 vector signed short vec_vmulesb (vector signed char, vector signed char); 19154 19155 vector signed int vec_vmulesh (vector signed short, vector signed short); 19156 19157 vector unsigned short vec_vmuleub (vector unsigned char, vector unsigned char); 19158 19159 vector unsigned int vec_vmuleuh (vector unsigned short, vector unsigned short); 19160 19161 vector signed short vec_vmulosb (vector signed char, vector signed char); 19162 19163 vector signed int vec_vmulosh (vector signed short, vector signed short); 19164 19165 vector unsigned short vec_vmuloub (vector unsigned char, vector unsigned char); 19166 19167 vector unsigned int vec_vmulouh (vector unsigned short, vector unsigned short); 19168 19169 vector signed char vec_vpkshss (vector signed short, vector signed short); 19170 19171 vector unsigned char vec_vpkshus (vector signed short, vector signed short); 19172 19173 vector signed short vec_vpkswss (vector signed int, vector signed int); 19174 19175 vector unsigned short vec_vpkswus (vector signed int, vector signed int); 19176 19177 vector bool char vec_vpkuhum (vector bool short, vector bool short); 19178 vector signed char vec_vpkuhum (vector signed short, vector signed short); 19179 vector unsigned char vec_vpkuhum (vector unsigned short, vector unsigned short); 19180 19181 vector unsigned char vec_vpkuhus (vector unsigned short, vector unsigned short); 19182 19183 vector bool short vec_vpkuwum (vector bool int, vector bool int); 19184 vector signed short vec_vpkuwum (vector signed int, vector signed int); 19185 vector unsigned short vec_vpkuwum (vector unsigned int, vector unsigned int); 19186 19187 vector unsigned short vec_vpkuwus (vector unsigned int, vector unsigned int); 19188 19189 vector signed char vec_vrlb (vector signed char, vector unsigned char); 19190 vector unsigned char vec_vrlb (vector unsigned char, vector unsigned char); 19191 19192 vector signed short vec_vrlh (vector signed short, vector unsigned short); 19193 vector unsigned short vec_vrlh (vector unsigned short, vector unsigned short); 19194 19195 vector signed int vec_vrlw (vector signed int, vector unsigned int); 19196 vector unsigned int vec_vrlw (vector unsigned int, vector unsigned int); 19197 19198 vector signed char vec_vslb (vector signed char, vector unsigned char); 19199 vector unsigned char vec_vslb (vector unsigned char, vector unsigned char); 19200 19201 vector signed short vec_vslh (vector signed short, vector unsigned short); 19202 vector unsigned short vec_vslh (vector unsigned short, vector unsigned short); 19203 19204 vector signed int vec_vslw (vector signed int, vector unsigned int); 19205 vector unsigned int vec_vslw (vector unsigned int, vector unsigned int); 19206 19207 vector signed char vec_vspltb (vector signed char, const int); 19208 vector unsigned char vec_vspltb (vector unsigned char, const int); 19209 vector bool char vec_vspltb (vector bool char, const int); 19210 19211 vector bool short vec_vsplth (vector bool short, const int); 19212 vector signed short vec_vsplth (vector signed short, const int); 19213 vector unsigned short vec_vsplth (vector unsigned short, const int); 19214 vector pixel vec_vsplth (vector pixel, const int); 19215 19216 vector float vec_vspltw (vector float, const int); 19217 vector signed int vec_vspltw (vector signed int, const int); 19218 vector unsigned int vec_vspltw (vector unsigned int, const int); 19219 vector bool int vec_vspltw (vector bool int, const int); 19220 19221 vector signed char vec_vsrab (vector signed char, vector unsigned char); 19222 vector unsigned char vec_vsrab (vector unsigned char, vector unsigned char); 19223 19224 vector signed short vec_vsrah (vector signed short, vector unsigned short); 19225 vector unsigned short vec_vsrah (vector unsigned short, vector unsigned short); 19226 19227 vector signed int vec_vsraw (vector signed int, vector unsigned int); 19228 vector unsigned int vec_vsraw (vector unsigned int, vector unsigned int); 19229 19230 vector signed char vec_vsrb (vector signed char, vector unsigned char); 19231 vector unsigned char vec_vsrb (vector unsigned char, vector unsigned char); 19232 19233 vector signed short vec_vsrh (vector signed short, vector unsigned short); 19234 vector unsigned short vec_vsrh (vector unsigned short, vector unsigned short); 19235 19236 vector signed int vec_vsrw (vector signed int, vector unsigned int); 19237 vector unsigned int vec_vsrw (vector unsigned int, vector unsigned int); 19238 19239 vector float vec_vsubfp (vector float, vector float); 19240 19241 vector signed char vec_vsubsbs (vector bool char, vector signed char); 19242 vector signed char vec_vsubsbs (vector signed char, vector bool char); 19243 vector signed char vec_vsubsbs (vector signed char, vector signed char); 19244 19245 vector signed short vec_vsubshs (vector bool short, vector signed short); 19246 vector signed short vec_vsubshs (vector signed short, vector bool short); 19247 vector signed short vec_vsubshs (vector signed short, vector signed short); 19248 19249 vector signed int vec_vsubsws (vector bool int, vector signed int); 19250 vector signed int vec_vsubsws (vector signed int, vector bool int); 19251 vector signed int vec_vsubsws (vector signed int, vector signed int); 19252 19253 vector signed char vec_vsububm (vector bool char, vector signed char); 19254 vector signed char vec_vsububm (vector signed char, vector bool char); 19255 vector signed char vec_vsububm (vector signed char, vector signed char); 19256 vector unsigned char vec_vsububm (vector bool char, vector unsigned char); 19257 vector unsigned char vec_vsububm (vector unsigned char, vector bool char); 19258 vector unsigned char vec_vsububm (vector unsigned char, vector unsigned char); 19259 19260 vector unsigned char vec_vsububs (vector bool char, vector unsigned char); 19261 vector unsigned char vec_vsububs (vector unsigned char, vector bool char); 19262 vector unsigned char vec_vsububs (vector unsigned char, vector unsigned char); 19263 19264 vector signed short vec_vsubuhm (vector bool short, vector signed short); 19265 vector signed short vec_vsubuhm (vector signed short, vector bool short); 19266 vector signed short vec_vsubuhm (vector signed short, vector signed short); 19267 vector unsigned short vec_vsubuhm (vector bool short, vector unsigned short); 19268 vector unsigned short vec_vsubuhm (vector unsigned short, vector bool short); 19269 vector unsigned short vec_vsubuhm (vector unsigned short, vector unsigned short); 19270 19271 vector unsigned short vec_vsubuhs (vector bool short, vector unsigned short); 19272 vector unsigned short vec_vsubuhs (vector unsigned short, vector bool short); 19273 vector unsigned short vec_vsubuhs (vector unsigned short, vector unsigned short); 19274 19275 vector signed int vec_vsubuwm (vector bool int, vector signed int); 19276 vector signed int vec_vsubuwm (vector signed int, vector bool int); 19277 vector signed int vec_vsubuwm (vector signed int, vector signed int); 19278 vector unsigned int vec_vsubuwm (vector bool int, vector unsigned int); 19279 vector unsigned int vec_vsubuwm (vector unsigned int, vector bool int); 19280 vector unsigned int vec_vsubuwm (vector unsigned int, vector unsigned int); 19281 19282 vector unsigned int vec_vsubuws (vector bool int, vector unsigned int); 19283 vector unsigned int vec_vsubuws (vector unsigned int, vector bool int); 19284 vector unsigned int vec_vsubuws (vector unsigned int, vector unsigned int); 19285 19286 vector signed int vec_vsum4sbs (vector signed char, vector signed int); 19287 19288 vector signed int vec_vsum4shs (vector signed short, vector signed int); 19289 19290 vector unsigned int vec_vsum4ubs (vector unsigned char, vector unsigned int); 19291 19292 vector unsigned int vec_vupkhpx (vector pixel); 19293 19294 vector bool short vec_vupkhsb (vector bool char); 19295 vector signed short vec_vupkhsb (vector signed char); 19296 19297 vector bool int vec_vupkhsh (vector bool short); 19298 vector signed int vec_vupkhsh (vector signed short); 19299 19300 vector unsigned int vec_vupklpx (vector pixel); 19301 19302 vector bool short vec_vupklsb (vector bool char); 19303 vector signed short vec_vupklsb (vector signed char); 19304 19305 vector bool int vec_vupklsh (vector bool short); 19306 vector signed int vec_vupklsh (vector signed short); 19307 @end smallexample 19308 19309 @node PowerPC AltiVec Built-in Functions Available on ISA 2.06 19310 @subsubsection PowerPC AltiVec Built-in Functions Available on ISA 2.06 19311 19312 The AltiVec built-in functions described in this section are 19313 available on the PowerPC family of processors starting with ISA 2.06 19314 or later. These are normally enabled by adding @option{-mvsx} to the 19315 command line. 19316 19317 When @option{-mvsx} is used, the following additional vector types are 19318 implemented. 19319 19320 @smallexample 19321 vector unsigned __int128 19322 vector signed __int128 19323 vector unsigned long long int 19324 vector signed long long int 19325 vector double 19326 @end smallexample 19327 19328 The long long types are only implemented for 64-bit code generation. 19329 19330 Only functions excluded from the PVIPR are listed here. 19331 19332 @smallexample 19333 void vec_dst (const unsigned long *, int, const int); 19334 void vec_dst (const long *, int, const int); 19335 19336 void vec_dststt (const unsigned long *, int, const int); 19337 void vec_dststt (const long *, int, const int); 19338 19339 void vec_dstt (const unsigned long *, int, const int); 19340 void vec_dstt (const long *, int, const int); 19341 19342 vector unsigned char vec_lvsl (int, const unsigned long *); 19343 vector unsigned char vec_lvsl (int, const long *); 19344 19345 vector unsigned char vec_lvsr (int, const unsigned long *); 19346 vector unsigned char vec_lvsr (int, const long *); 19347 19348 vector unsigned char vec_lvsl (int, const double *); 19349 vector unsigned char vec_lvsr (int, const double *); 19350 19351 vector double vec_vsx_ld (int, const vector double *); 19352 vector double vec_vsx_ld (int, const double *); 19353 vector float vec_vsx_ld (int, const vector float *); 19354 vector float vec_vsx_ld (int, const float *); 19355 vector bool int vec_vsx_ld (int, const vector bool int *); 19356 vector signed int vec_vsx_ld (int, const vector signed int *); 19357 vector signed int vec_vsx_ld (int, const int *); 19358 vector signed int vec_vsx_ld (int, const long *); 19359 vector unsigned int vec_vsx_ld (int, const vector unsigned int *); 19360 vector unsigned int vec_vsx_ld (int, const unsigned int *); 19361 vector unsigned int vec_vsx_ld (int, const unsigned long *); 19362 vector bool short vec_vsx_ld (int, const vector bool short *); 19363 vector pixel vec_vsx_ld (int, const vector pixel *); 19364 vector signed short vec_vsx_ld (int, const vector signed short *); 19365 vector signed short vec_vsx_ld (int, const short *); 19366 vector unsigned short vec_vsx_ld (int, const vector unsigned short *); 19367 vector unsigned short vec_vsx_ld (int, const unsigned short *); 19368 vector bool char vec_vsx_ld (int, const vector bool char *); 19369 vector signed char vec_vsx_ld (int, const vector signed char *); 19370 vector signed char vec_vsx_ld (int, const signed char *); 19371 vector unsigned char vec_vsx_ld (int, const vector unsigned char *); 19372 vector unsigned char vec_vsx_ld (int, const unsigned char *); 19373 19374 void vec_vsx_st (vector double, int, vector double *); 19375 void vec_vsx_st (vector double, int, double *); 19376 void vec_vsx_st (vector float, int, vector float *); 19377 void vec_vsx_st (vector float, int, float *); 19378 void vec_vsx_st (vector signed int, int, vector signed int *); 19379 void vec_vsx_st (vector signed int, int, int *); 19380 void vec_vsx_st (vector unsigned int, int, vector unsigned int *); 19381 void vec_vsx_st (vector unsigned int, int, unsigned int *); 19382 void vec_vsx_st (vector bool int, int, vector bool int *); 19383 void vec_vsx_st (vector bool int, int, unsigned int *); 19384 void vec_vsx_st (vector bool int, int, int *); 19385 void vec_vsx_st (vector signed short, int, vector signed short *); 19386 void vec_vsx_st (vector signed short, int, short *); 19387 void vec_vsx_st (vector unsigned short, int, vector unsigned short *); 19388 void vec_vsx_st (vector unsigned short, int, unsigned short *); 19389 void vec_vsx_st (vector bool short, int, vector bool short *); 19390 void vec_vsx_st (vector bool short, int, unsigned short *); 19391 void vec_vsx_st (vector pixel, int, vector pixel *); 19392 void vec_vsx_st (vector pixel, int, unsigned short *); 19393 void vec_vsx_st (vector pixel, int, short *); 19394 void vec_vsx_st (vector bool short, int, short *); 19395 void vec_vsx_st (vector signed char, int, vector signed char *); 19396 void vec_vsx_st (vector signed char, int, signed char *); 19397 void vec_vsx_st (vector unsigned char, int, vector unsigned char *); 19398 void vec_vsx_st (vector unsigned char, int, unsigned char *); 19399 void vec_vsx_st (vector bool char, int, vector bool char *); 19400 void vec_vsx_st (vector bool char, int, unsigned char *); 19401 void vec_vsx_st (vector bool char, int, signed char *); 19402 19403 vector double vec_xxpermdi (vector double, vector double, const int); 19404 vector float vec_xxpermdi (vector float, vector float, const int); 19405 vector long long vec_xxpermdi (vector long long, vector long long, const int); 19406 vector unsigned long long vec_xxpermdi (vector unsigned long long, 19407 vector unsigned long long, const int); 19408 vector int vec_xxpermdi (vector int, vector int, const int); 19409 vector unsigned int vec_xxpermdi (vector unsigned int, 19410 vector unsigned int, const int); 19411 vector short vec_xxpermdi (vector short, vector short, const int); 19412 vector unsigned short vec_xxpermdi (vector unsigned short, 19413 vector unsigned short, const int); 19414 vector signed char vec_xxpermdi (vector signed char, vector signed char, 19415 const int); 19416 vector unsigned char vec_xxpermdi (vector unsigned char, 19417 vector unsigned char, const int); 19418 19419 vector double vec_xxsldi (vector double, vector double, int); 19420 vector float vec_xxsldi (vector float, vector float, int); 19421 vector long long vec_xxsldi (vector long long, vector long long, int); 19422 vector unsigned long long vec_xxsldi (vector unsigned long long, 19423 vector unsigned long long, int); 19424 vector int vec_xxsldi (vector int, vector int, int); 19425 vector unsigned int vec_xxsldi (vector unsigned int, vector unsigned int, int); 19426 vector short vec_xxsldi (vector short, vector short, int); 19427 vector unsigned short vec_xxsldi (vector unsigned short, 19428 vector unsigned short, int); 19429 vector signed char vec_xxsldi (vector signed char, vector signed char, int); 19430 vector unsigned char vec_xxsldi (vector unsigned char, 19431 vector unsigned char, int); 19432 @end smallexample 19433 19434 Note that the @samp{vec_ld} and @samp{vec_st} built-in functions always 19435 generate the AltiVec @samp{LVX} and @samp{STVX} instructions even 19436 if the VSX instruction set is available. The @samp{vec_vsx_ld} and 19437 @samp{vec_vsx_st} built-in functions always generate the VSX @samp{LXVD2X}, 19438 @samp{LXVW4X}, @samp{STXVD2X}, and @samp{STXVW4X} instructions. 19439 19440 @node PowerPC AltiVec Built-in Functions Available on ISA 2.07 19441 @subsubsection PowerPC AltiVec Built-in Functions Available on ISA 2.07 19442 19443 If the ISA 2.07 additions to the vector/scalar (power8-vector) 19444 instruction set are available, the following additional functions are 19445 available for both 32-bit and 64-bit targets. For 64-bit targets, you 19446 can use @var{vector long} instead of @var{vector long long}, 19447 @var{vector bool long} instead of @var{vector bool long long}, and 19448 @var{vector unsigned long} instead of @var{vector unsigned long long}. 19449 19450 Only functions excluded from the PVIPR are listed here. 19451 19452 @smallexample 19453 vector long long vec_vaddudm (vector long long, vector long long); 19454 vector long long vec_vaddudm (vector bool long long, vector long long); 19455 vector long long vec_vaddudm (vector long long, vector bool long long); 19456 vector unsigned long long vec_vaddudm (vector unsigned long long, 19457 vector unsigned long long); 19458 vector unsigned long long vec_vaddudm (vector bool unsigned long long, 19459 vector unsigned long long); 19460 vector unsigned long long vec_vaddudm (vector unsigned long long, 19461 vector bool unsigned long long); 19462 19463 vector long long vec_vclz (vector long long); 19464 vector unsigned long long vec_vclz (vector unsigned long long); 19465 vector int vec_vclz (vector int); 19466 vector unsigned int vec_vclz (vector int); 19467 vector short vec_vclz (vector short); 19468 vector unsigned short vec_vclz (vector unsigned short); 19469 vector signed char vec_vclz (vector signed char); 19470 vector unsigned char vec_vclz (vector unsigned char); 19471 19472 vector signed char vec_vclzb (vector signed char); 19473 vector unsigned char vec_vclzb (vector unsigned char); 19474 19475 vector long long vec_vclzd (vector long long); 19476 vector unsigned long long vec_vclzd (vector unsigned long long); 19477 19478 vector short vec_vclzh (vector short); 19479 vector unsigned short vec_vclzh (vector unsigned short); 19480 19481 vector int vec_vclzw (vector int); 19482 vector unsigned int vec_vclzw (vector int); 19483 19484 vector signed char vec_vgbbd (vector signed char); 19485 vector unsigned char vec_vgbbd (vector unsigned char); 19486 19487 vector long long vec_vmaxsd (vector long long, vector long long); 19488 19489 vector unsigned long long vec_vmaxud (vector unsigned long long, 19490 unsigned vector long long); 19491 19492 vector long long vec_vminsd (vector long long, vector long long); 19493 19494 vector unsigned long long vec_vminud (vector long long, vector long long); 19495 19496 vector int vec_vpksdss (vector long long, vector long long); 19497 vector unsigned int vec_vpksdss (vector long long, vector long long); 19498 19499 vector unsigned int vec_vpkudus (vector unsigned long long, 19500 vector unsigned long long); 19501 19502 vector int vec_vpkudum (vector long long, vector long long); 19503 vector unsigned int vec_vpkudum (vector unsigned long long, 19504 vector unsigned long long); 19505 vector bool int vec_vpkudum (vector bool long long, vector bool long long); 19506 19507 vector long long vec_vpopcnt (vector long long); 19508 vector unsigned long long vec_vpopcnt (vector unsigned long long); 19509 vector int vec_vpopcnt (vector int); 19510 vector unsigned int vec_vpopcnt (vector int); 19511 vector short vec_vpopcnt (vector short); 19512 vector unsigned short vec_vpopcnt (vector unsigned short); 19513 vector signed char vec_vpopcnt (vector signed char); 19514 vector unsigned char vec_vpopcnt (vector unsigned char); 19515 19516 vector signed char vec_vpopcntb (vector signed char); 19517 vector unsigned char vec_vpopcntb (vector unsigned char); 19518 19519 vector long long vec_vpopcntd (vector long long); 19520 vector unsigned long long vec_vpopcntd (vector unsigned long long); 19521 19522 vector short vec_vpopcnth (vector short); 19523 vector unsigned short vec_vpopcnth (vector unsigned short); 19524 19525 vector int vec_vpopcntw (vector int); 19526 vector unsigned int vec_vpopcntw (vector int); 19527 19528 vector long long vec_vrld (vector long long, vector unsigned long long); 19529 vector unsigned long long vec_vrld (vector unsigned long long, 19530 vector unsigned long long); 19531 19532 vector long long vec_vsld (vector long long, vector unsigned long long); 19533 vector long long vec_vsld (vector unsigned long long, 19534 vector unsigned long long); 19535 19536 vector long long vec_vsrad (vector long long, vector unsigned long long); 19537 vector unsigned long long vec_vsrad (vector unsigned long long, 19538 vector unsigned long long); 19539 19540 vector long long vec_vsrd (vector long long, vector unsigned long long); 19541 vector unsigned long long char vec_vsrd (vector unsigned long long, 19542 vector unsigned long long); 19543 19544 vector long long vec_vsubudm (vector long long, vector long long); 19545 vector long long vec_vsubudm (vector bool long long, vector long long); 19546 vector long long vec_vsubudm (vector long long, vector bool long long); 19547 vector unsigned long long vec_vsubudm (vector unsigned long long, 19548 vector unsigned long long); 19549 vector unsigned long long vec_vsubudm (vector bool long long, 19550 vector unsigned long long); 19551 vector unsigned long long vec_vsubudm (vector unsigned long long, 19552 vector bool long long); 19553 19554 vector long long vec_vupkhsw (vector int); 19555 vector unsigned long long vec_vupkhsw (vector unsigned int); 19556 19557 vector long long vec_vupklsw (vector int); 19558 vector unsigned long long vec_vupklsw (vector int); 19559 @end smallexample 19560 19561 If the ISA 2.07 additions to the vector/scalar (power8-vector) 19562 instruction set are available, the following additional functions are 19563 available for 64-bit targets. New vector types 19564 (@var{vector __int128} and @var{vector __uint128}) are available 19565 to hold the @var{__int128} and @var{__uint128} types to use these 19566 builtins. 19567 19568 The normal vector extract, and set operations work on 19569 @var{vector __int128} and @var{vector __uint128} types, 19570 but the index value must be 0. 19571 19572 Only functions excluded from the PVIPR are listed here. 19573 19574 @smallexample 19575 vector __int128 vec_vaddcuq (vector __int128, vector __int128); 19576 vector __uint128 vec_vaddcuq (vector __uint128, vector __uint128); 19577 19578 vector __int128 vec_vadduqm (vector __int128, vector __int128); 19579 vector __uint128 vec_vadduqm (vector __uint128, vector __uint128); 19580 19581 vector __int128 vec_vaddecuq (vector __int128, vector __int128, 19582 vector __int128); 19583 vector __uint128 vec_vaddecuq (vector __uint128, vector __uint128, 19584 vector __uint128); 19585 19586 vector __int128 vec_vaddeuqm (vector __int128, vector __int128, 19587 vector __int128); 19588 vector __uint128 vec_vaddeuqm (vector __uint128, vector __uint128, 19589 vector __uint128); 19590 19591 vector __int128 vec_vsubecuq (vector __int128, vector __int128, 19592 vector __int128); 19593 vector __uint128 vec_vsubecuq (vector __uint128, vector __uint128, 19594 vector __uint128); 19595 19596 vector __int128 vec_vsubeuqm (vector __int128, vector __int128, 19597 vector __int128); 19598 vector __uint128 vec_vsubeuqm (vector __uint128, vector __uint128, 19599 vector __uint128); 19600 19601 vector __int128 vec_vsubcuq (vector __int128, vector __int128); 19602 vector __uint128 vec_vsubcuq (vector __uint128, vector __uint128); 19603 19604 __int128 vec_vsubuqm (__int128, __int128); 19605 __uint128 vec_vsubuqm (__uint128, __uint128); 19606 19607 vector __int128 __builtin_bcdadd (vector __int128, vector __int128, const int); 19608 vector unsigned char __builtin_bcdadd (vector unsigned char, vector unsigned char, 19609 const int); 19610 int __builtin_bcdadd_lt (vector __int128, vector __int128, const int); 19611 int __builtin_bcdadd_lt (vector unsigned char, vector unsigned char, const int); 19612 int __builtin_bcdadd_eq (vector __int128, vector __int128, const int); 19613 int __builtin_bcdadd_eq (vector unsigned char, vector unsigned char, const int); 19614 int __builtin_bcdadd_gt (vector __int128, vector __int128, const int); 19615 int __builtin_bcdadd_gt (vector unsigned char, vector unsigned char, const int); 19616 int __builtin_bcdadd_ov (vector __int128, vector __int128, const int); 19617 int __builtin_bcdadd_ov (vector unsigned char, vector unsigned char, const int); 19618 19619 vector __int128 __builtin_bcdsub (vector __int128, vector __int128, const int); 19620 vector unsigned char __builtin_bcdsub (vector unsigned char, vector unsigned char, 19621 const int); 19622 int __builtin_bcdsub_lt (vector __int128, vector __int128, const int); 19623 int __builtin_bcdsub_lt (vector unsigned char, vector unsigned char, const int); 19624 int __builtin_bcdsub_eq (vector __int128, vector __int128, const int); 19625 int __builtin_bcdsub_eq (vector unsigned char, vector unsigned char, const int); 19626 int __builtin_bcdsub_gt (vector __int128, vector __int128, const int); 19627 int __builtin_bcdsub_gt (vector unsigned char, vector unsigned char, const int); 19628 int __builtin_bcdsub_ov (vector __int128, vector __int128, const int); 19629 int __builtin_bcdsub_ov (vector unsigned char, vector unsigned char, const int); 19630 @end smallexample 19631 19632 @node PowerPC AltiVec Built-in Functions Available on ISA 3.0 19633 @subsubsection PowerPC AltiVec Built-in Functions Available on ISA 3.0 19634 19635 The following additional built-in functions are also available for the 19636 PowerPC family of processors, starting with ISA 3.0 19637 (@option{-mcpu=power9}) or later. 19638 19639 Only instructions excluded from the PVIPR are listed here. 19640 19641 @smallexample 19642 unsigned int scalar_extract_exp (double source); 19643 unsigned long long int scalar_extract_exp (__ieee128 source); 19644 19645 unsigned long long int scalar_extract_sig (double source); 19646 unsigned __int128 scalar_extract_sig (__ieee128 source); 19647 19648 double scalar_insert_exp (unsigned long long int significand, 19649 unsigned long long int exponent); 19650 double scalar_insert_exp (double significand, unsigned long long int exponent); 19651 19652 ieee_128 scalar_insert_exp (unsigned __int128 significand, 19653 unsigned long long int exponent); 19654 ieee_128 scalar_insert_exp (ieee_128 significand, unsigned long long int exponent); 19655 19656 int scalar_cmp_exp_gt (double arg1, double arg2); 19657 int scalar_cmp_exp_lt (double arg1, double arg2); 19658 int scalar_cmp_exp_eq (double arg1, double arg2); 19659 int scalar_cmp_exp_unordered (double arg1, double arg2); 19660 19661 bool scalar_test_data_class (float source, const int condition); 19662 bool scalar_test_data_class (double source, const int condition); 19663 bool scalar_test_data_class (__ieee128 source, const int condition); 19664 19665 bool scalar_test_neg (float source); 19666 bool scalar_test_neg (double source); 19667 bool scalar_test_neg (__ieee128 source); 19668 @end smallexample 19669 19670 The @code{scalar_extract_exp} and @code{scalar_extract_sig} 19671 functions require a 64-bit environment supporting ISA 3.0 or later. 19672 The @code{scalar_extract_exp} and @code{scalar_extract_sig} built-in 19673 functions return the significand and the biased exponent value 19674 respectively of their @code{source} arguments. 19675 When supplied with a 64-bit @code{source} argument, the 19676 result returned by @code{scalar_extract_sig} has 19677 the @code{0x0010000000000000} bit set if the 19678 function's @code{source} argument is in normalized form. 19679 Otherwise, this bit is set to 0. 19680 When supplied with a 128-bit @code{source} argument, the 19681 @code{0x00010000000000000000000000000000} bit of the result is 19682 treated similarly. 19683 Note that the sign of the significand is not represented in the result 19684 returned from the @code{scalar_extract_sig} function. Use the 19685 @code{scalar_test_neg} function to test the sign of its @code{double} 19686 argument. 19687 19688 The @code{scalar_insert_exp} 19689 functions require a 64-bit environment supporting ISA 3.0 or later. 19690 When supplied with a 64-bit first argument, the 19691 @code{scalar_insert_exp} built-in function returns a double-precision 19692 floating point value that is constructed by assembling the values of its 19693 @code{significand} and @code{exponent} arguments. The sign of the 19694 result is copied from the most significant bit of the 19695 @code{significand} argument. The significand and exponent components 19696 of the result are composed of the least significant 11 bits of the 19697 @code{exponent} argument and the least significant 52 bits of the 19698 @code{significand} argument respectively. 19699 19700 When supplied with a 128-bit first argument, the 19701 @code{scalar_insert_exp} built-in function returns a quad-precision 19702 ieee floating point value. The sign bit of the result is copied from 19703 the most significant bit of the @code{significand} argument. 19704 The significand and exponent components of the result are composed of 19705 the least significant 15 bits of the @code{exponent} argument and the 19706 least significant 112 bits of the @code{significand} argument respectively. 19707 19708 The @code{scalar_cmp_exp_gt}, @code{scalar_cmp_exp_lt}, 19709 @code{scalar_cmp_exp_eq}, and @code{scalar_cmp_exp_unordered} built-in 19710 functions return a non-zero value if @code{arg1} is greater than, less 19711 than, equal to, or not comparable to @code{arg2} respectively. The 19712 arguments are not comparable if one or the other equals NaN (not a 19713 number). 19714 19715 The @code{scalar_test_data_class} built-in function returns 1 19716 if any of the condition tests enabled by the value of the 19717 @code{condition} variable are true, and 0 otherwise. The 19718 @code{condition} argument must be a compile-time constant integer with 19719 value not exceeding 127. The 19720 @code{condition} argument is encoded as a bitmask with each bit 19721 enabling the testing of a different condition, as characterized by the 19722 following: 19723 @smallexample 19724 0x40 Test for NaN 19725 0x20 Test for +Infinity 19726 0x10 Test for -Infinity 19727 0x08 Test for +Zero 19728 0x04 Test for -Zero 19729 0x02 Test for +Denormal 19730 0x01 Test for -Denormal 19731 @end smallexample 19732 19733 The @code{scalar_test_neg} built-in function returns 1 if its 19734 @code{source} argument holds a negative value, 0 otherwise. 19735 19736 The following built-in functions are also available for the PowerPC family 19737 of processors, starting with ISA 3.0 or later 19738 (@option{-mcpu=power9}). These string functions are described 19739 separately in order to group the descriptions closer to the function 19740 prototypes. 19741 19742 Only functions excluded from the PVIPR are listed here. 19743 19744 @smallexample 19745 int vec_all_nez (vector signed char, vector signed char); 19746 int vec_all_nez (vector unsigned char, vector unsigned char); 19747 int vec_all_nez (vector signed short, vector signed short); 19748 int vec_all_nez (vector unsigned short, vector unsigned short); 19749 int vec_all_nez (vector signed int, vector signed int); 19750 int vec_all_nez (vector unsigned int, vector unsigned int); 19751 19752 int vec_any_eqz (vector signed char, vector signed char); 19753 int vec_any_eqz (vector unsigned char, vector unsigned char); 19754 int vec_any_eqz (vector signed short, vector signed short); 19755 int vec_any_eqz (vector unsigned short, vector unsigned short); 19756 int vec_any_eqz (vector signed int, vector signed int); 19757 int vec_any_eqz (vector unsigned int, vector unsigned int); 19758 19759 signed char vec_xlx (unsigned int index, vector signed char data); 19760 unsigned char vec_xlx (unsigned int index, vector unsigned char data); 19761 signed short vec_xlx (unsigned int index, vector signed short data); 19762 unsigned short vec_xlx (unsigned int index, vector unsigned short data); 19763 signed int vec_xlx (unsigned int index, vector signed int data); 19764 unsigned int vec_xlx (unsigned int index, vector unsigned int data); 19765 float vec_xlx (unsigned int index, vector float data); 19766 19767 signed char vec_xrx (unsigned int index, vector signed char data); 19768 unsigned char vec_xrx (unsigned int index, vector unsigned char data); 19769 signed short vec_xrx (unsigned int index, vector signed short data); 19770 unsigned short vec_xrx (unsigned int index, vector unsigned short data); 19771 signed int vec_xrx (unsigned int index, vector signed int data); 19772 unsigned int vec_xrx (unsigned int index, vector unsigned int data); 19773 float vec_xrx (unsigned int index, vector float data); 19774 @end smallexample 19775 19776 The @code{vec_all_nez}, @code{vec_any_eqz}, and @code{vec_cmpnez} 19777 perform pairwise comparisons between the elements at the same 19778 positions within their two vector arguments. 19779 The @code{vec_all_nez} function returns a 19780 non-zero value if and only if all pairwise comparisons are not 19781 equal and no element of either vector argument contains a zero. 19782 The @code{vec_any_eqz} function returns a 19783 non-zero value if and only if at least one pairwise comparison is equal 19784 or if at least one element of either vector argument contains a zero. 19785 The @code{vec_cmpnez} function returns a vector of the same type as 19786 its two arguments, within which each element consists of all ones to 19787 denote that either the corresponding elements of the incoming arguments are 19788 not equal or that at least one of the corresponding elements contains 19789 zero. Otherwise, the element of the returned vector contains all zeros. 19790 19791 The @code{vec_xlx} and @code{vec_xrx} functions extract the single 19792 element selected by the @code{index} argument from the vector 19793 represented by the @code{data} argument. The @code{index} argument 19794 always specifies a byte offset, regardless of the size of the vector 19795 element. With @code{vec_xlx}, @code{index} is the offset of the first 19796 byte of the element to be extracted. With @code{vec_xrx}, @code{index} 19797 represents the last byte of the element to be extracted, measured 19798 from the right end of the vector. In other words, the last byte of 19799 the element to be extracted is found at position @code{(15 - index)}. 19800 There is no requirement that @code{index} be a multiple of the vector 19801 element size. However, if the size of the vector element added to 19802 @code{index} is greater than 15, the content of the returned value is 19803 undefined. 19804 19805 The following functions are also available if the ISA 3.0 instruction 19806 set additions (@option{-mcpu=power9}) are available. 19807 19808 Only functions excluded from the PVIPR are listed here. 19809 19810 @smallexample 19811 vector long long vec_vctz (vector long long); 19812 vector unsigned long long vec_vctz (vector unsigned long long); 19813 vector int vec_vctz (vector int); 19814 vector unsigned int vec_vctz (vector int); 19815 vector short vec_vctz (vector short); 19816 vector unsigned short vec_vctz (vector unsigned short); 19817 vector signed char vec_vctz (vector signed char); 19818 vector unsigned char vec_vctz (vector unsigned char); 19819 19820 vector signed char vec_vctzb (vector signed char); 19821 vector unsigned char vec_vctzb (vector unsigned char); 19822 19823 vector long long vec_vctzd (vector long long); 19824 vector unsigned long long vec_vctzd (vector unsigned long long); 19825 19826 vector short vec_vctzh (vector short); 19827 vector unsigned short vec_vctzh (vector unsigned short); 19828 19829 vector int vec_vctzw (vector int); 19830 vector unsigned int vec_vctzw (vector int); 19831 19832 vector int vec_vprtyb (vector int); 19833 vector unsigned int vec_vprtyb (vector unsigned int); 19834 vector long long vec_vprtyb (vector long long); 19835 vector unsigned long long vec_vprtyb (vector unsigned long long); 19836 19837 vector int vec_vprtybw (vector int); 19838 vector unsigned int vec_vprtybw (vector unsigned int); 19839 19840 vector long long vec_vprtybd (vector long long); 19841 vector unsigned long long vec_vprtybd (vector unsigned long long); 19842 @end smallexample 19843 19844 On 64-bit targets, if the ISA 3.0 additions (@option{-mcpu=power9}) 19845 are available: 19846 19847 @smallexample 19848 vector long vec_vprtyb (vector long); 19849 vector unsigned long vec_vprtyb (vector unsigned long); 19850 vector __int128 vec_vprtyb (vector __int128); 19851 vector __uint128 vec_vprtyb (vector __uint128); 19852 19853 vector long vec_vprtybd (vector long); 19854 vector unsigned long vec_vprtybd (vector unsigned long); 19855 19856 vector __int128 vec_vprtybq (vector __int128); 19857 vector __uint128 vec_vprtybd (vector __uint128); 19858 @end smallexample 19859 19860 The following built-in functions are available for the PowerPC family 19861 of processors, starting with ISA 3.0 or later (@option{-mcpu=power9}). 19862 19863 Only functions excluded from the PVIPR are listed here. 19864 19865 @smallexample 19866 __vector unsigned char 19867 vec_absdb (__vector unsigned char arg1, __vector unsigned char arg2); 19868 __vector unsigned short 19869 vec_absdh (__vector unsigned short arg1, __vector unsigned short arg2); 19870 __vector unsigned int 19871 vec_absdw (__vector unsigned int arg1, __vector unsigned int arg2); 19872 @end smallexample 19873 19874 The @code{vec_absd}, @code{vec_absdb}, @code{vec_absdh}, and 19875 @code{vec_absdw} built-in functions each computes the absolute 19876 differences of the pairs of vector elements supplied in its two vector 19877 arguments, placing the absolute differences into the corresponding 19878 elements of the vector result. 19879 19880 The following built-in functions are available for the PowerPC family 19881 of processors, starting with ISA 3.0 or later (@option{-mcpu=power9}): 19882 @smallexample 19883 vector unsigned int vec_vrlnm (vector unsigned int, vector unsigned int); 19884 vector unsigned long long vec_vrlnm (vector unsigned long long, 19885 vector unsigned long long); 19886 @end smallexample 19887 19888 The result of @code{vec_vrlnm} is obtained by rotating each element 19889 of the first argument vector left and ANDing it with a mask. The 19890 second argument vector contains the mask beginning in bits 11:15, 19891 the mask end in bits 19:23, and the shift count in bits 27:31, 19892 of each element. 19893 19894 If the cryptographic instructions are enabled (@option{-mcrypto} or 19895 @option{-mcpu=power8}), the following builtins are enabled. 19896 19897 Only functions excluded from the PVIPR are listed here. 19898 19899 @smallexample 19900 vector unsigned long long __builtin_crypto_vsbox (vector unsigned long long); 19901 19902 vector unsigned long long __builtin_crypto_vcipher (vector unsigned long long, 19903 vector unsigned long long); 19904 19905 vector unsigned long long __builtin_crypto_vcipherlast 19906 (vector unsigned long long, 19907 vector unsigned long long); 19908 19909 vector unsigned long long __builtin_crypto_vncipher (vector unsigned long long, 19910 vector unsigned long long); 19911 19912 vector unsigned long long __builtin_crypto_vncipherlast (vector unsigned long long, 19913 vector unsigned long long); 19914 19915 vector unsigned char __builtin_crypto_vpermxor (vector unsigned char, 19916 vector unsigned char, 19917 vector unsigned char); 19918 19919 vector unsigned short __builtin_crypto_vpermxor (vector unsigned short, 19920 vector unsigned short, 19921 vector unsigned short); 19922 19923 vector unsigned int __builtin_crypto_vpermxor (vector unsigned int, 19924 vector unsigned int, 19925 vector unsigned int); 19926 19927 vector unsigned long long __builtin_crypto_vpermxor (vector unsigned long long, 19928 vector unsigned long long, 19929 vector unsigned long long); 19930 19931 vector unsigned char __builtin_crypto_vpmsumb (vector unsigned char, 19932 vector unsigned char); 19933 19934 vector unsigned short __builtin_crypto_vpmsumh (vector unsigned short, 19935 vector unsigned short); 19936 19937 vector unsigned int __builtin_crypto_vpmsumw (vector unsigned int, 19938 vector unsigned int); 19939 19940 vector unsigned long long __builtin_crypto_vpmsumd (vector unsigned long long, 19941 vector unsigned long long); 19942 19943 vector unsigned long long __builtin_crypto_vshasigmad (vector unsigned long long, 19944 int, int); 19945 19946 vector unsigned int __builtin_crypto_vshasigmaw (vector unsigned int, int, int); 19947 @end smallexample 19948 19949 The second argument to @var{__builtin_crypto_vshasigmad} and 19950 @var{__builtin_crypto_vshasigmaw} must be a constant 19951 integer that is 0 or 1. The third argument to these built-in functions 19952 must be a constant integer in the range of 0 to 15. 19953 19954 The following sign extension builtins are provided: 19955 19956 @smallexample 19957 vector signed int vec_signexti (vector signed char a); 19958 vector signed long long vec_signextll (vector signed char a); 19959 vector signed int vec_signexti (vector signed short a); 19960 vector signed long long vec_signextll (vector signed short a); 19961 vector signed long long vec_signextll (vector signed int a); 19962 vector signed long long vec_signextq (vector signed long long a); 19963 @end smallexample 19964 19965 Each element of the result is produced by sign-extending the element of the 19966 input vector that would fall in the least significant portion of the result 19967 element. For example, a sign-extension of a vector signed char to a vector 19968 signed long long will sign extend the rightmost byte of each doubleword. 19969 19970 @node PowerPC AltiVec Built-in Functions Available on ISA 3.1 19971 @subsubsection PowerPC AltiVec Built-in Functions Available on ISA 3.1 19972 19973 The following additional built-in functions are also available for the 19974 PowerPC family of processors, starting with ISA 3.1 (@option{-mcpu=power10}): 19975 19976 19977 @smallexample 19978 @exdent vector unsigned long long int 19979 @exdent vec_cfuge (vector unsigned long long int, vector unsigned long long int); 19980 @end smallexample 19981 Perform a vector centrifuge operation, as if implemented by the 19982 @code{vcfuged} instruction. 19983 @findex vec_cfuge 19984 19985 @smallexample 19986 @exdent vector unsigned long long int 19987 @exdent vec_cntlzm (vector unsigned long long int, vector unsigned long long int); 19988 @end smallexample 19989 Perform a vector count leading zeros under bit mask operation, as if 19990 implemented by the @code{vclzdm} instruction. 19991 @findex vec_cntlzm 19992 19993 @smallexample 19994 @exdent vector unsigned long long int 19995 @exdent vec_cnttzm (vector unsigned long long int, vector unsigned long long int); 19996 @end smallexample 19997 Perform a vector count trailing zeros under bit mask operation, as if 19998 implemented by the @code{vctzdm} instruction. 19999 @findex vec_cnttzm 20000 20001 @smallexample 20002 @exdent vector signed char 20003 @exdent vec_clrl (vector signed char a, unsigned int n); 20004 @exdent vector unsigned char 20005 @exdent vec_clrl (vector unsigned char a, unsigned int n); 20006 @end smallexample 20007 Clear the left-most @code{(16 - n)} bytes of vector argument @code{a}, as if 20008 implemented by the @code{vclrlb} instruction on a big-endian target 20009 and by the @code{vclrrb} instruction on a little-endian target. A 20010 value of @code{n} that is greater than 16 is treated as if it equaled 16. 20011 @findex vec_clrl 20012 20013 @smallexample 20014 @exdent vector signed char 20015 @exdent vec_clrr (vector signed char a, unsigned int n); 20016 @exdent vector unsigned char 20017 @exdent vec_clrr (vector unsigned char a, unsigned int n); 20018 @end smallexample 20019 Clear the right-most @code{(16 - n)} bytes of vector argument @code{a}, as if 20020 implemented by the @code{vclrrb} instruction on a big-endian target 20021 and by the @code{vclrlb} instruction on a little-endian target. A 20022 value of @code{n} that is greater than 16 is treated as if it equaled 16. 20023 @findex vec_clrr 20024 20025 @smallexample 20026 @exdent vector unsigned long long int 20027 @exdent vec_gnb (vector unsigned __int128, const unsigned char); 20028 @end smallexample 20029 Perform a 128-bit vector gather operation, as if implemented by the 20030 @code{vgnb} instruction. The second argument must be a literal 20031 integer value between 2 and 7 inclusive. 20032 @findex vec_gnb 20033 20034 20035 Vector Extract 20036 20037 @smallexample 20038 @exdent vector unsigned long long int 20039 @exdent vec_extractl (vector unsigned char, vector unsigned char, unsigned int); 20040 @exdent vector unsigned long long int 20041 @exdent vec_extractl (vector unsigned short, vector unsigned short, unsigned int); 20042 @exdent vector unsigned long long int 20043 @exdent vec_extractl (vector unsigned int, vector unsigned int, unsigned int); 20044 @exdent vector unsigned long long int 20045 @exdent vec_extractl (vector unsigned long long, vector unsigned long long, unsigned int); 20046 @end smallexample 20047 Extract an element from two concatenated vectors starting at the given byte index 20048 in natural-endian order, and place it zero-extended in doubleword 1 of the result 20049 according to natural element order. If the byte index is out of range for the 20050 data type, the intrinsic will be rejected. 20051 For little-endian, this output will match the placement by the hardware 20052 instruction, i.e., dword[0] in RTL notation. For big-endian, an additional 20053 instruction is needed to move it from the "left" doubleword to the "right" one. 20054 For little-endian, semantics matching the @code{vextdubvrx}, 20055 @code{vextduhvrx}, @code{vextduwvrx} instruction will be generated, while for 20056 big-endian, semantics matching the @code{vextdubvlx}, @code{vextduhvlx}, 20057 @code{vextduwvlx} instructions 20058 will be generated. Note that some fairly anomalous results can be generated if 20059 the byte index is not aligned on an element boundary for the element being 20060 extracted. This is a limitation of the bi-endian vector programming model is 20061 consistent with the limitation on @code{vec_perm}. 20062 @findex vec_extractl 20063 20064 @smallexample 20065 @exdent vector unsigned long long int 20066 @exdent vec_extracth (vector unsigned char, vector unsigned char, unsigned int); 20067 @exdent vector unsigned long long int 20068 @exdent vec_extracth (vector unsigned short, vector unsigned short, 20069 unsigned int); 20070 @exdent vector unsigned long long int 20071 @exdent vec_extracth (vector unsigned int, vector unsigned int, unsigned int); 20072 @exdent vector unsigned long long int 20073 @exdent vec_extracth (vector unsigned long long, vector unsigned long long, 20074 unsigned int); 20075 @end smallexample 20076 Extract an element from two concatenated vectors starting at the given byte 20077 index. The index is based on big endian order for a little endian system. 20078 Similarly, the index is based on little endian order for a big endian system. 20079 The extraced elements are zero-extended and put in doubleword 1 20080 according to natural element order. If the byte index is out of range for the 20081 data type, the intrinsic will be rejected. For little-endian, this output 20082 will match the placement by the hardware instruction (vextdubvrx, vextduhvrx, 20083 vextduwvrx, vextddvrx) i.e., dword[0] in RTL 20084 notation. For big-endian, an additional instruction is needed to move it 20085 from the "left" doubleword to the "right" one. For little-endian, semantics 20086 matching the @code{vextdubvlx}, @code{vextduhvlx}, @code{vextduwvlx} 20087 instructions will be generated, while for big-endian, semantics matching the 20088 @code{vextdubvrx}, @code{vextduhvrx}, @code{vextduwvrx} instructions will 20089 be generated. Note that some fairly anomalous 20090 results can be generated if the byte index is not aligned on the 20091 element boundary for the element being extracted. This is a 20092 limitation of the bi-endian vector programming model consistent with the 20093 limitation on @code{vec_perm}. 20094 @findex vec_extracth 20095 @smallexample 20096 @exdent vector unsigned long long int 20097 @exdent vec_pdep (vector unsigned long long int, vector unsigned long long int); 20098 @end smallexample 20099 Perform a vector parallel bits deposit operation, as if implemented by 20100 the @code{vpdepd} instruction. 20101 @findex vec_pdep 20102 20103 Vector Insert 20104 20105 @smallexample 20106 @exdent vector unsigned char 20107 @exdent vec_insertl (unsigned char, vector unsigned char, unsigned int); 20108 @exdent vector unsigned short 20109 @exdent vec_insertl (unsigned short, vector unsigned short, unsigned int); 20110 @exdent vector unsigned int 20111 @exdent vec_insertl (unsigned int, vector unsigned int, unsigned int); 20112 @exdent vector unsigned long long 20113 @exdent vec_insertl (unsigned long long, vector unsigned long long, 20114 unsigned int); 20115 @exdent vector unsigned char 20116 @exdent vec_insertl (vector unsigned char, vector unsigned char, unsigned int; 20117 @exdent vector unsigned short 20118 @exdent vec_insertl (vector unsigned short, vector unsigned short, 20119 unsigned int); 20120 @exdent vector unsigned int 20121 @exdent vec_insertl (vector unsigned int, vector unsigned int, unsigned int); 20122 @end smallexample 20123 20124 Let src be the first argument, when the first argument is a scalar, or the 20125 rightmost element of the left doubleword of the first argument, when the first 20126 argument is a vector. Insert the source into the destination at the position 20127 given by the third argument, using natural element order in the second 20128 argument. The rest of the second argument is unchanged. If the byte 20129 index is greater than 14 for halfwords, greater than 12 for words, or 20130 greater than 8 for doublewords the result is undefined. For little-endian, 20131 the generated code will be semantically equivalent to @code{vins[bhwd]rx} 20132 instructions. Similarly for big-endian it will be semantically equivalent 20133 to @code{vins[bhwd]lx}. Note that some fairly anomalous results can be 20134 generated if the byte index is not aligned on an element boundary for the 20135 type of element being inserted. 20136 @findex vec_insertl 20137 20138 @smallexample 20139 @exdent vector unsigned char 20140 @exdent vec_inserth (unsigned char, vector unsigned char, unsigned int); 20141 @exdent vector unsigned short 20142 @exdent vec_inserth (unsigned short, vector unsigned short, unsigned int); 20143 @exdent vector unsigned int 20144 @exdent vec_inserth (unsigned int, vector unsigned int, unsigned int); 20145 @exdent vector unsigned long long 20146 @exdent vec_inserth (unsigned long long, vector unsigned long long, 20147 unsigned int); 20148 @exdent vector unsigned char 20149 @exdent vec_inserth (vector unsigned char, vector unsigned char, unsigned int); 20150 @exdent vector unsigned short 20151 @exdent vec_inserth (vector unsigned short, vector unsigned short, 20152 unsigned int); 20153 @exdent vector unsigned int 20154 @exdent vec_inserth (vector unsigned int, vector unsigned int, unsigned int); 20155 @end smallexample 20156 20157 Let src be the first argument, when the first argument is a scalar, or the 20158 rightmost element of the first argument, when the first argument is a vector. 20159 Insert src into the second argument at the position identified by the third 20160 argument, using opposite element order in the second argument, and leaving the 20161 rest of the second argument unchanged. If the byte index is greater than 14 20162 for halfwords, 12 for words, or 8 for doublewords, the intrinsic will be 20163 rejected. Note that the underlying hardware instruction uses the same register 20164 for the second argument and the result. 20165 For little-endian, the code generation will be semantically equivalent to 20166 @code{vins[bhwd]lx}, while for big-endian it will be semantically equivalent to 20167 @code{vins[bhwd]rx}. 20168 Note that some fairly anomalous results can be generated if the byte index is 20169 not aligned on an element boundary for the sort of element being inserted. 20170 @findex vec_inserth 20171 20172 Vector Replace Element 20173 @smallexample 20174 @exdent vector signed int vec_replace_elt (vector signed int, signed int, 20175 const int); 20176 @exdent vector unsigned int vec_replace_elt (vector unsigned int, 20177 unsigned int, const int); 20178 @exdent vector float vec_replace_elt (vector float, float, const int); 20179 @exdent vector signed long long vec_replace_elt (vector signed long long, 20180 signed long long, const int); 20181 @exdent vector unsigned long long vec_replace_elt (vector unsigned long long, 20182 unsigned long long, const int); 20183 @exdent vector double rec_replace_elt (vector double, double, const int); 20184 @end smallexample 20185 The third argument (constrained to [0,3]) identifies the natural-endian 20186 element number of the first argument that will be replaced by the second 20187 argument to produce the result. The other elements of the first argument will 20188 remain unchanged in the result. 20189 20190 If it's desirable to insert a word at an unaligned position, use 20191 vec_replace_unaligned instead. 20192 20193 @findex vec_replace_element 20194 20195 Vector Replace Unaligned 20196 @smallexample 20197 @exdent vector unsigned char vec_replace_unaligned (vector unsigned char, 20198 signed int, const int); 20199 @exdent vector unsigned char vec_replace_unaligned (vector unsigned char, 20200 unsigned int, const int); 20201 @exdent vector unsigned char vec_replace_unaligned (vector unsigned char, 20202 float, const int); 20203 @exdent vector unsigned char vec_replace_unaligned (vector unsigned char, 20204 signed long long, const int); 20205 @exdent vector unsigned char vec_replace_unaligned (vector unsigned char, 20206 unsigned long long, const int); 20207 @exdent vector unsigned char vec_replace_unaligned (vector unsigned char, 20208 double, const int); 20209 @end smallexample 20210 20211 The second argument replaces a portion of the first argument to produce the 20212 result, with the rest of the first argument unchanged in the result. The 20213 third argument identifies the byte index (using left-to-right, or big-endian 20214 order) where the high-order byte of the second argument will be placed, with 20215 the remaining bytes of the second argument placed naturally "to the right" 20216 of the high-order byte. 20217 20218 The programmer is responsible for understanding the endianness issues involved 20219 with the first argument and the result. 20220 @findex vec_replace_unaligned 20221 20222 Vector Shift Left Double Bit Immediate 20223 @smallexample 20224 @exdent vector signed char vec_sldb (vector signed char, vector signed char, 20225 const unsigned int); 20226 @exdent vector unsigned char vec_sldb (vector unsigned char, 20227 vector unsigned char, const unsigned int); 20228 @exdent vector signed short vec_sldb (vector signed short, vector signed short, 20229 const unsigned int); 20230 @exdent vector unsigned short vec_sldb (vector unsigned short, 20231 vector unsigned short, const unsigned int); 20232 @exdent vector signed int vec_sldb (vector signed int, vector signed int, 20233 const unsigned int); 20234 @exdent vector unsigned int vec_sldb (vector unsigned int, vector unsigned int, 20235 const unsigned int); 20236 @exdent vector signed long long vec_sldb (vector signed long long, 20237 vector signed long long, const unsigned int); 20238 @exdent vector unsigned long long vec_sldb (vector unsigned long long, 20239 vector unsigned long long, const unsigned int); 20240 @end smallexample 20241 20242 Shift the combined input vectors left by the amount specified by the low-order 20243 three bits of the third argument, and return the leftmost remaining 128 bits. 20244 Code using this instruction must be endian-aware. 20245 20246 @findex vec_sldb 20247 20248 Vector Shift Right Double Bit Immediate 20249 20250 @smallexample 20251 @exdent vector signed char vec_srdb (vector signed char, vector signed char, 20252 const unsigned int); 20253 @exdent vector unsigned char vec_srdb (vector unsigned char, vector unsigned char, 20254 const unsigned int); 20255 @exdent vector signed short vec_srdb (vector signed short, vector signed short, 20256 const unsigned int); 20257 @exdent vector unsigned short vec_srdb (vector unsigned short, vector unsigned short, 20258 const unsigned int); 20259 @exdent vector signed int vec_srdb (vector signed int, vector signed int, 20260 const unsigned int); 20261 @exdent vector unsigned int vec_srdb (vector unsigned int, vector unsigned int, 20262 const unsigned int); 20263 @exdent vector signed long long vec_srdb (vector signed long long, 20264 vector signed long long, const unsigned int); 20265 @exdent vector unsigned long long vec_srdb (vector unsigned long long, 20266 vector unsigned long long, const unsigned int); 20267 @end smallexample 20268 20269 Shift the combined input vectors right by the amount specified by the low-order 20270 three bits of the third argument, and return the remaining 128 bits. Code 20271 using this built-in must be endian-aware. 20272 20273 @findex vec_srdb 20274 20275 Vector Splat 20276 20277 @smallexample 20278 @exdent vector signed int vec_splati (const signed int); 20279 @exdent vector float vec_splati (const float); 20280 @end smallexample 20281 20282 Splat a 32-bit immediate into a vector of words. 20283 20284 @findex vec_splati 20285 20286 @smallexample 20287 @exdent vector double vec_splatid (const float); 20288 @end smallexample 20289 20290 Convert a single precision floating-point value to double-precision and splat 20291 the result to a vector of double-precision floats. 20292 20293 @findex vec_splatid 20294 20295 @smallexample 20296 @exdent vector signed int vec_splati_ins (vector signed int, 20297 const unsigned int, const signed int); 20298 @exdent vector unsigned int vec_splati_ins (vector unsigned int, 20299 const unsigned int, const unsigned int); 20300 @exdent vector float vec_splati_ins (vector float, const unsigned int, 20301 const float); 20302 @end smallexample 20303 20304 Argument 2 must be either 0 or 1. Splat the value of argument 3 into the word 20305 identified by argument 2 of each doubleword of argument 1 and return the 20306 result. The other words of argument 1 are unchanged. 20307 20308 @findex vec_splati_ins 20309 20310 Vector Blend Variable 20311 20312 @smallexample 20313 @exdent vector signed char vec_blendv (vector signed char, vector signed char, 20314 vector unsigned char); 20315 @exdent vector unsigned char vec_blendv (vector unsigned char, 20316 vector unsigned char, vector unsigned char); 20317 @exdent vector signed short vec_blendv (vector signed short, 20318 vector signed short, vector unsigned short); 20319 @exdent vector unsigned short vec_blendv (vector unsigned short, 20320 vector unsigned short, vector unsigned short); 20321 @exdent vector signed int vec_blendv (vector signed int, vector signed int, 20322 vector unsigned int); 20323 @exdent vector unsigned int vec_blendv (vector unsigned int, 20324 vector unsigned int, vector unsigned int); 20325 @exdent vector signed long long vec_blendv (vector signed long long, 20326 vector signed long long, vector unsigned long long); 20327 @exdent vector unsigned long long vec_blendv (vector unsigned long long, 20328 vector unsigned long long, vector unsigned long long); 20329 @exdent vector float vec_blendv (vector float, vector float, 20330 vector unsigned int); 20331 @exdent vector double vec_blendv (vector double, vector double, 20332 vector unsigned long long); 20333 @end smallexample 20334 20335 Blend the first and second argument vectors according to the sign bits of the 20336 corresponding elements of the third argument vector. This is similar to the 20337 @code{vsel} and @code{xxsel} instructions but for bigger elements. 20338 20339 @findex vec_blendv 20340 20341 Vector Permute Extended 20342 20343 @smallexample 20344 @exdent vector signed char vec_permx (vector signed char, vector signed char, 20345 vector unsigned char, const int); 20346 @exdent vector unsigned char vec_permx (vector unsigned char, 20347 vector unsigned char, vector unsigned char, const int); 20348 @exdent vector signed short vec_permx (vector signed short, 20349 vector signed short, vector unsigned char, const int); 20350 @exdent vector unsigned short vec_permx (vector unsigned short, 20351 vector unsigned short, vector unsigned char, const int); 20352 @exdent vector signed int vec_permx (vector signed int, vector signed int, 20353 vector unsigned char, const int); 20354 @exdent vector unsigned int vec_permx (vector unsigned int, 20355 vector unsigned int, vector unsigned char, const int); 20356 @exdent vector signed long long vec_permx (vector signed long long, 20357 vector signed long long, vector unsigned char, const int); 20358 @exdent vector unsigned long long vec_permx (vector unsigned long long, 20359 vector unsigned long long, vector unsigned char, const int); 20360 @exdent vector float (vector float, vector float, vector unsigned char, 20361 const int); 20362 @exdent vector double (vector double, vector double, vector unsigned char, 20363 const int); 20364 @end smallexample 20365 20366 Perform a partial permute of the first two arguments, which form a 32-byte 20367 section of an emulated vector up to 256 bytes wide, using the partial permute 20368 control vector in the third argument. The fourth argument (constrained to 20369 values of 0-7) identifies which 32-byte section of the emulated vector is 20370 contained in the first two arguments. 20371 @findex vec_permx 20372 20373 @smallexample 20374 @exdent vector unsigned long long int 20375 @exdent vec_pext (vector unsigned long long int, vector unsigned long long int); 20376 @end smallexample 20377 Perform a vector parallel bit extract operation, as if implemented by 20378 the @code{vpextd} instruction. 20379 @findex vec_pext 20380 20381 @smallexample 20382 @exdent vector unsigned char vec_stril (vector unsigned char); 20383 @exdent vector signed char vec_stril (vector signed char); 20384 @exdent vector unsigned short vec_stril (vector unsigned short); 20385 @exdent vector signed short vec_stril (vector signed short); 20386 @end smallexample 20387 Isolate the left-most non-zero elements of the incoming vector argument, 20388 replacing all elements to the right of the left-most zero element 20389 found within the argument with zero. The typical implementation uses 20390 the @code{vstribl} or @code{vstrihl} instruction on big-endian targets 20391 and uses the @code{vstribr} or @code{vstrihr} instruction on 20392 little-endian targets. 20393 @findex vec_stril 20394 20395 @smallexample 20396 @exdent int vec_stril_p (vector unsigned char); 20397 @exdent int vec_stril_p (vector signed char); 20398 @exdent int short vec_stril_p (vector unsigned short); 20399 @exdent int vec_stril_p (vector signed short); 20400 @end smallexample 20401 Return a non-zero value if and only if the argument contains a zero 20402 element. The typical implementation uses 20403 the @code{vstribl.} or @code{vstrihl.} instruction on big-endian targets 20404 and uses the @code{vstribr.} or @code{vstrihr.} instruction on 20405 little-endian targets. Choose this built-in to check for presence of 20406 zero element if the same argument is also passed to @code{vec_stril}. 20407 @findex vec_stril_p 20408 20409 @smallexample 20410 @exdent vector unsigned char vec_strir (vector unsigned char); 20411 @exdent vector signed char vec_strir (vector signed char); 20412 @exdent vector unsigned short vec_strir (vector unsigned short); 20413 @exdent vector signed short vec_strir (vector signed short); 20414 @end smallexample 20415 Isolate the right-most non-zero elements of the incoming vector argument, 20416 replacing all elements to the left of the right-most zero element 20417 found within the argument with zero. The typical implementation uses 20418 the @code{vstribr} or @code{vstrihr} instruction on big-endian targets 20419 and uses the @code{vstribl} or @code{vstrihl} instruction on 20420 little-endian targets. 20421 @findex vec_strir 20422 20423 @smallexample 20424 @exdent int vec_strir_p (vector unsigned char); 20425 @exdent int vec_strir_p (vector signed char); 20426 @exdent int short vec_strir_p (vector unsigned short); 20427 @exdent int vec_strir_p (vector signed short); 20428 @end smallexample 20429 Return a non-zero value if and only if the argument contains a zero 20430 element. The typical implementation uses 20431 the @code{vstribr.} or @code{vstrihr.} instruction on big-endian targets 20432 and uses the @code{vstribl.} or @code{vstrihl.} instruction on 20433 little-endian targets. Choose this built-in to check for presence of 20434 zero element if the same argument is also passed to @code{vec_strir}. 20435 @findex vec_strir_p 20436 20437 @smallexample 20438 @exdent vector unsigned char 20439 @exdent vec_ternarylogic (vector unsigned char, vector unsigned char, 20440 vector unsigned char, const unsigned int); 20441 @exdent vector unsigned short 20442 @exdent vec_ternarylogic (vector unsigned short, vector unsigned short, 20443 vector unsigned short, const unsigned int); 20444 @exdent vector unsigned int 20445 @exdent vec_ternarylogic (vector unsigned int, vector unsigned int, 20446 vector unsigned int, const unsigned int); 20447 @exdent vector unsigned long long int 20448 @exdent vec_ternarylogic (vector unsigned long long int, vector unsigned long long int, 20449 vector unsigned long long int, const unsigned int); 20450 @exdent vector unsigned __int128 20451 @exdent vec_ternarylogic (vector unsigned __int128, vector unsigned __int128, 20452 vector unsigned __int128, const unsigned int); 20453 @end smallexample 20454 Perform a 128-bit vector evaluate operation, as if implemented by the 20455 @code{xxeval} instruction. The fourth argument must be a literal 20456 integer value between 0 and 255 inclusive. 20457 @findex vec_ternarylogic 20458 20459 @smallexample 20460 @exdent vector unsigned char vec_genpcvm (vector unsigned char, const int); 20461 @exdent vector unsigned short vec_genpcvm (vector unsigned short, const int); 20462 @exdent vector unsigned int vec_genpcvm (vector unsigned int, const int); 20463 @exdent vector unsigned int vec_genpcvm (vector unsigned long long int, 20464 const int); 20465 @end smallexample 20466 20467 Vector Integer Multiply/Divide/Modulo 20468 20469 @smallexample 20470 @exdent vector signed int 20471 @exdent vec_mulh (vector signed int a, vector signed int b); 20472 @exdent vector unsigned int 20473 @exdent vec_mulh (vector unsigned int a, vector unsigned int b); 20474 @end smallexample 20475 20476 For each integer value @code{i} from 0 to 3, do the following. The integer 20477 value in word element @code{i} of a is multiplied by the integer value in word 20478 element @code{i} of b. The high-order 32 bits of the 64-bit product are placed 20479 into word element @code{i} of the vector returned. 20480 20481 @smallexample 20482 @exdent vector signed long long 20483 @exdent vec_mulh (vector signed long long a, vector signed long long b); 20484 @exdent vector unsigned long long 20485 @exdent vec_mulh (vector unsigned long long a, vector unsigned long long b); 20486 @end smallexample 20487 20488 For each integer value @code{i} from 0 to 1, do the following. The integer 20489 value in doubleword element @code{i} of a is multiplied by the integer value in 20490 doubleword element @code{i} of b. The high-order 64 bits of the 128-bit product 20491 are placed into doubleword element @code{i} of the vector returned. 20492 20493 @smallexample 20494 @exdent vector unsigned long long 20495 @exdent vec_mul (vector unsigned long long a, vector unsigned long long b); 20496 @exdent vector signed long long 20497 @exdent vec_mul (vector signed long long a, vector signed long long b); 20498 @end smallexample 20499 20500 For each integer value @code{i} from 0 to 1, do the following. The integer 20501 value in doubleword element @code{i} of a is multiplied by the integer value in 20502 doubleword element @code{i} of b. The low-order 64 bits of the 128-bit product 20503 are placed into doubleword element @code{i} of the vector returned. 20504 20505 @smallexample 20506 @exdent vector signed int 20507 @exdent vec_div (vector signed int a, vector signed int b); 20508 @exdent vector unsigned int 20509 @exdent vec_div (vector unsigned int a, vector unsigned int b); 20510 @end smallexample 20511 20512 For each integer value @code{i} from 0 to 3, do the following. The integer in 20513 word element @code{i} of a is divided by the integer in word element @code{i} 20514 of b. The unique integer quotient is placed into the word element @code{i} of 20515 the vector returned. If an attempt is made to perform any of the divisions 20516 <anything> 0 then the quotient is undefined. 20517 20518 @smallexample 20519 @exdent vector signed long long 20520 @exdent vec_div (vector signed long long a, vector signed long long b); 20521 @exdent vector unsigned long long 20522 @exdent vec_div (vector unsigned long long a, vector unsigned long long b); 20523 @end smallexample 20524 20525 For each integer value @code{i} from 0 to 1, do the following. The integer in 20526 doubleword element @code{i} of a is divided by the integer in doubleword 20527 element @code{i} of b. The unique integer quotient is placed into the 20528 doubleword element @code{i} of the vector returned. If an attempt is made to 20529 perform any of the divisions 0x8000_0000_0000_0000 -1 or <anything> 0 then 20530 the quotient is undefined. 20531 20532 @smallexample 20533 @exdent vector signed int 20534 @exdent vec_dive (vector signed int a, vector signed int b); 20535 @exdent vector unsigned int 20536 @exdent vec_dive (vector unsigned int a, vector unsigned int b); 20537 @end smallexample 20538 20539 For each integer value @code{i} from 0 to 3, do the following. The integer in 20540 word element @code{i} of a is shifted left by 32 bits, then divided by the 20541 integer in word element @code{i} of b. The unique integer quotient is placed 20542 into the word element @code{i} of the vector returned. If the quotient cannot 20543 be represented in 32 bits, or if an attempt is made to perform any of the 20544 divisions <anything> 0 then the quotient is undefined. 20545 20546 @smallexample 20547 @exdent vector signed long long 20548 @exdent vec_dive (vector signed long long a, vector signed long long b); 20549 @exdent vector unsigned long long 20550 @exdent vec_dive (vector unsigned long long a, vector unsigned long long b); 20551 @end smallexample 20552 20553 For each integer value @code{i} from 0 to 1, do the following. The integer in 20554 doubleword element @code{i} of a is shifted left by 64 bits, then divided by 20555 the integer in doubleword element @code{i} of b. The unique integer quotient is 20556 placed into the doubleword element @code{i} of the vector returned. If the 20557 quotient cannot be represented in 64 bits, or if an attempt is made to perform 20558 <anything> 0 then the quotient is undefined. 20559 20560 @smallexample 20561 @exdent vector signed int 20562 @exdent vec_mod (vector signed int a, vector signed int b); 20563 @exdent vector unsigned int 20564 @exdent vec_mod (vector unsigned int a, vector unsigned int b); 20565 @end smallexample 20566 20567 For each integer value @code{i} from 0 to 3, do the following. The integer in 20568 word element @code{i} of a is divided by the integer in word element @code{i} 20569 of b. The unique integer remainder is placed into the word element @code{i} of 20570 the vector returned. If an attempt is made to perform any of the divisions 20571 0x8000_0000 -1 or <anything> 0 then the remainder is undefined. 20572 20573 @smallexample 20574 @exdent vector signed long long 20575 @exdent vec_mod (vector signed long long a, vector signed long long b); 20576 @exdent vector unsigned long long 20577 @exdent vec_mod (vector unsigned long long a, vector unsigned long long b); 20578 @end smallexample 20579 20580 For each integer value @code{i} from 0 to 1, do the following. The integer in 20581 doubleword element @code{i} of a is divided by the integer in doubleword 20582 element @code{i} of b. The unique integer remainder is placed into the 20583 doubleword element @code{i} of the vector returned. If an attempt is made to 20584 perform <anything> 0 then the remainder is undefined. 20585 20586 Generate PCV from specified Mask size, as if implemented by the 20587 @code{xxgenpcvbm}, @code{xxgenpcvhm}, @code{xxgenpcvwm} instructions, where 20588 immediate value is either 0, 1, 2 or 3. 20589 @findex vec_genpcvm 20590 20591 @smallexample 20592 @exdent vector unsigned __int128 vec_rl (vector unsigned __int128 A, 20593 vector unsigned __int128 B); 20594 @exdent vector signed __int128 vec_rl (vector signed __int128 A, 20595 vector unsigned __int128 B); 20596 @end smallexample 20597 20598 Result value: Each element of R is obtained by rotating the corresponding element 20599 of A left by the number of bits specified by the corresponding element of B. 20600 20601 20602 @smallexample 20603 @exdent vector unsigned __int128 vec_rlmi (vector unsigned __int128, 20604 vector unsigned __int128, 20605 vector unsigned __int128); 20606 @exdent vector signed __int128 vec_rlmi (vector signed __int128, 20607 vector signed __int128, 20608 vector unsigned __int128); 20609 @end smallexample 20610 20611 Returns the result of rotating the first input and inserting it under mask 20612 into the second input. The first bit in the mask, the last bit in the mask are 20613 obtained from the two 7-bit fields bits [108:115] and bits [117:123] 20614 respectively of the second input. The shift is obtained from the third input 20615 in the 7-bit field [125:131] where all bits counted from zero at the left. 20616 20617 @smallexample 20618 @exdent vector unsigned __int128 vec_rlnm (vector unsigned __int128, 20619 vector unsigned __int128, 20620 vector unsigned __int128); 20621 @exdent vector signed __int128 vec_rlnm (vector signed __int128, 20622 vector unsigned __int128, 20623 vector unsigned __int128); 20624 @end smallexample 20625 20626 Returns the result of rotating the first input and ANDing it with a mask. The 20627 first bit in the mask and the last bit in the mask are obtained from the two 20628 7-bit fields bits [117:123] and bits [125:131] respectively of the second 20629 input. The shift is obtained from the third input in the 7-bit field bits 20630 [125:131] where all bits counted from zero at the left. 20631 20632 @smallexample 20633 @exdent vector unsigned __int128 vec_sl(vector unsigned __int128 A, vector unsigned __int128 B); 20634 @exdent vector signed __int128 vec_sl(vector signed __int128 A, vector unsigned __int128 B); 20635 @end smallexample 20636 20637 Result value: Each element of R is obtained by shifting the corresponding element of 20638 A left by the number of bits specified by the corresponding element of B. 20639 20640 @smallexample 20641 @exdent vector unsigned __int128 vec_sr(vector unsigned __int128 A, vector unsigned __int128 B); 20642 @exdent vector signed __int128 vec_sr(vector signed __int128 A, vector unsigned __int128 B); 20643 @end smallexample 20644 20645 Result value: Each element of R is obtained by shifting the corresponding element of 20646 A right by the number of bits specified by the corresponding element of B. 20647 20648 @smallexample 20649 @exdent vector unsigned __int128 vec_sra(vector unsigned __int128 A, vector unsigned __int128 B); 20650 @exdent vector signed __int128 vec_sra(vector signed __int128 A, vector unsigned __int128 B); 20651 @end smallexample 20652 20653 Result value: Each element of R is obtained by arithmetic shifting the corresponding 20654 element of A right by the number of bits specified by the corresponding element of B. 20655 20656 @smallexample 20657 @exdent vector unsigned __int128 vec_mule (vector unsigned long long, 20658 vector unsigned long long); 20659 @exdent vector signed __int128 vec_mule (vector signed long long, 20660 vector signed long long); 20661 @end smallexample 20662 20663 Returns a vector containing a 128-bit integer result of multiplying the even 20664 doubleword elements of the two inputs. 20665 20666 @smallexample 20667 @exdent vector unsigned __int128 vec_mulo (vector unsigned long long, 20668 vector unsigned long long); 20669 @exdent vector signed __int128 vec_mulo (vector signed long long, 20670 vector signed long long); 20671 @end smallexample 20672 20673 Returns a vector containing a 128-bit integer result of multiplying the odd 20674 doubleword elements of the two inputs. 20675 20676 @smallexample 20677 @exdent vector unsigned __int128 vec_div (vector unsigned __int128, 20678 vector unsigned __int128); 20679 @exdent vector signed __int128 vec_div (vector signed __int128, 20680 vector signed __int128); 20681 @end smallexample 20682 20683 Returns the result of dividing the first operand by the second operand. An 20684 attempt to divide any value by zero or to divide the most negative signed 20685 128-bit integer by negative one results in an undefined value. 20686 20687 @smallexample 20688 @exdent vector unsigned __int128 vec_dive (vector unsigned __int128, 20689 vector unsigned __int128); 20690 @exdent vector signed __int128 vec_dive (vector signed __int128, 20691 vector signed __int128); 20692 @end smallexample 20693 20694 The result is produced by shifting the first input left by 128 bits and 20695 dividing by the second. If an attempt is made to divide by zero or the result 20696 is larger than 128 bits, the result is undefined. 20697 20698 @smallexample 20699 @exdent vector unsigned __int128 vec_mod (vector unsigned __int128, 20700 vector unsigned __int128); 20701 @exdent vector signed __int128 vec_mod (vector signed __int128, 20702 vector signed __int128); 20703 @end smallexample 20704 20705 The result is the modulo result of dividing the first input by the second 20706 input. 20707 20708 The following builtins perform 128-bit vector comparisons. The 20709 @code{vec_all_xx}, @code{vec_any_xx}, and @code{vec_cmpxx}, where @code{xx} is 20710 one of the operations @code{eq, ne, gt, lt, ge, le} perform pairwise 20711 comparisons between the elements at the same positions within their two vector 20712 arguments. The @code{vec_all_xx}function returns a non-zero value if and only 20713 if all pairwise comparisons are true. The @code{vec_any_xx} function returns 20714 a non-zero value if and only if at least one pairwise comparison is true. The 20715 @code{vec_cmpxx}function returns a vector of the same type as its two 20716 arguments, within which each element consists of all ones to denote that 20717 specified logical comparison of the corresponding elements was true. 20718 Otherwise, the element of the returned vector contains all zeros. 20719 20720 @smallexample 20721 vector bool __int128 vec_cmpeq (vector signed __int128, vector signed __int128); 20722 vector bool __int128 vec_cmpeq (vector unsigned __int128, vector unsigned __int128); 20723 vector bool __int128 vec_cmpne (vector signed __int128, vector signed __int128); 20724 vector bool __int128 vec_cmpne (vector unsigned __int128, vector unsigned __int128); 20725 vector bool __int128 vec_cmpgt (vector signed __int128, vector signed __int128); 20726 vector bool __int128 vec_cmpgt (vector unsigned __int128, vector unsigned __int128); 20727 vector bool __int128 vec_cmplt (vector signed __int128, vector signed __int128); 20728 vector bool __int128 vec_cmplt (vector unsigned __int128, vector unsigned __int128); 20729 vector bool __int128 vec_cmpge (vector signed __int128, vector signed __int128); 20730 vector bool __int128 vec_cmpge (vector unsigned __int128, vector unsigned __int128); 20731 vector bool __int128 vec_cmple (vector signed __int128, vector signed __int128); 20732 vector bool __int128 vec_cmple (vector unsigned __int128, vector unsigned __int128); 20733 20734 int vec_all_eq (vector signed __int128, vector signed __int128); 20735 int vec_all_eq (vector unsigned __int128, vector unsigned __int128); 20736 int vec_all_ne (vector signed __int128, vector signed __int128); 20737 int vec_all_ne (vector unsigned __int128, vector unsigned __int128); 20738 int vec_all_gt (vector signed __int128, vector signed __int128); 20739 int vec_all_gt (vector unsigned __int128, vector unsigned __int128); 20740 int vec_all_lt (vector signed __int128, vector signed __int128); 20741 int vec_all_lt (vector unsigned __int128, vector unsigned __int128); 20742 int vec_all_ge (vector signed __int128, vector signed __int128); 20743 int vec_all_ge (vector unsigned __int128, vector unsigned __int128); 20744 int vec_all_le (vector signed __int128, vector signed __int128); 20745 int vec_all_le (vector unsigned __int128, vector unsigned __int128); 20746 20747 int vec_any_eq (vector signed __int128, vector signed __int128); 20748 int vec_any_eq (vector unsigned __int128, vector unsigned __int128); 20749 int vec_any_ne (vector signed __int128, vector signed __int128); 20750 int vec_any_ne (vector unsigned __int128, vector unsigned __int128); 20751 int vec_any_gt (vector signed __int128, vector signed __int128); 20752 int vec_any_gt (vector unsigned __int128, vector unsigned __int128); 20753 int vec_any_lt (vector signed __int128, vector signed __int128); 20754 int vec_any_lt (vector unsigned __int128, vector unsigned __int128); 20755 int vec_any_ge (vector signed __int128, vector signed __int128); 20756 int vec_any_ge (vector unsigned __int128, vector unsigned __int128); 20757 int vec_any_le (vector signed __int128, vector signed __int128); 20758 int vec_any_le (vector unsigned __int128, vector unsigned __int128); 20759 @end smallexample 20760 20761 20762 @node PowerPC Hardware Transactional Memory Built-in Functions 20763 @subsection PowerPC Hardware Transactional Memory Built-in Functions 20764 GCC provides two interfaces for accessing the Hardware Transactional 20765 Memory (HTM) instructions available on some of the PowerPC family 20766 of processors (eg, POWER8). The two interfaces come in a low level 20767 interface, consisting of built-in functions specific to PowerPC and a 20768 higher level interface consisting of inline functions that are common 20769 between PowerPC and S/390. 20770 20771 @subsubsection PowerPC HTM Low Level Built-in Functions 20772 20773 The following low level built-in functions are available with 20774 @option{-mhtm} or @option{-mcpu=CPU} where CPU is `power8' or later. 20775 They all generate the machine instruction that is part of the name. 20776 20777 The HTM builtins (with the exception of @code{__builtin_tbegin}) return 20778 the full 4-bit condition register value set by their associated hardware 20779 instruction. The header file @code{htmintrin.h} defines some macros that can 20780 be used to decipher the return value. The @code{__builtin_tbegin} builtin 20781 returns a simple @code{true} or @code{false} value depending on whether a transaction was 20782 successfully started or not. The arguments of the builtins match exactly the 20783 type and order of the associated hardware instruction's operands, except for 20784 the @code{__builtin_tcheck} builtin, which does not take any input arguments. 20785 Refer to the ISA manual for a description of each instruction's operands. 20786 20787 @smallexample 20788 unsigned int __builtin_tbegin (unsigned int); 20789 unsigned int __builtin_tend (unsigned int); 20790 20791 unsigned int __builtin_tabort (unsigned int); 20792 unsigned int __builtin_tabortdc (unsigned int, unsigned int, unsigned int); 20793 unsigned int __builtin_tabortdci (unsigned int, unsigned int, int); 20794 unsigned int __builtin_tabortwc (unsigned int, unsigned int, unsigned int); 20795 unsigned int __builtin_tabortwci (unsigned int, unsigned int, int); 20796 20797 unsigned int __builtin_tcheck (void); 20798 unsigned int __builtin_treclaim (unsigned int); 20799 unsigned int __builtin_trechkpt (void); 20800 unsigned int __builtin_tsr (unsigned int); 20801 @end smallexample 20802 20803 In addition to the above HTM built-ins, we have added built-ins for 20804 some common extended mnemonics of the HTM instructions: 20805 20806 @smallexample 20807 unsigned int __builtin_tendall (void); 20808 unsigned int __builtin_tresume (void); 20809 unsigned int __builtin_tsuspend (void); 20810 @end smallexample 20811 20812 Note that the semantics of the above HTM builtins are required to mimic 20813 the locking semantics used for critical sections. Builtins that are used 20814 to create a new transaction or restart a suspended transaction must have 20815 lock acquisition like semantics while those builtins that end or suspend a 20816 transaction must have lock release like semantics. Specifically, this must 20817 mimic lock semantics as specified by C++11, for example: Lock acquisition is 20818 as-if an execution of __atomic_exchange_n(&globallock,1,__ATOMIC_ACQUIRE) 20819 that returns 0, and lock release is as-if an execution of 20820 __atomic_store(&globallock,0,__ATOMIC_RELEASE), with globallock being an 20821 implicit implementation-defined lock used for all transactions. The HTM 20822 instructions associated with with the builtins inherently provide the 20823 correct acquisition and release hardware barriers required. However, 20824 the compiler must also be prohibited from moving loads and stores across 20825 the builtins in a way that would violate their semantics. This has been 20826 accomplished by adding memory barriers to the associated HTM instructions 20827 (which is a conservative approach to provide acquire and release semantics). 20828 Earlier versions of the compiler did not treat the HTM instructions as 20829 memory barriers. A @code{__TM_FENCE__} macro has been added, which can 20830 be used to determine whether the current compiler treats HTM instructions 20831 as memory barriers or not. This allows the user to explicitly add memory 20832 barriers to their code when using an older version of the compiler. 20833 20834 The following set of built-in functions are available to gain access 20835 to the HTM specific special purpose registers. 20836 20837 @smallexample 20838 unsigned long __builtin_get_texasr (void); 20839 unsigned long __builtin_get_texasru (void); 20840 unsigned long __builtin_get_tfhar (void); 20841 unsigned long __builtin_get_tfiar (void); 20842 20843 void __builtin_set_texasr (unsigned long); 20844 void __builtin_set_texasru (unsigned long); 20845 void __builtin_set_tfhar (unsigned long); 20846 void __builtin_set_tfiar (unsigned long); 20847 @end smallexample 20848 20849 Example usage of these low level built-in functions may look like: 20850 20851 @smallexample 20852 #include <htmintrin.h> 20853 20854 int num_retries = 10; 20855 20856 while (1) 20857 @{ 20858 if (__builtin_tbegin (0)) 20859 @{ 20860 /* Transaction State Initiated. */ 20861 if (is_locked (lock)) 20862 __builtin_tabort (0); 20863 ... transaction code... 20864 __builtin_tend (0); 20865 break; 20866 @} 20867 else 20868 @{ 20869 /* Transaction State Failed. Use locks if the transaction 20870 failure is "persistent" or we've tried too many times. */ 20871 if (num_retries-- <= 0 20872 || _TEXASRU_FAILURE_PERSISTENT (__builtin_get_texasru ())) 20873 @{ 20874 acquire_lock (lock); 20875 ... non transactional fallback path... 20876 release_lock (lock); 20877 break; 20878 @} 20879 @} 20880 @} 20881 @end smallexample 20882 20883 One final built-in function has been added that returns the value of 20884 the 2-bit Transaction State field of the Machine Status Register (MSR) 20885 as stored in @code{CR0}. 20886 20887 @smallexample 20888 unsigned long __builtin_ttest (void) 20889 @end smallexample 20890 20891 This built-in can be used to determine the current transaction state 20892 using the following code example: 20893 20894 @smallexample 20895 #include <htmintrin.h> 20896 20897 unsigned char tx_state = _HTM_STATE (__builtin_ttest ()); 20898 20899 if (tx_state == _HTM_TRANSACTIONAL) 20900 @{ 20901 /* Code to use in transactional state. */ 20902 @} 20903 else if (tx_state == _HTM_NONTRANSACTIONAL) 20904 @{ 20905 /* Code to use in non-transactional state. */ 20906 @} 20907 else if (tx_state == _HTM_SUSPENDED) 20908 @{ 20909 /* Code to use in transaction suspended state. */ 20910 @} 20911 @end smallexample 20912 20913 @subsubsection PowerPC HTM High Level Inline Functions 20914 20915 The following high level HTM interface is made available by including 20916 @code{<htmxlintrin.h>} and using @option{-mhtm} or @option{-mcpu=CPU} 20917 where CPU is `power8' or later. This interface is common between PowerPC 20918 and S/390, allowing users to write one HTM source implementation that 20919 can be compiled and executed on either system. 20920 20921 @smallexample 20922 long __TM_simple_begin (void); 20923 long __TM_begin (void* const TM_buff); 20924 long __TM_end (void); 20925 void __TM_abort (void); 20926 void __TM_named_abort (unsigned char const code); 20927 void __TM_resume (void); 20928 void __TM_suspend (void); 20929 20930 long __TM_is_user_abort (void* const TM_buff); 20931 long __TM_is_named_user_abort (void* const TM_buff, unsigned char *code); 20932 long __TM_is_illegal (void* const TM_buff); 20933 long __TM_is_footprint_exceeded (void* const TM_buff); 20934 long __TM_nesting_depth (void* const TM_buff); 20935 long __TM_is_nested_too_deep(void* const TM_buff); 20936 long __TM_is_conflict(void* const TM_buff); 20937 long __TM_is_failure_persistent(void* const TM_buff); 20938 long __TM_failure_address(void* const TM_buff); 20939 long long __TM_failure_code(void* const TM_buff); 20940 @end smallexample 20941 20942 Using these common set of HTM inline functions, we can create 20943 a more portable version of the HTM example in the previous 20944 section that will work on either PowerPC or S/390: 20945 20946 @smallexample 20947 #include <htmxlintrin.h> 20948 20949 int num_retries = 10; 20950 TM_buff_type TM_buff; 20951 20952 while (1) 20953 @{ 20954 if (__TM_begin (TM_buff) == _HTM_TBEGIN_STARTED) 20955 @{ 20956 /* Transaction State Initiated. */ 20957 if (is_locked (lock)) 20958 __TM_abort (); 20959 ... transaction code... 20960 __TM_end (); 20961 break; 20962 @} 20963 else 20964 @{ 20965 /* Transaction State Failed. Use locks if the transaction 20966 failure is "persistent" or we've tried too many times. */ 20967 if (num_retries-- <= 0 20968 || __TM_is_failure_persistent (TM_buff)) 20969 @{ 20970 acquire_lock (lock); 20971 ... non transactional fallback path... 20972 release_lock (lock); 20973 break; 20974 @} 20975 @} 20976 @} 20977 @end smallexample 20978 20979 @node PowerPC Atomic Memory Operation Functions 20980 @subsection PowerPC Atomic Memory Operation Functions 20981 ISA 3.0 of the PowerPC added new atomic memory operation (amo) 20982 instructions. GCC provides support for these instructions in 64-bit 20983 environments. All of the functions are declared in the include file 20984 @code{amo.h}. 20985 20986 The functions supported are: 20987 20988 @smallexample 20989 #include <amo.h> 20990 20991 uint32_t amo_lwat_add (uint32_t *, uint32_t); 20992 uint32_t amo_lwat_xor (uint32_t *, uint32_t); 20993 uint32_t amo_lwat_ior (uint32_t *, uint32_t); 20994 uint32_t amo_lwat_and (uint32_t *, uint32_t); 20995 uint32_t amo_lwat_umax (uint32_t *, uint32_t); 20996 uint32_t amo_lwat_umin (uint32_t *, uint32_t); 20997 uint32_t amo_lwat_swap (uint32_t *, uint32_t); 20998 20999 int32_t amo_lwat_sadd (int32_t *, int32_t); 21000 int32_t amo_lwat_smax (int32_t *, int32_t); 21001 int32_t amo_lwat_smin (int32_t *, int32_t); 21002 int32_t amo_lwat_sswap (int32_t *, int32_t); 21003 21004 uint64_t amo_ldat_add (uint64_t *, uint64_t); 21005 uint64_t amo_ldat_xor (uint64_t *, uint64_t); 21006 uint64_t amo_ldat_ior (uint64_t *, uint64_t); 21007 uint64_t amo_ldat_and (uint64_t *, uint64_t); 21008 uint64_t amo_ldat_umax (uint64_t *, uint64_t); 21009 uint64_t amo_ldat_umin (uint64_t *, uint64_t); 21010 uint64_t amo_ldat_swap (uint64_t *, uint64_t); 21011 21012 int64_t amo_ldat_sadd (int64_t *, int64_t); 21013 int64_t amo_ldat_smax (int64_t *, int64_t); 21014 int64_t amo_ldat_smin (int64_t *, int64_t); 21015 int64_t amo_ldat_sswap (int64_t *, int64_t); 21016 21017 void amo_stwat_add (uint32_t *, uint32_t); 21018 void amo_stwat_xor (uint32_t *, uint32_t); 21019 void amo_stwat_ior (uint32_t *, uint32_t); 21020 void amo_stwat_and (uint32_t *, uint32_t); 21021 void amo_stwat_umax (uint32_t *, uint32_t); 21022 void amo_stwat_umin (uint32_t *, uint32_t); 21023 21024 void amo_stwat_sadd (int32_t *, int32_t); 21025 void amo_stwat_smax (int32_t *, int32_t); 21026 void amo_stwat_smin (int32_t *, int32_t); 21027 21028 void amo_stdat_add (uint64_t *, uint64_t); 21029 void amo_stdat_xor (uint64_t *, uint64_t); 21030 void amo_stdat_ior (uint64_t *, uint64_t); 21031 void amo_stdat_and (uint64_t *, uint64_t); 21032 void amo_stdat_umax (uint64_t *, uint64_t); 21033 void amo_stdat_umin (uint64_t *, uint64_t); 21034 21035 void amo_stdat_sadd (int64_t *, int64_t); 21036 void amo_stdat_smax (int64_t *, int64_t); 21037 void amo_stdat_smin (int64_t *, int64_t); 21038 @end smallexample 21039 21040 @node PowerPC Matrix-Multiply Assist Built-in Functions 21041 @subsection PowerPC Matrix-Multiply Assist Built-in Functions 21042 ISA 3.1 of the PowerPC added new Matrix-Multiply Assist (MMA) instructions. 21043 GCC provides support for these instructions through the following built-in 21044 functions which are enabled with the @code{-mmma} option. The vec_t type 21045 below is defined to be a normal vector unsigned char type. The uint2, uint4 21046 and uint8 parameters are 2-bit, 4-bit and 8-bit unsigned integer constants 21047 respectively. The compiler will verify that they are constants and that 21048 their values are within range. 21049 21050 The built-in functions supported are: 21051 21052 @smallexample 21053 void __builtin_mma_xvi4ger8 (__vector_quad *, vec_t, vec_t); 21054 void __builtin_mma_xvi8ger4 (__vector_quad *, vec_t, vec_t); 21055 void __builtin_mma_xvi16ger2 (__vector_quad *, vec_t, vec_t); 21056 void __builtin_mma_xvi16ger2s (__vector_quad *, vec_t, vec_t); 21057 void __builtin_mma_xvf16ger2 (__vector_quad *, vec_t, vec_t); 21058 void __builtin_mma_xvbf16ger2 (__vector_quad *, vec_t, vec_t); 21059 void __builtin_mma_xvf32ger (__vector_quad *, vec_t, vec_t); 21060 21061 void __builtin_mma_xvi4ger8pp (__vector_quad *, vec_t, vec_t); 21062 void __builtin_mma_xvi8ger4pp (__vector_quad *, vec_t, vec_t); 21063 void __builtin_mma_xvi8ger4spp(__vector_quad *, vec_t, vec_t); 21064 void __builtin_mma_xvi16ger2pp (__vector_quad *, vec_t, vec_t); 21065 void __builtin_mma_xvi16ger2spp (__vector_quad *, vec_t, vec_t); 21066 void __builtin_mma_xvf16ger2pp (__vector_quad *, vec_t, vec_t); 21067 void __builtin_mma_xvf16ger2pn (__vector_quad *, vec_t, vec_t); 21068 void __builtin_mma_xvf16ger2np (__vector_quad *, vec_t, vec_t); 21069 void __builtin_mma_xvf16ger2nn (__vector_quad *, vec_t, vec_t); 21070 void __builtin_mma_xvbf16ger2pp (__vector_quad *, vec_t, vec_t); 21071 void __builtin_mma_xvbf16ger2pn (__vector_quad *, vec_t, vec_t); 21072 void __builtin_mma_xvbf16ger2np (__vector_quad *, vec_t, vec_t); 21073 void __builtin_mma_xvbf16ger2nn (__vector_quad *, vec_t, vec_t); 21074 void __builtin_mma_xvf32gerpp (__vector_quad *, vec_t, vec_t); 21075 void __builtin_mma_xvf32gerpn (__vector_quad *, vec_t, vec_t); 21076 void __builtin_mma_xvf32gernp (__vector_quad *, vec_t, vec_t); 21077 void __builtin_mma_xvf32gernn (__vector_quad *, vec_t, vec_t); 21078 21079 void __builtin_mma_pmxvi4ger8 (__vector_quad *, vec_t, vec_t, uint4, uint4, uint8); 21080 void __builtin_mma_pmxvi4ger8pp (__vector_quad *, vec_t, vec_t, uint4, uint4, uint8); 21081 21082 void __builtin_mma_pmxvi8ger4 (__vector_quad *, vec_t, vec_t, uint4, uint4, uint4); 21083 void __builtin_mma_pmxvi8ger4pp (__vector_quad *, vec_t, vec_t, uint4, uint4, uint4); 21084 void __builtin_mma_pmxvi8ger4spp(__vector_quad *, vec_t, vec_t, uint4, uint4, uint4); 21085 21086 void __builtin_mma_pmxvi16ger2 (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2); 21087 void __builtin_mma_pmxvi16ger2s (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2); 21088 void __builtin_mma_pmxvf16ger2 (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2); 21089 void __builtin_mma_pmxvbf16ger2 (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2); 21090 21091 void __builtin_mma_pmxvi16ger2pp (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2); 21092 void __builtin_mma_pmxvi16ger2spp (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2); 21093 void __builtin_mma_pmxvf16ger2pp (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2); 21094 void __builtin_mma_pmxvf16ger2pn (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2); 21095 void __builtin_mma_pmxvf16ger2np (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2); 21096 void __builtin_mma_pmxvf16ger2nn (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2); 21097 void __builtin_mma_pmxvbf16ger2pp (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2); 21098 void __builtin_mma_pmxvbf16ger2pn (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2); 21099 void __builtin_mma_pmxvbf16ger2np (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2); 21100 void __builtin_mma_pmxvbf16ger2nn (__vector_quad *, vec_t, vec_t, uint4, uint4, uint2); 21101 21102 void __builtin_mma_pmxvf32ger (__vector_quad *, vec_t, vec_t, uint4, uint4); 21103 void __builtin_mma_pmxvf32gerpp (__vector_quad *, vec_t, vec_t, uint4, uint4); 21104 void __builtin_mma_pmxvf32gerpn (__vector_quad *, vec_t, vec_t, uint4, uint4); 21105 void __builtin_mma_pmxvf32gernp (__vector_quad *, vec_t, vec_t, uint4, uint4); 21106 void __builtin_mma_pmxvf32gernn (__vector_quad *, vec_t, vec_t, uint4, uint4); 21107 21108 void __builtin_mma_xvf64ger (__vector_quad *, __vector_pair, vec_t); 21109 void __builtin_mma_xvf64gerpp (__vector_quad *, __vector_pair, vec_t); 21110 void __builtin_mma_xvf64gerpn (__vector_quad *, __vector_pair, vec_t); 21111 void __builtin_mma_xvf64gernp (__vector_quad *, __vector_pair, vec_t); 21112 void __builtin_mma_xvf64gernn (__vector_quad *, __vector_pair, vec_t); 21113 21114 void __builtin_mma_pmxvf64ger (__vector_quad *, __vector_pair, vec_t, uint4, uint2); 21115 void __builtin_mma_pmxvf64gerpp (__vector_quad *, __vector_pair, vec_t, uint4, uint2); 21116 void __builtin_mma_pmxvf64gerpn (__vector_quad *, __vector_pair, vec_t, uint4, uint2); 21117 void __builtin_mma_pmxvf64gernp (__vector_quad *, __vector_pair, vec_t, uint4, uint2); 21118 void __builtin_mma_pmxvf64gernn (__vector_quad *, __vector_pair, vec_t, uint4, uint2); 21119 21120 void __builtin_mma_xxmtacc (__vector_quad *); 21121 void __builtin_mma_xxmfacc (__vector_quad *); 21122 void __builtin_mma_xxsetaccz (__vector_quad *); 21123 21124 void __builtin_mma_build_acc (__vector_quad *, vec_t, vec_t, vec_t, vec_t); 21125 void __builtin_mma_disassemble_acc (void *, __vector_quad *); 21126 21127 void __builtin_vsx_build_pair (__vector_pair *, vec_t, vec_t); 21128 void __builtin_vsx_disassemble_pair (void *, __vector_pair *); 21129 21130 vec_t __builtin_vsx_xvcvspbf16 (vec_t); 21131 vec_t __builtin_vsx_xvcvbf16spn (vec_t); 21132 21133 __vector_pair __builtin_vsx_lxvp (size_t, __vector_pair *); 21134 void __builtin_vsx_stxvp (__vector_pair, size_t, __vector_pair *); 21135 @end smallexample 21136 21137 @node PRU Built-in Functions 21138 @subsection PRU Built-in Functions 21139 21140 GCC provides a couple of special builtin functions to aid in utilizing 21141 special PRU instructions. 21142 21143 The built-in functions supported are: 21144 21145 @table @code 21146 @item __delay_cycles (long long @var{cycles}) 21147 This inserts an instruction sequence that takes exactly @var{cycles} 21148 cycles (between 0 and 0xffffffff) to complete. The inserted sequence 21149 may use jumps, loops, or no-ops, and does not interfere with any other 21150 instructions. Note that @var{cycles} must be a compile-time constant 21151 integer - that is, you must pass a number, not a variable that may be 21152 optimized to a constant later. The number of cycles delayed by this 21153 builtin is exact. 21154 21155 @item __halt (void) 21156 This inserts a HALT instruction to stop processor execution. 21157 21158 @item unsigned int __lmbd (unsigned int @var{wordval}, unsigned int @var{bitval}) 21159 This inserts LMBD instruction to calculate the left-most bit with value 21160 @var{bitval} in value @var{wordval}. Only the least significant bit 21161 of @var{bitval} is taken into account. 21162 @end table 21163 21164 @node RISC-V Built-in Functions 21165 @subsection RISC-V Built-in Functions 21166 21167 These built-in functions are available for the RISC-V family of 21168 processors. 21169 21170 @deftypefn {Built-in Function} {void *} __builtin_thread_pointer (void) 21171 Returns the value that is currently set in the @samp{tp} register. 21172 @end deftypefn 21173 21174 @node RX Built-in Functions 21175 @subsection RX Built-in Functions 21176 GCC supports some of the RX instructions which cannot be expressed in 21177 the C programming language via the use of built-in functions. The 21178 following functions are supported: 21179 21180 @deftypefn {Built-in Function} void __builtin_rx_brk (void) 21181 Generates the @code{brk} machine instruction. 21182 @end deftypefn 21183 21184 @deftypefn {Built-in Function} void __builtin_rx_clrpsw (int) 21185 Generates the @code{clrpsw} machine instruction to clear the specified 21186 bit in the processor status word. 21187 @end deftypefn 21188 21189 @deftypefn {Built-in Function} void __builtin_rx_int (int) 21190 Generates the @code{int} machine instruction to generate an interrupt 21191 with the specified value. 21192 @end deftypefn 21193 21194 @deftypefn {Built-in Function} void __builtin_rx_machi (int, int) 21195 Generates the @code{machi} machine instruction to add the result of 21196 multiplying the top 16 bits of the two arguments into the 21197 accumulator. 21198 @end deftypefn 21199 21200 @deftypefn {Built-in Function} void __builtin_rx_maclo (int, int) 21201 Generates the @code{maclo} machine instruction to add the result of 21202 multiplying the bottom 16 bits of the two arguments into the 21203 accumulator. 21204 @end deftypefn 21205 21206 @deftypefn {Built-in Function} void __builtin_rx_mulhi (int, int) 21207 Generates the @code{mulhi} machine instruction to place the result of 21208 multiplying the top 16 bits of the two arguments into the 21209 accumulator. 21210 @end deftypefn 21211 21212 @deftypefn {Built-in Function} void __builtin_rx_mullo (int, int) 21213 Generates the @code{mullo} machine instruction to place the result of 21214 multiplying the bottom 16 bits of the two arguments into the 21215 accumulator. 21216 @end deftypefn 21217 21218 @deftypefn {Built-in Function} int __builtin_rx_mvfachi (void) 21219 Generates the @code{mvfachi} machine instruction to read the top 21220 32 bits of the accumulator. 21221 @end deftypefn 21222 21223 @deftypefn {Built-in Function} int __builtin_rx_mvfacmi (void) 21224 Generates the @code{mvfacmi} machine instruction to read the middle 21225 32 bits of the accumulator. 21226 @end deftypefn 21227 21228 @deftypefn {Built-in Function} int __builtin_rx_mvfc (int) 21229 Generates the @code{mvfc} machine instruction which reads the control 21230 register specified in its argument and returns its value. 21231 @end deftypefn 21232 21233 @deftypefn {Built-in Function} void __builtin_rx_mvtachi (int) 21234 Generates the @code{mvtachi} machine instruction to set the top 21235 32 bits of the accumulator. 21236 @end deftypefn 21237 21238 @deftypefn {Built-in Function} void __builtin_rx_mvtaclo (int) 21239 Generates the @code{mvtaclo} machine instruction to set the bottom 21240 32 bits of the accumulator. 21241 @end deftypefn 21242 21243 @deftypefn {Built-in Function} void __builtin_rx_mvtc (int reg, int val) 21244 Generates the @code{mvtc} machine instruction which sets control 21245 register number @code{reg} to @code{val}. 21246 @end deftypefn 21247 21248 @deftypefn {Built-in Function} void __builtin_rx_mvtipl (int) 21249 Generates the @code{mvtipl} machine instruction set the interrupt 21250 priority level. 21251 @end deftypefn 21252 21253 @deftypefn {Built-in Function} void __builtin_rx_racw (int) 21254 Generates the @code{racw} machine instruction to round the accumulator 21255 according to the specified mode. 21256 @end deftypefn 21257 21258 @deftypefn {Built-in Function} int __builtin_rx_revw (int) 21259 Generates the @code{revw} machine instruction which swaps the bytes in 21260 the argument so that bits 0--7 now occupy bits 8--15 and vice versa, 21261 and also bits 16--23 occupy bits 24--31 and vice versa. 21262 @end deftypefn 21263 21264 @deftypefn {Built-in Function} void __builtin_rx_rmpa (void) 21265 Generates the @code{rmpa} machine instruction which initiates a 21266 repeated multiply and accumulate sequence. 21267 @end deftypefn 21268 21269 @deftypefn {Built-in Function} void __builtin_rx_round (float) 21270 Generates the @code{round} machine instruction which returns the 21271 floating-point argument rounded according to the current rounding mode 21272 set in the floating-point status word register. 21273 @end deftypefn 21274 21275 @deftypefn {Built-in Function} int __builtin_rx_sat (int) 21276 Generates the @code{sat} machine instruction which returns the 21277 saturated value of the argument. 21278 @end deftypefn 21279 21280 @deftypefn {Built-in Function} void __builtin_rx_setpsw (int) 21281 Generates the @code{setpsw} machine instruction to set the specified 21282 bit in the processor status word. 21283 @end deftypefn 21284 21285 @deftypefn {Built-in Function} void __builtin_rx_wait (void) 21286 Generates the @code{wait} machine instruction. 21287 @end deftypefn 21288 21289 @node S/390 System z Built-in Functions 21290 @subsection S/390 System z Built-in Functions 21291 @deftypefn {Built-in Function} int __builtin_tbegin (void*) 21292 Generates the @code{tbegin} machine instruction starting a 21293 non-constrained hardware transaction. If the parameter is non-NULL the 21294 memory area is used to store the transaction diagnostic buffer and 21295 will be passed as first operand to @code{tbegin}. This buffer can be 21296 defined using the @code{struct __htm_tdb} C struct defined in 21297 @code{htmintrin.h} and must reside on a double-word boundary. The 21298 second tbegin operand is set to @code{0xff0c}. This enables 21299 save/restore of all GPRs and disables aborts for FPR and AR 21300 manipulations inside the transaction body. The condition code set by 21301 the tbegin instruction is returned as integer value. The tbegin 21302 instruction by definition overwrites the content of all FPRs. The 21303 compiler will generate code which saves and restores the FPRs. For 21304 soft-float code it is recommended to used the @code{*_nofloat} 21305 variant. In order to prevent a TDB from being written it is required 21306 to pass a constant zero value as parameter. Passing a zero value 21307 through a variable is not sufficient. Although modifications of 21308 access registers inside the transaction will not trigger an 21309 transaction abort it is not supported to actually modify them. Access 21310 registers do not get saved when entering a transaction. They will have 21311 undefined state when reaching the abort code. 21312 @end deftypefn 21313 21314 Macros for the possible return codes of tbegin are defined in the 21315 @code{htmintrin.h} header file: 21316 21317 @table @code 21318 @item _HTM_TBEGIN_STARTED 21319 @code{tbegin} has been executed as part of normal processing. The 21320 transaction body is supposed to be executed. 21321 @item _HTM_TBEGIN_INDETERMINATE 21322 The transaction was aborted due to an indeterminate condition which 21323 might be persistent. 21324 @item _HTM_TBEGIN_TRANSIENT 21325 The transaction aborted due to a transient failure. The transaction 21326 should be re-executed in that case. 21327 @item _HTM_TBEGIN_PERSISTENT 21328 The transaction aborted due to a persistent failure. Re-execution 21329 under same circumstances will not be productive. 21330 @end table 21331 21332 @defmac _HTM_FIRST_USER_ABORT_CODE 21333 The @code{_HTM_FIRST_USER_ABORT_CODE} defined in @code{htmintrin.h} 21334 specifies the first abort code which can be used for 21335 @code{__builtin_tabort}. Values below this threshold are reserved for 21336 machine use. 21337 @end defmac 21338 21339 @deftp {Data type} {struct __htm_tdb} 21340 The @code{struct __htm_tdb} defined in @code{htmintrin.h} describes 21341 the structure of the transaction diagnostic block as specified in the 21342 Principles of Operation manual chapter 5-91. 21343 @end deftp 21344 21345 @deftypefn {Built-in Function} int __builtin_tbegin_nofloat (void*) 21346 Same as @code{__builtin_tbegin} but without FPR saves and restores. 21347 Using this variant in code making use of FPRs will leave the FPRs in 21348 undefined state when entering the transaction abort handler code. 21349 @end deftypefn 21350 21351 @deftypefn {Built-in Function} int __builtin_tbegin_retry (void*, int) 21352 In addition to @code{__builtin_tbegin} a loop for transient failures 21353 is generated. If tbegin returns a condition code of 2 the transaction 21354 will be retried as often as specified in the second argument. The 21355 perform processor assist instruction is used to tell the CPU about the 21356 number of fails so far. 21357 @end deftypefn 21358 21359 @deftypefn {Built-in Function} int __builtin_tbegin_retry_nofloat (void*, int) 21360 Same as @code{__builtin_tbegin_retry} but without FPR saves and 21361 restores. Using this variant in code making use of FPRs will leave 21362 the FPRs in undefined state when entering the transaction abort 21363 handler code. 21364 @end deftypefn 21365 21366 @deftypefn {Built-in Function} void __builtin_tbeginc (void) 21367 Generates the @code{tbeginc} machine instruction starting a constrained 21368 hardware transaction. The second operand is set to @code{0xff08}. 21369 @end deftypefn 21370 21371 @deftypefn {Built-in Function} int __builtin_tend (void) 21372 Generates the @code{tend} machine instruction finishing a transaction 21373 and making the changes visible to other threads. The condition code 21374 generated by tend is returned as integer value. 21375 @end deftypefn 21376 21377 @deftypefn {Built-in Function} void __builtin_tabort (int) 21378 Generates the @code{tabort} machine instruction with the specified 21379 abort code. Abort codes from 0 through 255 are reserved and will 21380 result in an error message. 21381 @end deftypefn 21382 21383 @deftypefn {Built-in Function} void __builtin_tx_assist (int) 21384 Generates the @code{ppa rX,rY,1} machine instruction. Where the 21385 integer parameter is loaded into rX and a value of zero is loaded into 21386 rY. The integer parameter specifies the number of times the 21387 transaction repeatedly aborted. 21388 @end deftypefn 21389 21390 @deftypefn {Built-in Function} int __builtin_tx_nesting_depth (void) 21391 Generates the @code{etnd} machine instruction. The current nesting 21392 depth is returned as integer value. For a nesting depth of 0 the code 21393 is not executed as part of an transaction. 21394 @end deftypefn 21395 21396 @deftypefn {Built-in Function} void __builtin_non_tx_store (uint64_t *, uint64_t) 21397 21398 Generates the @code{ntstg} machine instruction. The second argument 21399 is written to the first arguments location. The store operation will 21400 not be rolled-back in case of an transaction abort. 21401 @end deftypefn 21402 21403 @node SH Built-in Functions 21404 @subsection SH Built-in Functions 21405 The following built-in functions are supported on the SH1, SH2, SH3 and SH4 21406 families of processors: 21407 21408 @deftypefn {Built-in Function} {void} __builtin_set_thread_pointer (void *@var{ptr}) 21409 Sets the @samp{GBR} register to the specified value @var{ptr}. This is usually 21410 used by system code that manages threads and execution contexts. The compiler 21411 normally does not generate code that modifies the contents of @samp{GBR} and 21412 thus the value is preserved across function calls. Changing the @samp{GBR} 21413 value in user code must be done with caution, since the compiler might use 21414 @samp{GBR} in order to access thread local variables. 21415 21416 @end deftypefn 21417 21418 @deftypefn {Built-in Function} {void *} __builtin_thread_pointer (void) 21419 Returns the value that is currently set in the @samp{GBR} register. 21420 Memory loads and stores that use the thread pointer as a base address are 21421 turned into @samp{GBR} based displacement loads and stores, if possible. 21422 For example: 21423 @smallexample 21424 struct my_tcb 21425 @{ 21426 int a, b, c, d, e; 21427 @}; 21428 21429 int get_tcb_value (void) 21430 @{ 21431 // Generate @samp{mov.l @@(8,gbr),r0} instruction 21432 return ((my_tcb*)__builtin_thread_pointer ())->c; 21433 @} 21434 21435 @end smallexample 21436 @end deftypefn 21437 21438 @deftypefn {Built-in Function} {unsigned int} __builtin_sh_get_fpscr (void) 21439 Returns the value that is currently set in the @samp{FPSCR} register. 21440 @end deftypefn 21441 21442 @deftypefn {Built-in Function} {void} __builtin_sh_set_fpscr (unsigned int @var{val}) 21443 Sets the @samp{FPSCR} register to the specified value @var{val}, while 21444 preserving the current values of the FR, SZ and PR bits. 21445 @end deftypefn 21446 21447 @node SPARC VIS Built-in Functions 21448 @subsection SPARC VIS Built-in Functions 21449 21450 GCC supports SIMD operations on the SPARC using both the generic vector 21451 extensions (@pxref{Vector Extensions}) as well as built-in functions for 21452 the SPARC Visual Instruction Set (VIS). When you use the @option{-mvis} 21453 switch, the VIS extension is exposed as the following built-in functions: 21454 21455 @smallexample 21456 typedef int v1si __attribute__ ((vector_size (4))); 21457 typedef int v2si __attribute__ ((vector_size (8))); 21458 typedef short v4hi __attribute__ ((vector_size (8))); 21459 typedef short v2hi __attribute__ ((vector_size (4))); 21460 typedef unsigned char v8qi __attribute__ ((vector_size (8))); 21461 typedef unsigned char v4qi __attribute__ ((vector_size (4))); 21462 21463 void __builtin_vis_write_gsr (int64_t); 21464 int64_t __builtin_vis_read_gsr (void); 21465 21466 void * __builtin_vis_alignaddr (void *, long); 21467 void * __builtin_vis_alignaddrl (void *, long); 21468 int64_t __builtin_vis_faligndatadi (int64_t, int64_t); 21469 v2si __builtin_vis_faligndatav2si (v2si, v2si); 21470 v4hi __builtin_vis_faligndatav4hi (v4si, v4si); 21471 v8qi __builtin_vis_faligndatav8qi (v8qi, v8qi); 21472 21473 v4hi __builtin_vis_fexpand (v4qi); 21474 21475 v4hi __builtin_vis_fmul8x16 (v4qi, v4hi); 21476 v4hi __builtin_vis_fmul8x16au (v4qi, v2hi); 21477 v4hi __builtin_vis_fmul8x16al (v4qi, v2hi); 21478 v4hi __builtin_vis_fmul8sux16 (v8qi, v4hi); 21479 v4hi __builtin_vis_fmul8ulx16 (v8qi, v4hi); 21480 v2si __builtin_vis_fmuld8sux16 (v4qi, v2hi); 21481 v2si __builtin_vis_fmuld8ulx16 (v4qi, v2hi); 21482 21483 v4qi __builtin_vis_fpack16 (v4hi); 21484 v8qi __builtin_vis_fpack32 (v2si, v8qi); 21485 v2hi __builtin_vis_fpackfix (v2si); 21486 v8qi __builtin_vis_fpmerge (v4qi, v4qi); 21487 21488 int64_t __builtin_vis_pdist (v8qi, v8qi, int64_t); 21489 21490 long __builtin_vis_edge8 (void *, void *); 21491 long __builtin_vis_edge8l (void *, void *); 21492 long __builtin_vis_edge16 (void *, void *); 21493 long __builtin_vis_edge16l (void *, void *); 21494 long __builtin_vis_edge32 (void *, void *); 21495 long __builtin_vis_edge32l (void *, void *); 21496 21497 long __builtin_vis_fcmple16 (v4hi, v4hi); 21498 long __builtin_vis_fcmple32 (v2si, v2si); 21499 long __builtin_vis_fcmpne16 (v4hi, v4hi); 21500 long __builtin_vis_fcmpne32 (v2si, v2si); 21501 long __builtin_vis_fcmpgt16 (v4hi, v4hi); 21502 long __builtin_vis_fcmpgt32 (v2si, v2si); 21503 long __builtin_vis_fcmpeq16 (v4hi, v4hi); 21504 long __builtin_vis_fcmpeq32 (v2si, v2si); 21505 21506 v4hi __builtin_vis_fpadd16 (v4hi, v4hi); 21507 v2hi __builtin_vis_fpadd16s (v2hi, v2hi); 21508 v2si __builtin_vis_fpadd32 (v2si, v2si); 21509 v1si __builtin_vis_fpadd32s (v1si, v1si); 21510 v4hi __builtin_vis_fpsub16 (v4hi, v4hi); 21511 v2hi __builtin_vis_fpsub16s (v2hi, v2hi); 21512 v2si __builtin_vis_fpsub32 (v2si, v2si); 21513 v1si __builtin_vis_fpsub32s (v1si, v1si); 21514 21515 long __builtin_vis_array8 (long, long); 21516 long __builtin_vis_array16 (long, long); 21517 long __builtin_vis_array32 (long, long); 21518 @end smallexample 21519 21520 When you use the @option{-mvis2} switch, the VIS version 2.0 built-in 21521 functions also become available: 21522 21523 @smallexample 21524 long __builtin_vis_bmask (long, long); 21525 int64_t __builtin_vis_bshuffledi (int64_t, int64_t); 21526 v2si __builtin_vis_bshufflev2si (v2si, v2si); 21527 v4hi __builtin_vis_bshufflev2si (v4hi, v4hi); 21528 v8qi __builtin_vis_bshufflev2si (v8qi, v8qi); 21529 21530 long __builtin_vis_edge8n (void *, void *); 21531 long __builtin_vis_edge8ln (void *, void *); 21532 long __builtin_vis_edge16n (void *, void *); 21533 long __builtin_vis_edge16ln (void *, void *); 21534 long __builtin_vis_edge32n (void *, void *); 21535 long __builtin_vis_edge32ln (void *, void *); 21536 @end smallexample 21537 21538 When you use the @option{-mvis3} switch, the VIS version 3.0 built-in 21539 functions also become available: 21540 21541 @smallexample 21542 void __builtin_vis_cmask8 (long); 21543 void __builtin_vis_cmask16 (long); 21544 void __builtin_vis_cmask32 (long); 21545 21546 v4hi __builtin_vis_fchksm16 (v4hi, v4hi); 21547 21548 v4hi __builtin_vis_fsll16 (v4hi, v4hi); 21549 v4hi __builtin_vis_fslas16 (v4hi, v4hi); 21550 v4hi __builtin_vis_fsrl16 (v4hi, v4hi); 21551 v4hi __builtin_vis_fsra16 (v4hi, v4hi); 21552 v2si __builtin_vis_fsll16 (v2si, v2si); 21553 v2si __builtin_vis_fslas16 (v2si, v2si); 21554 v2si __builtin_vis_fsrl16 (v2si, v2si); 21555 v2si __builtin_vis_fsra16 (v2si, v2si); 21556 21557 long __builtin_vis_pdistn (v8qi, v8qi); 21558 21559 v4hi __builtin_vis_fmean16 (v4hi, v4hi); 21560 21561 int64_t __builtin_vis_fpadd64 (int64_t, int64_t); 21562 int64_t __builtin_vis_fpsub64 (int64_t, int64_t); 21563 21564 v4hi __builtin_vis_fpadds16 (v4hi, v4hi); 21565 v2hi __builtin_vis_fpadds16s (v2hi, v2hi); 21566 v4hi __builtin_vis_fpsubs16 (v4hi, v4hi); 21567 v2hi __builtin_vis_fpsubs16s (v2hi, v2hi); 21568 v2si __builtin_vis_fpadds32 (v2si, v2si); 21569 v1si __builtin_vis_fpadds32s (v1si, v1si); 21570 v2si __builtin_vis_fpsubs32 (v2si, v2si); 21571 v1si __builtin_vis_fpsubs32s (v1si, v1si); 21572 21573 long __builtin_vis_fucmple8 (v8qi, v8qi); 21574 long __builtin_vis_fucmpne8 (v8qi, v8qi); 21575 long __builtin_vis_fucmpgt8 (v8qi, v8qi); 21576 long __builtin_vis_fucmpeq8 (v8qi, v8qi); 21577 21578 float __builtin_vis_fhadds (float, float); 21579 double __builtin_vis_fhaddd (double, double); 21580 float __builtin_vis_fhsubs (float, float); 21581 double __builtin_vis_fhsubd (double, double); 21582 float __builtin_vis_fnhadds (float, float); 21583 double __builtin_vis_fnhaddd (double, double); 21584 21585 int64_t __builtin_vis_umulxhi (int64_t, int64_t); 21586 int64_t __builtin_vis_xmulx (int64_t, int64_t); 21587 int64_t __builtin_vis_xmulxhi (int64_t, int64_t); 21588 @end smallexample 21589 21590 When you use the @option{-mvis4} switch, the VIS version 4.0 built-in 21591 functions also become available: 21592 21593 @smallexample 21594 v8qi __builtin_vis_fpadd8 (v8qi, v8qi); 21595 v8qi __builtin_vis_fpadds8 (v8qi, v8qi); 21596 v8qi __builtin_vis_fpaddus8 (v8qi, v8qi); 21597 v4hi __builtin_vis_fpaddus16 (v4hi, v4hi); 21598 21599 v8qi __builtin_vis_fpsub8 (v8qi, v8qi); 21600 v8qi __builtin_vis_fpsubs8 (v8qi, v8qi); 21601 v8qi __builtin_vis_fpsubus8 (v8qi, v8qi); 21602 v4hi __builtin_vis_fpsubus16 (v4hi, v4hi); 21603 21604 long __builtin_vis_fpcmple8 (v8qi, v8qi); 21605 long __builtin_vis_fpcmpgt8 (v8qi, v8qi); 21606 long __builtin_vis_fpcmpule16 (v4hi, v4hi); 21607 long __builtin_vis_fpcmpugt16 (v4hi, v4hi); 21608 long __builtin_vis_fpcmpule32 (v2si, v2si); 21609 long __builtin_vis_fpcmpugt32 (v2si, v2si); 21610 21611 v8qi __builtin_vis_fpmax8 (v8qi, v8qi); 21612 v4hi __builtin_vis_fpmax16 (v4hi, v4hi); 21613 v2si __builtin_vis_fpmax32 (v2si, v2si); 21614 21615 v8qi __builtin_vis_fpmaxu8 (v8qi, v8qi); 21616 v4hi __builtin_vis_fpmaxu16 (v4hi, v4hi); 21617 v2si __builtin_vis_fpmaxu32 (v2si, v2si); 21618 21619 v8qi __builtin_vis_fpmin8 (v8qi, v8qi); 21620 v4hi __builtin_vis_fpmin16 (v4hi, v4hi); 21621 v2si __builtin_vis_fpmin32 (v2si, v2si); 21622 21623 v8qi __builtin_vis_fpminu8 (v8qi, v8qi); 21624 v4hi __builtin_vis_fpminu16 (v4hi, v4hi); 21625 v2si __builtin_vis_fpminu32 (v2si, v2si); 21626 @end smallexample 21627 21628 When you use the @option{-mvis4b} switch, the VIS version 4.0B 21629 built-in functions also become available: 21630 21631 @smallexample 21632 v8qi __builtin_vis_dictunpack8 (double, int); 21633 v4hi __builtin_vis_dictunpack16 (double, int); 21634 v2si __builtin_vis_dictunpack32 (double, int); 21635 21636 long __builtin_vis_fpcmple8shl (v8qi, v8qi, int); 21637 long __builtin_vis_fpcmpgt8shl (v8qi, v8qi, int); 21638 long __builtin_vis_fpcmpeq8shl (v8qi, v8qi, int); 21639 long __builtin_vis_fpcmpne8shl (v8qi, v8qi, int); 21640 21641 long __builtin_vis_fpcmple16shl (v4hi, v4hi, int); 21642 long __builtin_vis_fpcmpgt16shl (v4hi, v4hi, int); 21643 long __builtin_vis_fpcmpeq16shl (v4hi, v4hi, int); 21644 long __builtin_vis_fpcmpne16shl (v4hi, v4hi, int); 21645 21646 long __builtin_vis_fpcmple32shl (v2si, v2si, int); 21647 long __builtin_vis_fpcmpgt32shl (v2si, v2si, int); 21648 long __builtin_vis_fpcmpeq32shl (v2si, v2si, int); 21649 long __builtin_vis_fpcmpne32shl (v2si, v2si, int); 21650 21651 long __builtin_vis_fpcmpule8shl (v8qi, v8qi, int); 21652 long __builtin_vis_fpcmpugt8shl (v8qi, v8qi, int); 21653 long __builtin_vis_fpcmpule16shl (v4hi, v4hi, int); 21654 long __builtin_vis_fpcmpugt16shl (v4hi, v4hi, int); 21655 long __builtin_vis_fpcmpule32shl (v2si, v2si, int); 21656 long __builtin_vis_fpcmpugt32shl (v2si, v2si, int); 21657 21658 long __builtin_vis_fpcmpde8shl (v8qi, v8qi, int); 21659 long __builtin_vis_fpcmpde16shl (v4hi, v4hi, int); 21660 long __builtin_vis_fpcmpde32shl (v2si, v2si, int); 21661 21662 long __builtin_vis_fpcmpur8shl (v8qi, v8qi, int); 21663 long __builtin_vis_fpcmpur16shl (v4hi, v4hi, int); 21664 long __builtin_vis_fpcmpur32shl (v2si, v2si, int); 21665 @end smallexample 21666 21667 @node TI C6X Built-in Functions 21668 @subsection TI C6X Built-in Functions 21669 21670 GCC provides intrinsics to access certain instructions of the TI C6X 21671 processors. These intrinsics, listed below, are available after 21672 inclusion of the @code{c6x_intrinsics.h} header file. They map directly 21673 to C6X instructions. 21674 21675 @smallexample 21676 int _sadd (int, int); 21677 int _ssub (int, int); 21678 int _sadd2 (int, int); 21679 int _ssub2 (int, int); 21680 long long _mpy2 (int, int); 21681 long long _smpy2 (int, int); 21682 int _add4 (int, int); 21683 int _sub4 (int, int); 21684 int _saddu4 (int, int); 21685 21686 int _smpy (int, int); 21687 int _smpyh (int, int); 21688 int _smpyhl (int, int); 21689 int _smpylh (int, int); 21690 21691 int _sshl (int, int); 21692 int _subc (int, int); 21693 21694 int _avg2 (int, int); 21695 int _avgu4 (int, int); 21696 21697 int _clrr (int, int); 21698 int _extr (int, int); 21699 int _extru (int, int); 21700 int _abs (int); 21701 int _abs2 (int); 21702 @end smallexample 21703 21704 @node TILE-Gx Built-in Functions 21705 @subsection TILE-Gx Built-in Functions 21706 21707 GCC provides intrinsics to access every instruction of the TILE-Gx 21708 processor. The intrinsics are of the form: 21709 21710 @smallexample 21711 21712 unsigned long long __insn_@var{op} (...) 21713 21714 @end smallexample 21715 21716 Where @var{op} is the name of the instruction. Refer to the ISA manual 21717 for the complete list of instructions. 21718 21719 GCC also provides intrinsics to directly access the network registers. 21720 The intrinsics are: 21721 21722 @smallexample 21723 unsigned long long __tile_idn0_receive (void); 21724 unsigned long long __tile_idn1_receive (void); 21725 unsigned long long __tile_udn0_receive (void); 21726 unsigned long long __tile_udn1_receive (void); 21727 unsigned long long __tile_udn2_receive (void); 21728 unsigned long long __tile_udn3_receive (void); 21729 void __tile_idn_send (unsigned long long); 21730 void __tile_udn_send (unsigned long long); 21731 @end smallexample 21732 21733 The intrinsic @code{void __tile_network_barrier (void)} is used to 21734 guarantee that no network operations before it are reordered with 21735 those after it. 21736 21737 @node TILEPro Built-in Functions 21738 @subsection TILEPro Built-in Functions 21739 21740 GCC provides intrinsics to access every instruction of the TILEPro 21741 processor. The intrinsics are of the form: 21742 21743 @smallexample 21744 21745 unsigned __insn_@var{op} (...) 21746 21747 @end smallexample 21748 21749 @noindent 21750 where @var{op} is the name of the instruction. Refer to the ISA manual 21751 for the complete list of instructions. 21752 21753 GCC also provides intrinsics to directly access the network registers. 21754 The intrinsics are: 21755 21756 @smallexample 21757 unsigned __tile_idn0_receive (void); 21758 unsigned __tile_idn1_receive (void); 21759 unsigned __tile_sn_receive (void); 21760 unsigned __tile_udn0_receive (void); 21761 unsigned __tile_udn1_receive (void); 21762 unsigned __tile_udn2_receive (void); 21763 unsigned __tile_udn3_receive (void); 21764 void __tile_idn_send (unsigned); 21765 void __tile_sn_send (unsigned); 21766 void __tile_udn_send (unsigned); 21767 @end smallexample 21768 21769 The intrinsic @code{void __tile_network_barrier (void)} is used to 21770 guarantee that no network operations before it are reordered with 21771 those after it. 21772 21773 @node x86 Built-in Functions 21774 @subsection x86 Built-in Functions 21775 21776 These built-in functions are available for the x86-32 and x86-64 family 21777 of computers, depending on the command-line switches used. 21778 21779 If you specify command-line switches such as @option{-msse}, 21780 the compiler could use the extended instruction sets even if the built-ins 21781 are not used explicitly in the program. For this reason, applications 21782 that perform run-time CPU detection must compile separate files for each 21783 supported architecture, using the appropriate flags. In particular, 21784 the file containing the CPU detection code should be compiled without 21785 these options. 21786 21787 The following machine modes are available for use with MMX built-in functions 21788 (@pxref{Vector Extensions}): @code{V2SI} for a vector of two 32-bit integers, 21789 @code{V4HI} for a vector of four 16-bit integers, and @code{V8QI} for a 21790 vector of eight 8-bit integers. Some of the built-in functions operate on 21791 MMX registers as a whole 64-bit entity, these use @code{V1DI} as their mode. 21792 21793 If 3DNow!@: extensions are enabled, @code{V2SF} is used as a mode for a vector 21794 of two 32-bit floating-point values. 21795 21796 If SSE extensions are enabled, @code{V4SF} is used for a vector of four 32-bit 21797 floating-point values. Some instructions use a vector of four 32-bit 21798 integers, these use @code{V4SI}. Finally, some instructions operate on an 21799 entire vector register, interpreting it as a 128-bit integer, these use mode 21800 @code{TI}. 21801 21802 The x86-32 and x86-64 family of processors use additional built-in 21803 functions for efficient use of @code{TF} (@code{__float128}) 128-bit 21804 floating point and @code{TC} 128-bit complex floating-point values. 21805 21806 The following floating-point built-in functions are always available. All 21807 of them implement the function that is part of the name. 21808 21809 @smallexample 21810 __float128 __builtin_fabsq (__float128) 21811 __float128 __builtin_copysignq (__float128, __float128) 21812 @end smallexample 21813 21814 The following built-in functions are always available. 21815 21816 @table @code 21817 @item __float128 __builtin_infq (void) 21818 Similar to @code{__builtin_inf}, except the return type is @code{__float128}. 21819 @findex __builtin_infq 21820 21821 @item __float128 __builtin_huge_valq (void) 21822 Similar to @code{__builtin_huge_val}, except the return type is @code{__float128}. 21823 @findex __builtin_huge_valq 21824 21825 @item __float128 __builtin_nanq (void) 21826 Similar to @code{__builtin_nan}, except the return type is @code{__float128}. 21827 @findex __builtin_nanq 21828 21829 @item __float128 __builtin_nansq (void) 21830 Similar to @code{__builtin_nans}, except the return type is @code{__float128}. 21831 @findex __builtin_nansq 21832 @end table 21833 21834 The following built-in function is always available. 21835 21836 @table @code 21837 @item void __builtin_ia32_pause (void) 21838 Generates the @code{pause} machine instruction with a compiler memory 21839 barrier. 21840 @end table 21841 21842 The following built-in functions are always available and can be used to 21843 check the target platform type. 21844 21845 @deftypefn {Built-in Function} void __builtin_cpu_init (void) 21846 This function runs the CPU detection code to check the type of CPU and the 21847 features supported. This built-in function needs to be invoked along with the built-in functions 21848 to check CPU type and features, @code{__builtin_cpu_is} and 21849 @code{__builtin_cpu_supports}, only when used in a function that is 21850 executed before any constructors are called. The CPU detection code is 21851 automatically executed in a very high priority constructor. 21852 21853 For example, this function has to be used in @code{ifunc} resolvers that 21854 check for CPU type using the built-in functions @code{__builtin_cpu_is} 21855 and @code{__builtin_cpu_supports}, or in constructors on targets that 21856 don't support constructor priority. 21857 @smallexample 21858 21859 static void (*resolve_memcpy (void)) (void) 21860 @{ 21861 // ifunc resolvers fire before constructors, explicitly call the init 21862 // function. 21863 __builtin_cpu_init (); 21864 if (__builtin_cpu_supports ("ssse3")) 21865 return ssse3_memcpy; // super fast memcpy with ssse3 instructions. 21866 else 21867 return default_memcpy; 21868 @} 21869 21870 void *memcpy (void *, const void *, size_t) 21871 __attribute__ ((ifunc ("resolve_memcpy"))); 21872 @end smallexample 21873 21874 @end deftypefn 21875 21876 @deftypefn {Built-in Function} int __builtin_cpu_is (const char *@var{cpuname}) 21877 This function returns a positive integer if the run-time CPU 21878 is of type @var{cpuname} 21879 and returns @code{0} otherwise. The following CPU names can be detected: 21880 21881 @table @samp 21882 @item amd 21883 AMD CPU. 21884 21885 @item intel 21886 Intel CPU. 21887 21888 @item atom 21889 Intel Atom CPU. 21890 21891 @item slm 21892 Intel Silvermont CPU. 21893 21894 @item core2 21895 Intel Core 2 CPU. 21896 21897 @item corei7 21898 Intel Core i7 CPU. 21899 21900 @item nehalem 21901 Intel Core i7 Nehalem CPU. 21902 21903 @item westmere 21904 Intel Core i7 Westmere CPU. 21905 21906 @item sandybridge 21907 Intel Core i7 Sandy Bridge CPU. 21908 21909 @item ivybridge 21910 Intel Core i7 Ivy Bridge CPU. 21911 21912 @item haswell 21913 Intel Core i7 Haswell CPU. 21914 21915 @item broadwell 21916 Intel Core i7 Broadwell CPU. 21917 21918 @item skylake 21919 Intel Core i7 Skylake CPU. 21920 21921 @item skylake-avx512 21922 Intel Core i7 Skylake AVX512 CPU. 21923 21924 @item cannonlake 21925 Intel Core i7 Cannon Lake CPU. 21926 21927 @item icelake-client 21928 Intel Core i7 Ice Lake Client CPU. 21929 21930 @item icelake-server 21931 Intel Core i7 Ice Lake Server CPU. 21932 21933 @item cascadelake 21934 Intel Core i7 Cascadelake CPU. 21935 21936 @item tigerlake 21937 Intel Core i7 Tigerlake CPU. 21938 21939 @item cooperlake 21940 Intel Core i7 Cooperlake CPU. 21941 21942 @item sapphirerapids 21943 Intel Core i7 sapphirerapids CPU. 21944 21945 @item alderlake 21946 Intel Core i7 Alderlake CPU. 21947 21948 @item rocketlake 21949 Intel Core i7 Rocketlake CPU. 21950 21951 @item bonnell 21952 Intel Atom Bonnell CPU. 21953 21954 @item silvermont 21955 Intel Atom Silvermont CPU. 21956 21957 @item goldmont 21958 Intel Atom Goldmont CPU. 21959 21960 @item goldmont-plus 21961 Intel Atom Goldmont Plus CPU. 21962 21963 @item tremont 21964 Intel Atom Tremont CPU. 21965 21966 @item knl 21967 Intel Knights Landing CPU. 21968 21969 @item knm 21970 Intel Knights Mill CPU. 21971 21972 @item amdfam10h 21973 AMD Family 10h CPU. 21974 21975 @item barcelona 21976 AMD Family 10h Barcelona CPU. 21977 21978 @item shanghai 21979 AMD Family 10h Shanghai CPU. 21980 21981 @item istanbul 21982 AMD Family 10h Istanbul CPU. 21983 21984 @item btver1 21985 AMD Family 14h CPU. 21986 21987 @item amdfam15h 21988 AMD Family 15h CPU. 21989 21990 @item bdver1 21991 AMD Family 15h Bulldozer version 1. 21992 21993 @item bdver2 21994 AMD Family 15h Bulldozer version 2. 21995 21996 @item bdver3 21997 AMD Family 15h Bulldozer version 3. 21998 21999 @item bdver4 22000 AMD Family 15h Bulldozer version 4. 22001 22002 @item btver2 22003 AMD Family 16h CPU. 22004 22005 @item amdfam17h 22006 AMD Family 17h CPU. 22007 22008 @item znver1 22009 AMD Family 17h Zen version 1. 22010 22011 @item znver2 22012 AMD Family 17h Zen version 2. 22013 22014 @item amdfam19h 22015 AMD Family 19h CPU. 22016 22017 @item znver3 22018 AMD Family 19h Zen version 3. 22019 22020 @item znver4 22021 AMD Family 19h Zen version 4. 22022 22023 @item znver5 22024 AMD Family 1ah Zen version 5. 22025 @end table 22026 22027 Here is an example: 22028 @smallexample 22029 if (__builtin_cpu_is ("corei7")) 22030 @{ 22031 do_corei7 (); // Core i7 specific implementation. 22032 @} 22033 else 22034 @{ 22035 do_generic (); // Generic implementation. 22036 @} 22037 @end smallexample 22038 @end deftypefn 22039 22040 @deftypefn {Built-in Function} int __builtin_cpu_supports (const char *@var{feature}) 22041 This function returns a positive integer if the run-time CPU 22042 supports @var{feature} 22043 and returns @code{0} otherwise. The following features can be detected: 22044 22045 @table @samp 22046 @item cmov 22047 CMOV instruction. 22048 @item mmx 22049 MMX instructions. 22050 @item popcnt 22051 POPCNT instruction. 22052 @item sse 22053 SSE instructions. 22054 @item sse2 22055 SSE2 instructions. 22056 @item sse3 22057 SSE3 instructions. 22058 @item ssse3 22059 SSSE3 instructions. 22060 @item sse4.1 22061 SSE4.1 instructions. 22062 @item sse4.2 22063 SSE4.2 instructions. 22064 @item avx 22065 AVX instructions. 22066 @item avx2 22067 AVX2 instructions. 22068 @item sse4a 22069 SSE4A instructions. 22070 @item fma4 22071 FMA4 instructions. 22072 @item xop 22073 XOP instructions. 22074 @item fma 22075 FMA instructions. 22076 @item avx512f 22077 AVX512F instructions. 22078 @item bmi 22079 BMI instructions. 22080 @item bmi2 22081 BMI2 instructions. 22082 @item aes 22083 AES instructions. 22084 @item pclmul 22085 PCLMUL instructions. 22086 @item avx512vl 22087 AVX512VL instructions. 22088 @item avx512bw 22089 AVX512BW instructions. 22090 @item avx512dq 22091 AVX512DQ instructions. 22092 @item avx512cd 22093 AVX512CD instructions. 22094 @item avx512er 22095 AVX512ER instructions. 22096 @item avx512pf 22097 AVX512PF instructions. 22098 @item avx512vbmi 22099 AVX512VBMI instructions. 22100 @item avx512ifma 22101 AVX512IFMA instructions. 22102 @item avx5124vnniw 22103 AVX5124VNNIW instructions. 22104 @item avx5124fmaps 22105 AVX5124FMAPS instructions. 22106 @item avx512vpopcntdq 22107 AVX512VPOPCNTDQ instructions. 22108 @item avx512vbmi2 22109 AVX512VBMI2 instructions. 22110 @item gfni 22111 GFNI instructions. 22112 @item vpclmulqdq 22113 VPCLMULQDQ instructions. 22114 @item avx512vnni 22115 AVX512VNNI instructions. 22116 @item avx512bitalg 22117 AVX512BITALG instructions. 22118 @item x86-64 22119 Baseline x86-64 microarchitecture level (as defined in x86-64 psABI). 22120 @item x86-64-v2 22121 x86-64-v2 microarchitecture level. 22122 @item x86-64-v3 22123 x86-64-v3 microarchitecture level. 22124 @item x86-64-v4 22125 x86-64-v4 microarchitecture level. 22126 22127 22128 @end table 22129 22130 Here is an example: 22131 @smallexample 22132 if (__builtin_cpu_supports ("popcnt")) 22133 @{ 22134 asm("popcnt %1,%0" : "=r"(count) : "rm"(n) : "cc"); 22135 @} 22136 else 22137 @{ 22138 count = generic_countbits (n); //generic implementation. 22139 @} 22140 @end smallexample 22141 @end deftypefn 22142 22143 The following built-in functions are made available by @option{-mmmx}. 22144 All of them generate the machine instruction that is part of the name. 22145 22146 @smallexample 22147 v8qi __builtin_ia32_paddb (v8qi, v8qi); 22148 v4hi __builtin_ia32_paddw (v4hi, v4hi); 22149 v2si __builtin_ia32_paddd (v2si, v2si); 22150 v8qi __builtin_ia32_psubb (v8qi, v8qi); 22151 v4hi __builtin_ia32_psubw (v4hi, v4hi); 22152 v2si __builtin_ia32_psubd (v2si, v2si); 22153 v8qi __builtin_ia32_paddsb (v8qi, v8qi); 22154 v4hi __builtin_ia32_paddsw (v4hi, v4hi); 22155 v8qi __builtin_ia32_psubsb (v8qi, v8qi); 22156 v4hi __builtin_ia32_psubsw (v4hi, v4hi); 22157 v8qi __builtin_ia32_paddusb (v8qi, v8qi); 22158 v4hi __builtin_ia32_paddusw (v4hi, v4hi); 22159 v8qi __builtin_ia32_psubusb (v8qi, v8qi); 22160 v4hi __builtin_ia32_psubusw (v4hi, v4hi); 22161 v4hi __builtin_ia32_pmullw (v4hi, v4hi); 22162 v4hi __builtin_ia32_pmulhw (v4hi, v4hi); 22163 di __builtin_ia32_pand (di, di); 22164 di __builtin_ia32_pandn (di,di); 22165 di __builtin_ia32_por (di, di); 22166 di __builtin_ia32_pxor (di, di); 22167 v8qi __builtin_ia32_pcmpeqb (v8qi, v8qi); 22168 v4hi __builtin_ia32_pcmpeqw (v4hi, v4hi); 22169 v2si __builtin_ia32_pcmpeqd (v2si, v2si); 22170 v8qi __builtin_ia32_pcmpgtb (v8qi, v8qi); 22171 v4hi __builtin_ia32_pcmpgtw (v4hi, v4hi); 22172 v2si __builtin_ia32_pcmpgtd (v2si, v2si); 22173 v8qi __builtin_ia32_punpckhbw (v8qi, v8qi); 22174 v4hi __builtin_ia32_punpckhwd (v4hi, v4hi); 22175 v2si __builtin_ia32_punpckhdq (v2si, v2si); 22176 v8qi __builtin_ia32_punpcklbw (v8qi, v8qi); 22177 v4hi __builtin_ia32_punpcklwd (v4hi, v4hi); 22178 v2si __builtin_ia32_punpckldq (v2si, v2si); 22179 v8qi __builtin_ia32_packsswb (v4hi, v4hi); 22180 v4hi __builtin_ia32_packssdw (v2si, v2si); 22181 v8qi __builtin_ia32_packuswb (v4hi, v4hi); 22182 22183 v4hi __builtin_ia32_psllw (v4hi, v4hi); 22184 v2si __builtin_ia32_pslld (v2si, v2si); 22185 v1di __builtin_ia32_psllq (v1di, v1di); 22186 v4hi __builtin_ia32_psrlw (v4hi, v4hi); 22187 v2si __builtin_ia32_psrld (v2si, v2si); 22188 v1di __builtin_ia32_psrlq (v1di, v1di); 22189 v4hi __builtin_ia32_psraw (v4hi, v4hi); 22190 v2si __builtin_ia32_psrad (v2si, v2si); 22191 v4hi __builtin_ia32_psllwi (v4hi, int); 22192 v2si __builtin_ia32_pslldi (v2si, int); 22193 v1di __builtin_ia32_psllqi (v1di, int); 22194 v4hi __builtin_ia32_psrlwi (v4hi, int); 22195 v2si __builtin_ia32_psrldi (v2si, int); 22196 v1di __builtin_ia32_psrlqi (v1di, int); 22197 v4hi __builtin_ia32_psrawi (v4hi, int); 22198 v2si __builtin_ia32_psradi (v2si, int); 22199 @end smallexample 22200 22201 The following built-in functions are made available either with 22202 @option{-msse}, or with @option{-m3dnowa}. All of them generate 22203 the machine instruction that is part of the name. 22204 22205 @smallexample 22206 v4hi __builtin_ia32_pmulhuw (v4hi, v4hi); 22207 v8qi __builtin_ia32_pavgb (v8qi, v8qi); 22208 v4hi __builtin_ia32_pavgw (v4hi, v4hi); 22209 v1di __builtin_ia32_psadbw (v8qi, v8qi); 22210 v8qi __builtin_ia32_pmaxub (v8qi, v8qi); 22211 v4hi __builtin_ia32_pmaxsw (v4hi, v4hi); 22212 v8qi __builtin_ia32_pminub (v8qi, v8qi); 22213 v4hi __builtin_ia32_pminsw (v4hi, v4hi); 22214 int __builtin_ia32_pmovmskb (v8qi); 22215 void __builtin_ia32_maskmovq (v8qi, v8qi, char *); 22216 void __builtin_ia32_movntq (di *, di); 22217 void __builtin_ia32_sfence (void); 22218 @end smallexample 22219 22220 The following built-in functions are available when @option{-msse} is used. 22221 All of them generate the machine instruction that is part of the name. 22222 22223 @smallexample 22224 int __builtin_ia32_comieq (v4sf, v4sf); 22225 int __builtin_ia32_comineq (v4sf, v4sf); 22226 int __builtin_ia32_comilt (v4sf, v4sf); 22227 int __builtin_ia32_comile (v4sf, v4sf); 22228 int __builtin_ia32_comigt (v4sf, v4sf); 22229 int __builtin_ia32_comige (v4sf, v4sf); 22230 int __builtin_ia32_ucomieq (v4sf, v4sf); 22231 int __builtin_ia32_ucomineq (v4sf, v4sf); 22232 int __builtin_ia32_ucomilt (v4sf, v4sf); 22233 int __builtin_ia32_ucomile (v4sf, v4sf); 22234 int __builtin_ia32_ucomigt (v4sf, v4sf); 22235 int __builtin_ia32_ucomige (v4sf, v4sf); 22236 v4sf __builtin_ia32_addps (v4sf, v4sf); 22237 v4sf __builtin_ia32_subps (v4sf, v4sf); 22238 v4sf __builtin_ia32_mulps (v4sf, v4sf); 22239 v4sf __builtin_ia32_divps (v4sf, v4sf); 22240 v4sf __builtin_ia32_addss (v4sf, v4sf); 22241 v4sf __builtin_ia32_subss (v4sf, v4sf); 22242 v4sf __builtin_ia32_mulss (v4sf, v4sf); 22243 v4sf __builtin_ia32_divss (v4sf, v4sf); 22244 v4sf __builtin_ia32_cmpeqps (v4sf, v4sf); 22245 v4sf __builtin_ia32_cmpltps (v4sf, v4sf); 22246 v4sf __builtin_ia32_cmpleps (v4sf, v4sf); 22247 v4sf __builtin_ia32_cmpgtps (v4sf, v4sf); 22248 v4sf __builtin_ia32_cmpgeps (v4sf, v4sf); 22249 v4sf __builtin_ia32_cmpunordps (v4sf, v4sf); 22250 v4sf __builtin_ia32_cmpneqps (v4sf, v4sf); 22251 v4sf __builtin_ia32_cmpnltps (v4sf, v4sf); 22252 v4sf __builtin_ia32_cmpnleps (v4sf, v4sf); 22253 v4sf __builtin_ia32_cmpngtps (v4sf, v4sf); 22254 v4sf __builtin_ia32_cmpngeps (v4sf, v4sf); 22255 v4sf __builtin_ia32_cmpordps (v4sf, v4sf); 22256 v4sf __builtin_ia32_cmpeqss (v4sf, v4sf); 22257 v4sf __builtin_ia32_cmpltss (v4sf, v4sf); 22258 v4sf __builtin_ia32_cmpless (v4sf, v4sf); 22259 v4sf __builtin_ia32_cmpunordss (v4sf, v4sf); 22260 v4sf __builtin_ia32_cmpneqss (v4sf, v4sf); 22261 v4sf __builtin_ia32_cmpnltss (v4sf, v4sf); 22262 v4sf __builtin_ia32_cmpnless (v4sf, v4sf); 22263 v4sf __builtin_ia32_cmpordss (v4sf, v4sf); 22264 v4sf __builtin_ia32_maxps (v4sf, v4sf); 22265 v4sf __builtin_ia32_maxss (v4sf, v4sf); 22266 v4sf __builtin_ia32_minps (v4sf, v4sf); 22267 v4sf __builtin_ia32_minss (v4sf, v4sf); 22268 v4sf __builtin_ia32_andps (v4sf, v4sf); 22269 v4sf __builtin_ia32_andnps (v4sf, v4sf); 22270 v4sf __builtin_ia32_orps (v4sf, v4sf); 22271 v4sf __builtin_ia32_xorps (v4sf, v4sf); 22272 v4sf __builtin_ia32_movss (v4sf, v4sf); 22273 v4sf __builtin_ia32_movhlps (v4sf, v4sf); 22274 v4sf __builtin_ia32_movlhps (v4sf, v4sf); 22275 v4sf __builtin_ia32_unpckhps (v4sf, v4sf); 22276 v4sf __builtin_ia32_unpcklps (v4sf, v4sf); 22277 v4sf __builtin_ia32_cvtpi2ps (v4sf, v2si); 22278 v4sf __builtin_ia32_cvtsi2ss (v4sf, int); 22279 v2si __builtin_ia32_cvtps2pi (v4sf); 22280 int __builtin_ia32_cvtss2si (v4sf); 22281 v2si __builtin_ia32_cvttps2pi (v4sf); 22282 int __builtin_ia32_cvttss2si (v4sf); 22283 v4sf __builtin_ia32_rcpps (v4sf); 22284 v4sf __builtin_ia32_rsqrtps (v4sf); 22285 v4sf __builtin_ia32_sqrtps (v4sf); 22286 v4sf __builtin_ia32_rcpss (v4sf); 22287 v4sf __builtin_ia32_rsqrtss (v4sf); 22288 v4sf __builtin_ia32_sqrtss (v4sf); 22289 v4sf __builtin_ia32_shufps (v4sf, v4sf, int); 22290 void __builtin_ia32_movntps (float *, v4sf); 22291 int __builtin_ia32_movmskps (v4sf); 22292 @end smallexample 22293 22294 The following built-in functions are available when @option{-msse} is used. 22295 22296 @table @code 22297 @item v4sf __builtin_ia32_loadups (float *) 22298 Generates the @code{movups} machine instruction as a load from memory. 22299 @item void __builtin_ia32_storeups (float *, v4sf) 22300 Generates the @code{movups} machine instruction as a store to memory. 22301 @item v4sf __builtin_ia32_loadss (float *) 22302 Generates the @code{movss} machine instruction as a load from memory. 22303 @item v4sf __builtin_ia32_loadhps (v4sf, const v2sf *) 22304 Generates the @code{movhps} machine instruction as a load from memory. 22305 @item v4sf __builtin_ia32_loadlps (v4sf, const v2sf *) 22306 Generates the @code{movlps} machine instruction as a load from memory 22307 @item void __builtin_ia32_storehps (v2sf *, v4sf) 22308 Generates the @code{movhps} machine instruction as a store to memory. 22309 @item void __builtin_ia32_storelps (v2sf *, v4sf) 22310 Generates the @code{movlps} machine instruction as a store to memory. 22311 @end table 22312 22313 The following built-in functions are available when @option{-msse2} is used. 22314 All of them generate the machine instruction that is part of the name. 22315 22316 @smallexample 22317 int __builtin_ia32_comisdeq (v2df, v2df); 22318 int __builtin_ia32_comisdlt (v2df, v2df); 22319 int __builtin_ia32_comisdle (v2df, v2df); 22320 int __builtin_ia32_comisdgt (v2df, v2df); 22321 int __builtin_ia32_comisdge (v2df, v2df); 22322 int __builtin_ia32_comisdneq (v2df, v2df); 22323 int __builtin_ia32_ucomisdeq (v2df, v2df); 22324 int __builtin_ia32_ucomisdlt (v2df, v2df); 22325 int __builtin_ia32_ucomisdle (v2df, v2df); 22326 int __builtin_ia32_ucomisdgt (v2df, v2df); 22327 int __builtin_ia32_ucomisdge (v2df, v2df); 22328 int __builtin_ia32_ucomisdneq (v2df, v2df); 22329 v2df __builtin_ia32_cmpeqpd (v2df, v2df); 22330 v2df __builtin_ia32_cmpltpd (v2df, v2df); 22331 v2df __builtin_ia32_cmplepd (v2df, v2df); 22332 v2df __builtin_ia32_cmpgtpd (v2df, v2df); 22333 v2df __builtin_ia32_cmpgepd (v2df, v2df); 22334 v2df __builtin_ia32_cmpunordpd (v2df, v2df); 22335 v2df __builtin_ia32_cmpneqpd (v2df, v2df); 22336 v2df __builtin_ia32_cmpnltpd (v2df, v2df); 22337 v2df __builtin_ia32_cmpnlepd (v2df, v2df); 22338 v2df __builtin_ia32_cmpngtpd (v2df, v2df); 22339 v2df __builtin_ia32_cmpngepd (v2df, v2df); 22340 v2df __builtin_ia32_cmpordpd (v2df, v2df); 22341 v2df __builtin_ia32_cmpeqsd (v2df, v2df); 22342 v2df __builtin_ia32_cmpltsd (v2df, v2df); 22343 v2df __builtin_ia32_cmplesd (v2df, v2df); 22344 v2df __builtin_ia32_cmpunordsd (v2df, v2df); 22345 v2df __builtin_ia32_cmpneqsd (v2df, v2df); 22346 v2df __builtin_ia32_cmpnltsd (v2df, v2df); 22347 v2df __builtin_ia32_cmpnlesd (v2df, v2df); 22348 v2df __builtin_ia32_cmpordsd (v2df, v2df); 22349 v2di __builtin_ia32_paddq (v2di, v2di); 22350 v2di __builtin_ia32_psubq (v2di, v2di); 22351 v2df __builtin_ia32_addpd (v2df, v2df); 22352 v2df __builtin_ia32_subpd (v2df, v2df); 22353 v2df __builtin_ia32_mulpd (v2df, v2df); 22354 v2df __builtin_ia32_divpd (v2df, v2df); 22355 v2df __builtin_ia32_addsd (v2df, v2df); 22356 v2df __builtin_ia32_subsd (v2df, v2df); 22357 v2df __builtin_ia32_mulsd (v2df, v2df); 22358 v2df __builtin_ia32_divsd (v2df, v2df); 22359 v2df __builtin_ia32_minpd (v2df, v2df); 22360 v2df __builtin_ia32_maxpd (v2df, v2df); 22361 v2df __builtin_ia32_minsd (v2df, v2df); 22362 v2df __builtin_ia32_maxsd (v2df, v2df); 22363 v2df __builtin_ia32_andpd (v2df, v2df); 22364 v2df __builtin_ia32_andnpd (v2df, v2df); 22365 v2df __builtin_ia32_orpd (v2df, v2df); 22366 v2df __builtin_ia32_xorpd (v2df, v2df); 22367 v2df __builtin_ia32_movsd (v2df, v2df); 22368 v2df __builtin_ia32_unpckhpd (v2df, v2df); 22369 v2df __builtin_ia32_unpcklpd (v2df, v2df); 22370 v16qi __builtin_ia32_paddb128 (v16qi, v16qi); 22371 v8hi __builtin_ia32_paddw128 (v8hi, v8hi); 22372 v4si __builtin_ia32_paddd128 (v4si, v4si); 22373 v2di __builtin_ia32_paddq128 (v2di, v2di); 22374 v16qi __builtin_ia32_psubb128 (v16qi, v16qi); 22375 v8hi __builtin_ia32_psubw128 (v8hi, v8hi); 22376 v4si __builtin_ia32_psubd128 (v4si, v4si); 22377 v2di __builtin_ia32_psubq128 (v2di, v2di); 22378 v8hi __builtin_ia32_pmullw128 (v8hi, v8hi); 22379 v8hi __builtin_ia32_pmulhw128 (v8hi, v8hi); 22380 v2di __builtin_ia32_pand128 (v2di, v2di); 22381 v2di __builtin_ia32_pandn128 (v2di, v2di); 22382 v2di __builtin_ia32_por128 (v2di, v2di); 22383 v2di __builtin_ia32_pxor128 (v2di, v2di); 22384 v16qi __builtin_ia32_pavgb128 (v16qi, v16qi); 22385 v8hi __builtin_ia32_pavgw128 (v8hi, v8hi); 22386 v16qi __builtin_ia32_pcmpeqb128 (v16qi, v16qi); 22387 v8hi __builtin_ia32_pcmpeqw128 (v8hi, v8hi); 22388 v4si __builtin_ia32_pcmpeqd128 (v4si, v4si); 22389 v16qi __builtin_ia32_pcmpgtb128 (v16qi, v16qi); 22390 v8hi __builtin_ia32_pcmpgtw128 (v8hi, v8hi); 22391 v4si __builtin_ia32_pcmpgtd128 (v4si, v4si); 22392 v16qi __builtin_ia32_pmaxub128 (v16qi, v16qi); 22393 v8hi __builtin_ia32_pmaxsw128 (v8hi, v8hi); 22394 v16qi __builtin_ia32_pminub128 (v16qi, v16qi); 22395 v8hi __builtin_ia32_pminsw128 (v8hi, v8hi); 22396 v16qi __builtin_ia32_punpckhbw128 (v16qi, v16qi); 22397 v8hi __builtin_ia32_punpckhwd128 (v8hi, v8hi); 22398 v4si __builtin_ia32_punpckhdq128 (v4si, v4si); 22399 v2di __builtin_ia32_punpckhqdq128 (v2di, v2di); 22400 v16qi __builtin_ia32_punpcklbw128 (v16qi, v16qi); 22401 v8hi __builtin_ia32_punpcklwd128 (v8hi, v8hi); 22402 v4si __builtin_ia32_punpckldq128 (v4si, v4si); 22403 v2di __builtin_ia32_punpcklqdq128 (v2di, v2di); 22404 v16qi __builtin_ia32_packsswb128 (v8hi, v8hi); 22405 v8hi __builtin_ia32_packssdw128 (v4si, v4si); 22406 v16qi __builtin_ia32_packuswb128 (v8hi, v8hi); 22407 v8hi __builtin_ia32_pmulhuw128 (v8hi, v8hi); 22408 void __builtin_ia32_maskmovdqu (v16qi, v16qi); 22409 v2df __builtin_ia32_loadupd (double *); 22410 void __builtin_ia32_storeupd (double *, v2df); 22411 v2df __builtin_ia32_loadhpd (v2df, double const *); 22412 v2df __builtin_ia32_loadlpd (v2df, double const *); 22413 int __builtin_ia32_movmskpd (v2df); 22414 int __builtin_ia32_pmovmskb128 (v16qi); 22415 void __builtin_ia32_movnti (int *, int); 22416 void __builtin_ia32_movnti64 (long long int *, long long int); 22417 void __builtin_ia32_movntpd (double *, v2df); 22418 void __builtin_ia32_movntdq (v2df *, v2df); 22419 v4si __builtin_ia32_pshufd (v4si, int); 22420 v8hi __builtin_ia32_pshuflw (v8hi, int); 22421 v8hi __builtin_ia32_pshufhw (v8hi, int); 22422 v2di __builtin_ia32_psadbw128 (v16qi, v16qi); 22423 v2df __builtin_ia32_sqrtpd (v2df); 22424 v2df __builtin_ia32_sqrtsd (v2df); 22425 v2df __builtin_ia32_shufpd (v2df, v2df, int); 22426 v2df __builtin_ia32_cvtdq2pd (v4si); 22427 v4sf __builtin_ia32_cvtdq2ps (v4si); 22428 v4si __builtin_ia32_cvtpd2dq (v2df); 22429 v2si __builtin_ia32_cvtpd2pi (v2df); 22430 v4sf __builtin_ia32_cvtpd2ps (v2df); 22431 v4si __builtin_ia32_cvttpd2dq (v2df); 22432 v2si __builtin_ia32_cvttpd2pi (v2df); 22433 v2df __builtin_ia32_cvtpi2pd (v2si); 22434 int __builtin_ia32_cvtsd2si (v2df); 22435 int __builtin_ia32_cvttsd2si (v2df); 22436 long long __builtin_ia32_cvtsd2si64 (v2df); 22437 long long __builtin_ia32_cvttsd2si64 (v2df); 22438 v4si __builtin_ia32_cvtps2dq (v4sf); 22439 v2df __builtin_ia32_cvtps2pd (v4sf); 22440 v4si __builtin_ia32_cvttps2dq (v4sf); 22441 v2df __builtin_ia32_cvtsi2sd (v2df, int); 22442 v2df __builtin_ia32_cvtsi642sd (v2df, long long); 22443 v4sf __builtin_ia32_cvtsd2ss (v4sf, v2df); 22444 v2df __builtin_ia32_cvtss2sd (v2df, v4sf); 22445 void __builtin_ia32_clflush (const void *); 22446 void __builtin_ia32_lfence (void); 22447 void __builtin_ia32_mfence (void); 22448 v16qi __builtin_ia32_loaddqu (const char *); 22449 void __builtin_ia32_storedqu (char *, v16qi); 22450 v1di __builtin_ia32_pmuludq (v2si, v2si); 22451 v2di __builtin_ia32_pmuludq128 (v4si, v4si); 22452 v8hi __builtin_ia32_psllw128 (v8hi, v8hi); 22453 v4si __builtin_ia32_pslld128 (v4si, v4si); 22454 v2di __builtin_ia32_psllq128 (v2di, v2di); 22455 v8hi __builtin_ia32_psrlw128 (v8hi, v8hi); 22456 v4si __builtin_ia32_psrld128 (v4si, v4si); 22457 v2di __builtin_ia32_psrlq128 (v2di, v2di); 22458 v8hi __builtin_ia32_psraw128 (v8hi, v8hi); 22459 v4si __builtin_ia32_psrad128 (v4si, v4si); 22460 v2di __builtin_ia32_pslldqi128 (v2di, int); 22461 v8hi __builtin_ia32_psllwi128 (v8hi, int); 22462 v4si __builtin_ia32_pslldi128 (v4si, int); 22463 v2di __builtin_ia32_psllqi128 (v2di, int); 22464 v2di __builtin_ia32_psrldqi128 (v2di, int); 22465 v8hi __builtin_ia32_psrlwi128 (v8hi, int); 22466 v4si __builtin_ia32_psrldi128 (v4si, int); 22467 v2di __builtin_ia32_psrlqi128 (v2di, int); 22468 v8hi __builtin_ia32_psrawi128 (v8hi, int); 22469 v4si __builtin_ia32_psradi128 (v4si, int); 22470 v4si __builtin_ia32_pmaddwd128 (v8hi, v8hi); 22471 v2di __builtin_ia32_movq128 (v2di); 22472 @end smallexample 22473 22474 The following built-in functions are available when @option{-msse3} is used. 22475 All of them generate the machine instruction that is part of the name. 22476 22477 @smallexample 22478 v2df __builtin_ia32_addsubpd (v2df, v2df); 22479 v4sf __builtin_ia32_addsubps (v4sf, v4sf); 22480 v2df __builtin_ia32_haddpd (v2df, v2df); 22481 v4sf __builtin_ia32_haddps (v4sf, v4sf); 22482 v2df __builtin_ia32_hsubpd (v2df, v2df); 22483 v4sf __builtin_ia32_hsubps (v4sf, v4sf); 22484 v16qi __builtin_ia32_lddqu (char const *); 22485 void __builtin_ia32_monitor (void *, unsigned int, unsigned int); 22486 v4sf __builtin_ia32_movshdup (v4sf); 22487 v4sf __builtin_ia32_movsldup (v4sf); 22488 void __builtin_ia32_mwait (unsigned int, unsigned int); 22489 @end smallexample 22490 22491 The following built-in functions are available when @option{-mssse3} is used. 22492 All of them generate the machine instruction that is part of the name. 22493 22494 @smallexample 22495 v2si __builtin_ia32_phaddd (v2si, v2si); 22496 v4hi __builtin_ia32_phaddw (v4hi, v4hi); 22497 v4hi __builtin_ia32_phaddsw (v4hi, v4hi); 22498 v2si __builtin_ia32_phsubd (v2si, v2si); 22499 v4hi __builtin_ia32_phsubw (v4hi, v4hi); 22500 v4hi __builtin_ia32_phsubsw (v4hi, v4hi); 22501 v4hi __builtin_ia32_pmaddubsw (v8qi, v8qi); 22502 v4hi __builtin_ia32_pmulhrsw (v4hi, v4hi); 22503 v8qi __builtin_ia32_pshufb (v8qi, v8qi); 22504 v8qi __builtin_ia32_psignb (v8qi, v8qi); 22505 v2si __builtin_ia32_psignd (v2si, v2si); 22506 v4hi __builtin_ia32_psignw (v4hi, v4hi); 22507 v1di __builtin_ia32_palignr (v1di, v1di, int); 22508 v8qi __builtin_ia32_pabsb (v8qi); 22509 v2si __builtin_ia32_pabsd (v2si); 22510 v4hi __builtin_ia32_pabsw (v4hi); 22511 @end smallexample 22512 22513 The following built-in functions are available when @option{-mssse3} is used. 22514 All of them generate the machine instruction that is part of the name. 22515 22516 @smallexample 22517 v4si __builtin_ia32_phaddd128 (v4si, v4si); 22518 v8hi __builtin_ia32_phaddw128 (v8hi, v8hi); 22519 v8hi __builtin_ia32_phaddsw128 (v8hi, v8hi); 22520 v4si __builtin_ia32_phsubd128 (v4si, v4si); 22521 v8hi __builtin_ia32_phsubw128 (v8hi, v8hi); 22522 v8hi __builtin_ia32_phsubsw128 (v8hi, v8hi); 22523 v8hi __builtin_ia32_pmaddubsw128 (v16qi, v16qi); 22524 v8hi __builtin_ia32_pmulhrsw128 (v8hi, v8hi); 22525 v16qi __builtin_ia32_pshufb128 (v16qi, v16qi); 22526 v16qi __builtin_ia32_psignb128 (v16qi, v16qi); 22527 v4si __builtin_ia32_psignd128 (v4si, v4si); 22528 v8hi __builtin_ia32_psignw128 (v8hi, v8hi); 22529 v2di __builtin_ia32_palignr128 (v2di, v2di, int); 22530 v16qi __builtin_ia32_pabsb128 (v16qi); 22531 v4si __builtin_ia32_pabsd128 (v4si); 22532 v8hi __builtin_ia32_pabsw128 (v8hi); 22533 @end smallexample 22534 22535 The following built-in functions are available when @option{-msse4.1} is 22536 used. All of them generate the machine instruction that is part of the 22537 name. 22538 22539 @smallexample 22540 v2df __builtin_ia32_blendpd (v2df, v2df, const int); 22541 v4sf __builtin_ia32_blendps (v4sf, v4sf, const int); 22542 v2df __builtin_ia32_blendvpd (v2df, v2df, v2df); 22543 v4sf __builtin_ia32_blendvps (v4sf, v4sf, v4sf); 22544 v2df __builtin_ia32_dppd (v2df, v2df, const int); 22545 v4sf __builtin_ia32_dpps (v4sf, v4sf, const int); 22546 v4sf __builtin_ia32_insertps128 (v4sf, v4sf, const int); 22547 v2di __builtin_ia32_movntdqa (v2di *); 22548 v16qi __builtin_ia32_mpsadbw128 (v16qi, v16qi, const int); 22549 v8hi __builtin_ia32_packusdw128 (v4si, v4si); 22550 v16qi __builtin_ia32_pblendvb128 (v16qi, v16qi, v16qi); 22551 v8hi __builtin_ia32_pblendw128 (v8hi, v8hi, const int); 22552 v2di __builtin_ia32_pcmpeqq (v2di, v2di); 22553 v8hi __builtin_ia32_phminposuw128 (v8hi); 22554 v16qi __builtin_ia32_pmaxsb128 (v16qi, v16qi); 22555 v4si __builtin_ia32_pmaxsd128 (v4si, v4si); 22556 v4si __builtin_ia32_pmaxud128 (v4si, v4si); 22557 v8hi __builtin_ia32_pmaxuw128 (v8hi, v8hi); 22558 v16qi __builtin_ia32_pminsb128 (v16qi, v16qi); 22559 v4si __builtin_ia32_pminsd128 (v4si, v4si); 22560 v4si __builtin_ia32_pminud128 (v4si, v4si); 22561 v8hi __builtin_ia32_pminuw128 (v8hi, v8hi); 22562 v4si __builtin_ia32_pmovsxbd128 (v16qi); 22563 v2di __builtin_ia32_pmovsxbq128 (v16qi); 22564 v8hi __builtin_ia32_pmovsxbw128 (v16qi); 22565 v2di __builtin_ia32_pmovsxdq128 (v4si); 22566 v4si __builtin_ia32_pmovsxwd128 (v8hi); 22567 v2di __builtin_ia32_pmovsxwq128 (v8hi); 22568 v4si __builtin_ia32_pmovzxbd128 (v16qi); 22569 v2di __builtin_ia32_pmovzxbq128 (v16qi); 22570 v8hi __builtin_ia32_pmovzxbw128 (v16qi); 22571 v2di __builtin_ia32_pmovzxdq128 (v4si); 22572 v4si __builtin_ia32_pmovzxwd128 (v8hi); 22573 v2di __builtin_ia32_pmovzxwq128 (v8hi); 22574 v2di __builtin_ia32_pmuldq128 (v4si, v4si); 22575 v4si __builtin_ia32_pmulld128 (v4si, v4si); 22576 int __builtin_ia32_ptestc128 (v2di, v2di); 22577 int __builtin_ia32_ptestnzc128 (v2di, v2di); 22578 int __builtin_ia32_ptestz128 (v2di, v2di); 22579 v2df __builtin_ia32_roundpd (v2df, const int); 22580 v4sf __builtin_ia32_roundps (v4sf, const int); 22581 v2df __builtin_ia32_roundsd (v2df, v2df, const int); 22582 v4sf __builtin_ia32_roundss (v4sf, v4sf, const int); 22583 @end smallexample 22584 22585 The following built-in functions are available when @option{-msse4.1} is 22586 used. 22587 22588 @table @code 22589 @item v4sf __builtin_ia32_vec_set_v4sf (v4sf, float, const int) 22590 Generates the @code{insertps} machine instruction. 22591 @item int __builtin_ia32_vec_ext_v16qi (v16qi, const int) 22592 Generates the @code{pextrb} machine instruction. 22593 @item v16qi __builtin_ia32_vec_set_v16qi (v16qi, int, const int) 22594 Generates the @code{pinsrb} machine instruction. 22595 @item v4si __builtin_ia32_vec_set_v4si (v4si, int, const int) 22596 Generates the @code{pinsrd} machine instruction. 22597 @item v2di __builtin_ia32_vec_set_v2di (v2di, long long, const int) 22598 Generates the @code{pinsrq} machine instruction in 64bit mode. 22599 @end table 22600 22601 The following built-in functions are changed to generate new SSE4.1 22602 instructions when @option{-msse4.1} is used. 22603 22604 @table @code 22605 @item float __builtin_ia32_vec_ext_v4sf (v4sf, const int) 22606 Generates the @code{extractps} machine instruction. 22607 @item int __builtin_ia32_vec_ext_v4si (v4si, const int) 22608 Generates the @code{pextrd} machine instruction. 22609 @item long long __builtin_ia32_vec_ext_v2di (v2di, const int) 22610 Generates the @code{pextrq} machine instruction in 64bit mode. 22611 @end table 22612 22613 The following built-in functions are available when @option{-msse4.2} is 22614 used. All of them generate the machine instruction that is part of the 22615 name. 22616 22617 @smallexample 22618 v16qi __builtin_ia32_pcmpestrm128 (v16qi, int, v16qi, int, const int); 22619 int __builtin_ia32_pcmpestri128 (v16qi, int, v16qi, int, const int); 22620 int __builtin_ia32_pcmpestria128 (v16qi, int, v16qi, int, const int); 22621 int __builtin_ia32_pcmpestric128 (v16qi, int, v16qi, int, const int); 22622 int __builtin_ia32_pcmpestrio128 (v16qi, int, v16qi, int, const int); 22623 int __builtin_ia32_pcmpestris128 (v16qi, int, v16qi, int, const int); 22624 int __builtin_ia32_pcmpestriz128 (v16qi, int, v16qi, int, const int); 22625 v16qi __builtin_ia32_pcmpistrm128 (v16qi, v16qi, const int); 22626 int __builtin_ia32_pcmpistri128 (v16qi, v16qi, const int); 22627 int __builtin_ia32_pcmpistria128 (v16qi, v16qi, const int); 22628 int __builtin_ia32_pcmpistric128 (v16qi, v16qi, const int); 22629 int __builtin_ia32_pcmpistrio128 (v16qi, v16qi, const int); 22630 int __builtin_ia32_pcmpistris128 (v16qi, v16qi, const int); 22631 int __builtin_ia32_pcmpistriz128 (v16qi, v16qi, const int); 22632 v2di __builtin_ia32_pcmpgtq (v2di, v2di); 22633 @end smallexample 22634 22635 The following built-in functions are available when @option{-msse4.2} is 22636 used. 22637 22638 @table @code 22639 @item unsigned int __builtin_ia32_crc32qi (unsigned int, unsigned char) 22640 Generates the @code{crc32b} machine instruction. 22641 @item unsigned int __builtin_ia32_crc32hi (unsigned int, unsigned short) 22642 Generates the @code{crc32w} machine instruction. 22643 @item unsigned int __builtin_ia32_crc32si (unsigned int, unsigned int) 22644 Generates the @code{crc32l} machine instruction. 22645 @item unsigned long long __builtin_ia32_crc32di (unsigned long long, unsigned long long) 22646 Generates the @code{crc32q} machine instruction. 22647 @end table 22648 22649 The following built-in functions are changed to generate new SSE4.2 22650 instructions when @option{-msse4.2} is used. 22651 22652 @table @code 22653 @item int __builtin_popcount (unsigned int) 22654 Generates the @code{popcntl} machine instruction. 22655 @item int __builtin_popcountl (unsigned long) 22656 Generates the @code{popcntl} or @code{popcntq} machine instruction, 22657 depending on the size of @code{unsigned long}. 22658 @item int __builtin_popcountll (unsigned long long) 22659 Generates the @code{popcntq} machine instruction. 22660 @end table 22661 22662 The following built-in functions are available when @option{-mavx} is 22663 used. All of them generate the machine instruction that is part of the 22664 name. 22665 22666 @smallexample 22667 v4df __builtin_ia32_addpd256 (v4df,v4df); 22668 v8sf __builtin_ia32_addps256 (v8sf,v8sf); 22669 v4df __builtin_ia32_addsubpd256 (v4df,v4df); 22670 v8sf __builtin_ia32_addsubps256 (v8sf,v8sf); 22671 v4df __builtin_ia32_andnpd256 (v4df,v4df); 22672 v8sf __builtin_ia32_andnps256 (v8sf,v8sf); 22673 v4df __builtin_ia32_andpd256 (v4df,v4df); 22674 v8sf __builtin_ia32_andps256 (v8sf,v8sf); 22675 v4df __builtin_ia32_blendpd256 (v4df,v4df,int); 22676 v8sf __builtin_ia32_blendps256 (v8sf,v8sf,int); 22677 v4df __builtin_ia32_blendvpd256 (v4df,v4df,v4df); 22678 v8sf __builtin_ia32_blendvps256 (v8sf,v8sf,v8sf); 22679 v2df __builtin_ia32_cmppd (v2df,v2df,int); 22680 v4df __builtin_ia32_cmppd256 (v4df,v4df,int); 22681 v4sf __builtin_ia32_cmpps (v4sf,v4sf,int); 22682 v8sf __builtin_ia32_cmpps256 (v8sf,v8sf,int); 22683 v2df __builtin_ia32_cmpsd (v2df,v2df,int); 22684 v4sf __builtin_ia32_cmpss (v4sf,v4sf,int); 22685 v4df __builtin_ia32_cvtdq2pd256 (v4si); 22686 v8sf __builtin_ia32_cvtdq2ps256 (v8si); 22687 v4si __builtin_ia32_cvtpd2dq256 (v4df); 22688 v4sf __builtin_ia32_cvtpd2ps256 (v4df); 22689 v8si __builtin_ia32_cvtps2dq256 (v8sf); 22690 v4df __builtin_ia32_cvtps2pd256 (v4sf); 22691 v4si __builtin_ia32_cvttpd2dq256 (v4df); 22692 v8si __builtin_ia32_cvttps2dq256 (v8sf); 22693 v4df __builtin_ia32_divpd256 (v4df,v4df); 22694 v8sf __builtin_ia32_divps256 (v8sf,v8sf); 22695 v8sf __builtin_ia32_dpps256 (v8sf,v8sf,int); 22696 v4df __builtin_ia32_haddpd256 (v4df,v4df); 22697 v8sf __builtin_ia32_haddps256 (v8sf,v8sf); 22698 v4df __builtin_ia32_hsubpd256 (v4df,v4df); 22699 v8sf __builtin_ia32_hsubps256 (v8sf,v8sf); 22700 v32qi __builtin_ia32_lddqu256 (pcchar); 22701 v32qi __builtin_ia32_loaddqu256 (pcchar); 22702 v4df __builtin_ia32_loadupd256 (pcdouble); 22703 v8sf __builtin_ia32_loadups256 (pcfloat); 22704 v2df __builtin_ia32_maskloadpd (pcv2df,v2df); 22705 v4df __builtin_ia32_maskloadpd256 (pcv4df,v4df); 22706 v4sf __builtin_ia32_maskloadps (pcv4sf,v4sf); 22707 v8sf __builtin_ia32_maskloadps256 (pcv8sf,v8sf); 22708 void __builtin_ia32_maskstorepd (pv2df,v2df,v2df); 22709 void __builtin_ia32_maskstorepd256 (pv4df,v4df,v4df); 22710 void __builtin_ia32_maskstoreps (pv4sf,v4sf,v4sf); 22711 void __builtin_ia32_maskstoreps256 (pv8sf,v8sf,v8sf); 22712 v4df __builtin_ia32_maxpd256 (v4df,v4df); 22713 v8sf __builtin_ia32_maxps256 (v8sf,v8sf); 22714 v4df __builtin_ia32_minpd256 (v4df,v4df); 22715 v8sf __builtin_ia32_minps256 (v8sf,v8sf); 22716 v4df __builtin_ia32_movddup256 (v4df); 22717 int __builtin_ia32_movmskpd256 (v4df); 22718 int __builtin_ia32_movmskps256 (v8sf); 22719 v8sf __builtin_ia32_movshdup256 (v8sf); 22720 v8sf __builtin_ia32_movsldup256 (v8sf); 22721 v4df __builtin_ia32_mulpd256 (v4df,v4df); 22722 v8sf __builtin_ia32_mulps256 (v8sf,v8sf); 22723 v4df __builtin_ia32_orpd256 (v4df,v4df); 22724 v8sf __builtin_ia32_orps256 (v8sf,v8sf); 22725 v2df __builtin_ia32_pd_pd256 (v4df); 22726 v4df __builtin_ia32_pd256_pd (v2df); 22727 v4sf __builtin_ia32_ps_ps256 (v8sf); 22728 v8sf __builtin_ia32_ps256_ps (v4sf); 22729 int __builtin_ia32_ptestc256 (v4di,v4di,ptest); 22730 int __builtin_ia32_ptestnzc256 (v4di,v4di,ptest); 22731 int __builtin_ia32_ptestz256 (v4di,v4di,ptest); 22732 v8sf __builtin_ia32_rcpps256 (v8sf); 22733 v4df __builtin_ia32_roundpd256 (v4df,int); 22734 v8sf __builtin_ia32_roundps256 (v8sf,int); 22735 v8sf __builtin_ia32_rsqrtps_nr256 (v8sf); 22736 v8sf __builtin_ia32_rsqrtps256 (v8sf); 22737 v4df __builtin_ia32_shufpd256 (v4df,v4df,int); 22738 v8sf __builtin_ia32_shufps256 (v8sf,v8sf,int); 22739 v4si __builtin_ia32_si_si256 (v8si); 22740 v8si __builtin_ia32_si256_si (v4si); 22741 v4df __builtin_ia32_sqrtpd256 (v4df); 22742 v8sf __builtin_ia32_sqrtps_nr256 (v8sf); 22743 v8sf __builtin_ia32_sqrtps256 (v8sf); 22744 void __builtin_ia32_storedqu256 (pchar,v32qi); 22745 void __builtin_ia32_storeupd256 (pdouble,v4df); 22746 void __builtin_ia32_storeups256 (pfloat,v8sf); 22747 v4df __builtin_ia32_subpd256 (v4df,v4df); 22748 v8sf __builtin_ia32_subps256 (v8sf,v8sf); 22749 v4df __builtin_ia32_unpckhpd256 (v4df,v4df); 22750 v8sf __builtin_ia32_unpckhps256 (v8sf,v8sf); 22751 v4df __builtin_ia32_unpcklpd256 (v4df,v4df); 22752 v8sf __builtin_ia32_unpcklps256 (v8sf,v8sf); 22753 v4df __builtin_ia32_vbroadcastf128_pd256 (pcv2df); 22754 v8sf __builtin_ia32_vbroadcastf128_ps256 (pcv4sf); 22755 v4df __builtin_ia32_vbroadcastsd256 (pcdouble); 22756 v4sf __builtin_ia32_vbroadcastss (pcfloat); 22757 v8sf __builtin_ia32_vbroadcastss256 (pcfloat); 22758 v2df __builtin_ia32_vextractf128_pd256 (v4df,int); 22759 v4sf __builtin_ia32_vextractf128_ps256 (v8sf,int); 22760 v4si __builtin_ia32_vextractf128_si256 (v8si,int); 22761 v4df __builtin_ia32_vinsertf128_pd256 (v4df,v2df,int); 22762 v8sf __builtin_ia32_vinsertf128_ps256 (v8sf,v4sf,int); 22763 v8si __builtin_ia32_vinsertf128_si256 (v8si,v4si,int); 22764 v4df __builtin_ia32_vperm2f128_pd256 (v4df,v4df,int); 22765 v8sf __builtin_ia32_vperm2f128_ps256 (v8sf,v8sf,int); 22766 v8si __builtin_ia32_vperm2f128_si256 (v8si,v8si,int); 22767 v2df __builtin_ia32_vpermil2pd (v2df,v2df,v2di,int); 22768 v4df __builtin_ia32_vpermil2pd256 (v4df,v4df,v4di,int); 22769 v4sf __builtin_ia32_vpermil2ps (v4sf,v4sf,v4si,int); 22770 v8sf __builtin_ia32_vpermil2ps256 (v8sf,v8sf,v8si,int); 22771 v2df __builtin_ia32_vpermilpd (v2df,int); 22772 v4df __builtin_ia32_vpermilpd256 (v4df,int); 22773 v4sf __builtin_ia32_vpermilps (v4sf,int); 22774 v8sf __builtin_ia32_vpermilps256 (v8sf,int); 22775 v2df __builtin_ia32_vpermilvarpd (v2df,v2di); 22776 v4df __builtin_ia32_vpermilvarpd256 (v4df,v4di); 22777 v4sf __builtin_ia32_vpermilvarps (v4sf,v4si); 22778 v8sf __builtin_ia32_vpermilvarps256 (v8sf,v8si); 22779 int __builtin_ia32_vtestcpd (v2df,v2df,ptest); 22780 int __builtin_ia32_vtestcpd256 (v4df,v4df,ptest); 22781 int __builtin_ia32_vtestcps (v4sf,v4sf,ptest); 22782 int __builtin_ia32_vtestcps256 (v8sf,v8sf,ptest); 22783 int __builtin_ia32_vtestnzcpd (v2df,v2df,ptest); 22784 int __builtin_ia32_vtestnzcpd256 (v4df,v4df,ptest); 22785 int __builtin_ia32_vtestnzcps (v4sf,v4sf,ptest); 22786 int __builtin_ia32_vtestnzcps256 (v8sf,v8sf,ptest); 22787 int __builtin_ia32_vtestzpd (v2df,v2df,ptest); 22788 int __builtin_ia32_vtestzpd256 (v4df,v4df,ptest); 22789 int __builtin_ia32_vtestzps (v4sf,v4sf,ptest); 22790 int __builtin_ia32_vtestzps256 (v8sf,v8sf,ptest); 22791 void __builtin_ia32_vzeroall (void); 22792 void __builtin_ia32_vzeroupper (void); 22793 v4df __builtin_ia32_xorpd256 (v4df,v4df); 22794 v8sf __builtin_ia32_xorps256 (v8sf,v8sf); 22795 @end smallexample 22796 22797 The following built-in functions are available when @option{-mavx2} is 22798 used. All of them generate the machine instruction that is part of the 22799 name. 22800 22801 @smallexample 22802 v32qi __builtin_ia32_mpsadbw256 (v32qi,v32qi,int); 22803 v32qi __builtin_ia32_pabsb256 (v32qi); 22804 v16hi __builtin_ia32_pabsw256 (v16hi); 22805 v8si __builtin_ia32_pabsd256 (v8si); 22806 v16hi __builtin_ia32_packssdw256 (v8si,v8si); 22807 v32qi __builtin_ia32_packsswb256 (v16hi,v16hi); 22808 v16hi __builtin_ia32_packusdw256 (v8si,v8si); 22809 v32qi __builtin_ia32_packuswb256 (v16hi,v16hi); 22810 v32qi __builtin_ia32_paddb256 (v32qi,v32qi); 22811 v16hi __builtin_ia32_paddw256 (v16hi,v16hi); 22812 v8si __builtin_ia32_paddd256 (v8si,v8si); 22813 v4di __builtin_ia32_paddq256 (v4di,v4di); 22814 v32qi __builtin_ia32_paddsb256 (v32qi,v32qi); 22815 v16hi __builtin_ia32_paddsw256 (v16hi,v16hi); 22816 v32qi __builtin_ia32_paddusb256 (v32qi,v32qi); 22817 v16hi __builtin_ia32_paddusw256 (v16hi,v16hi); 22818 v4di __builtin_ia32_palignr256 (v4di,v4di,int); 22819 v4di __builtin_ia32_andsi256 (v4di,v4di); 22820 v4di __builtin_ia32_andnotsi256 (v4di,v4di); 22821 v32qi __builtin_ia32_pavgb256 (v32qi,v32qi); 22822 v16hi __builtin_ia32_pavgw256 (v16hi,v16hi); 22823 v32qi __builtin_ia32_pblendvb256 (v32qi,v32qi,v32qi); 22824 v16hi __builtin_ia32_pblendw256 (v16hi,v16hi,int); 22825 v32qi __builtin_ia32_pcmpeqb256 (v32qi,v32qi); 22826 v16hi __builtin_ia32_pcmpeqw256 (v16hi,v16hi); 22827 v8si __builtin_ia32_pcmpeqd256 (c8si,v8si); 22828 v4di __builtin_ia32_pcmpeqq256 (v4di,v4di); 22829 v32qi __builtin_ia32_pcmpgtb256 (v32qi,v32qi); 22830 v16hi __builtin_ia32_pcmpgtw256 (16hi,v16hi); 22831 v8si __builtin_ia32_pcmpgtd256 (v8si,v8si); 22832 v4di __builtin_ia32_pcmpgtq256 (v4di,v4di); 22833 v16hi __builtin_ia32_phaddw256 (v16hi,v16hi); 22834 v8si __builtin_ia32_phaddd256 (v8si,v8si); 22835 v16hi __builtin_ia32_phaddsw256 (v16hi,v16hi); 22836 v16hi __builtin_ia32_phsubw256 (v16hi,v16hi); 22837 v8si __builtin_ia32_phsubd256 (v8si,v8si); 22838 v16hi __builtin_ia32_phsubsw256 (v16hi,v16hi); 22839 v32qi __builtin_ia32_pmaddubsw256 (v32qi,v32qi); 22840 v16hi __builtin_ia32_pmaddwd256 (v16hi,v16hi); 22841 v32qi __builtin_ia32_pmaxsb256 (v32qi,v32qi); 22842 v16hi __builtin_ia32_pmaxsw256 (v16hi,v16hi); 22843 v8si __builtin_ia32_pmaxsd256 (v8si,v8si); 22844 v32qi __builtin_ia32_pmaxub256 (v32qi,v32qi); 22845 v16hi __builtin_ia32_pmaxuw256 (v16hi,v16hi); 22846 v8si __builtin_ia32_pmaxud256 (v8si,v8si); 22847 v32qi __builtin_ia32_pminsb256 (v32qi,v32qi); 22848 v16hi __builtin_ia32_pminsw256 (v16hi,v16hi); 22849 v8si __builtin_ia32_pminsd256 (v8si,v8si); 22850 v32qi __builtin_ia32_pminub256 (v32qi,v32qi); 22851 v16hi __builtin_ia32_pminuw256 (v16hi,v16hi); 22852 v8si __builtin_ia32_pminud256 (v8si,v8si); 22853 int __builtin_ia32_pmovmskb256 (v32qi); 22854 v16hi __builtin_ia32_pmovsxbw256 (v16qi); 22855 v8si __builtin_ia32_pmovsxbd256 (v16qi); 22856 v4di __builtin_ia32_pmovsxbq256 (v16qi); 22857 v8si __builtin_ia32_pmovsxwd256 (v8hi); 22858 v4di __builtin_ia32_pmovsxwq256 (v8hi); 22859 v4di __builtin_ia32_pmovsxdq256 (v4si); 22860 v16hi __builtin_ia32_pmovzxbw256 (v16qi); 22861 v8si __builtin_ia32_pmovzxbd256 (v16qi); 22862 v4di __builtin_ia32_pmovzxbq256 (v16qi); 22863 v8si __builtin_ia32_pmovzxwd256 (v8hi); 22864 v4di __builtin_ia32_pmovzxwq256 (v8hi); 22865 v4di __builtin_ia32_pmovzxdq256 (v4si); 22866 v4di __builtin_ia32_pmuldq256 (v8si,v8si); 22867 v16hi __builtin_ia32_pmulhrsw256 (v16hi, v16hi); 22868 v16hi __builtin_ia32_pmulhuw256 (v16hi,v16hi); 22869 v16hi __builtin_ia32_pmulhw256 (v16hi,v16hi); 22870 v16hi __builtin_ia32_pmullw256 (v16hi,v16hi); 22871 v8si __builtin_ia32_pmulld256 (v8si,v8si); 22872 v4di __builtin_ia32_pmuludq256 (v8si,v8si); 22873 v4di __builtin_ia32_por256 (v4di,v4di); 22874 v16hi __builtin_ia32_psadbw256 (v32qi,v32qi); 22875 v32qi __builtin_ia32_pshufb256 (v32qi,v32qi); 22876 v8si __builtin_ia32_pshufd256 (v8si,int); 22877 v16hi __builtin_ia32_pshufhw256 (v16hi,int); 22878 v16hi __builtin_ia32_pshuflw256 (v16hi,int); 22879 v32qi __builtin_ia32_psignb256 (v32qi,v32qi); 22880 v16hi __builtin_ia32_psignw256 (v16hi,v16hi); 22881 v8si __builtin_ia32_psignd256 (v8si,v8si); 22882 v4di __builtin_ia32_pslldqi256 (v4di,int); 22883 v16hi __builtin_ia32_psllwi256 (16hi,int); 22884 v16hi __builtin_ia32_psllw256(v16hi,v8hi); 22885 v8si __builtin_ia32_pslldi256 (v8si,int); 22886 v8si __builtin_ia32_pslld256(v8si,v4si); 22887 v4di __builtin_ia32_psllqi256 (v4di,int); 22888 v4di __builtin_ia32_psllq256(v4di,v2di); 22889 v16hi __builtin_ia32_psrawi256 (v16hi,int); 22890 v16hi __builtin_ia32_psraw256 (v16hi,v8hi); 22891 v8si __builtin_ia32_psradi256 (v8si,int); 22892 v8si __builtin_ia32_psrad256 (v8si,v4si); 22893 v4di __builtin_ia32_psrldqi256 (v4di, int); 22894 v16hi __builtin_ia32_psrlwi256 (v16hi,int); 22895 v16hi __builtin_ia32_psrlw256 (v16hi,v8hi); 22896 v8si __builtin_ia32_psrldi256 (v8si,int); 22897 v8si __builtin_ia32_psrld256 (v8si,v4si); 22898 v4di __builtin_ia32_psrlqi256 (v4di,int); 22899 v4di __builtin_ia32_psrlq256(v4di,v2di); 22900 v32qi __builtin_ia32_psubb256 (v32qi,v32qi); 22901 v32hi __builtin_ia32_psubw256 (v16hi,v16hi); 22902 v8si __builtin_ia32_psubd256 (v8si,v8si); 22903 v4di __builtin_ia32_psubq256 (v4di,v4di); 22904 v32qi __builtin_ia32_psubsb256 (v32qi,v32qi); 22905 v16hi __builtin_ia32_psubsw256 (v16hi,v16hi); 22906 v32qi __builtin_ia32_psubusb256 (v32qi,v32qi); 22907 v16hi __builtin_ia32_psubusw256 (v16hi,v16hi); 22908 v32qi __builtin_ia32_punpckhbw256 (v32qi,v32qi); 22909 v16hi __builtin_ia32_punpckhwd256 (v16hi,v16hi); 22910 v8si __builtin_ia32_punpckhdq256 (v8si,v8si); 22911 v4di __builtin_ia32_punpckhqdq256 (v4di,v4di); 22912 v32qi __builtin_ia32_punpcklbw256 (v32qi,v32qi); 22913 v16hi __builtin_ia32_punpcklwd256 (v16hi,v16hi); 22914 v8si __builtin_ia32_punpckldq256 (v8si,v8si); 22915 v4di __builtin_ia32_punpcklqdq256 (v4di,v4di); 22916 v4di __builtin_ia32_pxor256 (v4di,v4di); 22917 v4di __builtin_ia32_movntdqa256 (pv4di); 22918 v4sf __builtin_ia32_vbroadcastss_ps (v4sf); 22919 v8sf __builtin_ia32_vbroadcastss_ps256 (v4sf); 22920 v4df __builtin_ia32_vbroadcastsd_pd256 (v2df); 22921 v4di __builtin_ia32_vbroadcastsi256 (v2di); 22922 v4si __builtin_ia32_pblendd128 (v4si,v4si); 22923 v8si __builtin_ia32_pblendd256 (v8si,v8si); 22924 v32qi __builtin_ia32_pbroadcastb256 (v16qi); 22925 v16hi __builtin_ia32_pbroadcastw256 (v8hi); 22926 v8si __builtin_ia32_pbroadcastd256 (v4si); 22927 v4di __builtin_ia32_pbroadcastq256 (v2di); 22928 v16qi __builtin_ia32_pbroadcastb128 (v16qi); 22929 v8hi __builtin_ia32_pbroadcastw128 (v8hi); 22930 v4si __builtin_ia32_pbroadcastd128 (v4si); 22931 v2di __builtin_ia32_pbroadcastq128 (v2di); 22932 v8si __builtin_ia32_permvarsi256 (v8si,v8si); 22933 v4df __builtin_ia32_permdf256 (v4df,int); 22934 v8sf __builtin_ia32_permvarsf256 (v8sf,v8sf); 22935 v4di __builtin_ia32_permdi256 (v4di,int); 22936 v4di __builtin_ia32_permti256 (v4di,v4di,int); 22937 v4di __builtin_ia32_extract128i256 (v4di,int); 22938 v4di __builtin_ia32_insert128i256 (v4di,v2di,int); 22939 v8si __builtin_ia32_maskloadd256 (pcv8si,v8si); 22940 v4di __builtin_ia32_maskloadq256 (pcv4di,v4di); 22941 v4si __builtin_ia32_maskloadd (pcv4si,v4si); 22942 v2di __builtin_ia32_maskloadq (pcv2di,v2di); 22943 void __builtin_ia32_maskstored256 (pv8si,v8si,v8si); 22944 void __builtin_ia32_maskstoreq256 (pv4di,v4di,v4di); 22945 void __builtin_ia32_maskstored (pv4si,v4si,v4si); 22946 void __builtin_ia32_maskstoreq (pv2di,v2di,v2di); 22947 v8si __builtin_ia32_psllv8si (v8si,v8si); 22948 v4si __builtin_ia32_psllv4si (v4si,v4si); 22949 v4di __builtin_ia32_psllv4di (v4di,v4di); 22950 v2di __builtin_ia32_psllv2di (v2di,v2di); 22951 v8si __builtin_ia32_psrav8si (v8si,v8si); 22952 v4si __builtin_ia32_psrav4si (v4si,v4si); 22953 v8si __builtin_ia32_psrlv8si (v8si,v8si); 22954 v4si __builtin_ia32_psrlv4si (v4si,v4si); 22955 v4di __builtin_ia32_psrlv4di (v4di,v4di); 22956 v2di __builtin_ia32_psrlv2di (v2di,v2di); 22957 v2df __builtin_ia32_gathersiv2df (v2df, pcdouble,v4si,v2df,int); 22958 v4df __builtin_ia32_gathersiv4df (v4df, pcdouble,v4si,v4df,int); 22959 v2df __builtin_ia32_gatherdiv2df (v2df, pcdouble,v2di,v2df,int); 22960 v4df __builtin_ia32_gatherdiv4df (v4df, pcdouble,v4di,v4df,int); 22961 v4sf __builtin_ia32_gathersiv4sf (v4sf, pcfloat,v4si,v4sf,int); 22962 v8sf __builtin_ia32_gathersiv8sf (v8sf, pcfloat,v8si,v8sf,int); 22963 v4sf __builtin_ia32_gatherdiv4sf (v4sf, pcfloat,v2di,v4sf,int); 22964 v4sf __builtin_ia32_gatherdiv4sf256 (v4sf, pcfloat,v4di,v4sf,int); 22965 v2di __builtin_ia32_gathersiv2di (v2di, pcint64,v4si,v2di,int); 22966 v4di __builtin_ia32_gathersiv4di (v4di, pcint64,v4si,v4di,int); 22967 v2di __builtin_ia32_gatherdiv2di (v2di, pcint64,v2di,v2di,int); 22968 v4di __builtin_ia32_gatherdiv4di (v4di, pcint64,v4di,v4di,int); 22969 v4si __builtin_ia32_gathersiv4si (v4si, pcint,v4si,v4si,int); 22970 v8si __builtin_ia32_gathersiv8si (v8si, pcint,v8si,v8si,int); 22971 v4si __builtin_ia32_gatherdiv4si (v4si, pcint,v2di,v4si,int); 22972 v4si __builtin_ia32_gatherdiv4si256 (v4si, pcint,v4di,v4si,int); 22973 @end smallexample 22974 22975 The following built-in functions are available when @option{-maes} is 22976 used. All of them generate the machine instruction that is part of the 22977 name. 22978 22979 @smallexample 22980 v2di __builtin_ia32_aesenc128 (v2di, v2di); 22981 v2di __builtin_ia32_aesenclast128 (v2di, v2di); 22982 v2di __builtin_ia32_aesdec128 (v2di, v2di); 22983 v2di __builtin_ia32_aesdeclast128 (v2di, v2di); 22984 v2di __builtin_ia32_aeskeygenassist128 (v2di, const int); 22985 v2di __builtin_ia32_aesimc128 (v2di); 22986 @end smallexample 22987 22988 The following built-in function is available when @option{-mpclmul} is 22989 used. 22990 22991 @table @code 22992 @item v2di __builtin_ia32_pclmulqdq128 (v2di, v2di, const int) 22993 Generates the @code{pclmulqdq} machine instruction. 22994 @end table 22995 22996 The following built-in function is available when @option{-mfsgsbase} is 22997 used. All of them generate the machine instruction that is part of the 22998 name. 22999 23000 @smallexample 23001 unsigned int __builtin_ia32_rdfsbase32 (void); 23002 unsigned long long __builtin_ia32_rdfsbase64 (void); 23003 unsigned int __builtin_ia32_rdgsbase32 (void); 23004 unsigned long long __builtin_ia32_rdgsbase64 (void); 23005 void _writefsbase_u32 (unsigned int); 23006 void _writefsbase_u64 (unsigned long long); 23007 void _writegsbase_u32 (unsigned int); 23008 void _writegsbase_u64 (unsigned long long); 23009 @end smallexample 23010 23011 The following built-in function is available when @option{-mrdrnd} is 23012 used. All of them generate the machine instruction that is part of the 23013 name. 23014 23015 @smallexample 23016 unsigned int __builtin_ia32_rdrand16_step (unsigned short *); 23017 unsigned int __builtin_ia32_rdrand32_step (unsigned int *); 23018 unsigned int __builtin_ia32_rdrand64_step (unsigned long long *); 23019 @end smallexample 23020 23021 The following built-in function is available when @option{-mptwrite} is 23022 used. All of them generate the machine instruction that is part of the 23023 name. 23024 23025 @smallexample 23026 void __builtin_ia32_ptwrite32 (unsigned); 23027 void __builtin_ia32_ptwrite64 (unsigned long long); 23028 @end smallexample 23029 23030 The following built-in functions are available when @option{-msse4a} is used. 23031 All of them generate the machine instruction that is part of the name. 23032 23033 @smallexample 23034 void __builtin_ia32_movntsd (double *, v2df); 23035 void __builtin_ia32_movntss (float *, v4sf); 23036 v2di __builtin_ia32_extrq (v2di, v16qi); 23037 v2di __builtin_ia32_extrqi (v2di, const unsigned int, const unsigned int); 23038 v2di __builtin_ia32_insertq (v2di, v2di); 23039 v2di __builtin_ia32_insertqi (v2di, v2di, const unsigned int, const unsigned int); 23040 @end smallexample 23041 23042 The following built-in functions are available when @option{-mxop} is used. 23043 @smallexample 23044 v2df __builtin_ia32_vfrczpd (v2df); 23045 v4sf __builtin_ia32_vfrczps (v4sf); 23046 v2df __builtin_ia32_vfrczsd (v2df); 23047 v4sf __builtin_ia32_vfrczss (v4sf); 23048 v4df __builtin_ia32_vfrczpd256 (v4df); 23049 v8sf __builtin_ia32_vfrczps256 (v8sf); 23050 v2di __builtin_ia32_vpcmov (v2di, v2di, v2di); 23051 v2di __builtin_ia32_vpcmov_v2di (v2di, v2di, v2di); 23052 v4si __builtin_ia32_vpcmov_v4si (v4si, v4si, v4si); 23053 v8hi __builtin_ia32_vpcmov_v8hi (v8hi, v8hi, v8hi); 23054 v16qi __builtin_ia32_vpcmov_v16qi (v16qi, v16qi, v16qi); 23055 v2df __builtin_ia32_vpcmov_v2df (v2df, v2df, v2df); 23056 v4sf __builtin_ia32_vpcmov_v4sf (v4sf, v4sf, v4sf); 23057 v4di __builtin_ia32_vpcmov_v4di256 (v4di, v4di, v4di); 23058 v8si __builtin_ia32_vpcmov_v8si256 (v8si, v8si, v8si); 23059 v16hi __builtin_ia32_vpcmov_v16hi256 (v16hi, v16hi, v16hi); 23060 v32qi __builtin_ia32_vpcmov_v32qi256 (v32qi, v32qi, v32qi); 23061 v4df __builtin_ia32_vpcmov_v4df256 (v4df, v4df, v4df); 23062 v8sf __builtin_ia32_vpcmov_v8sf256 (v8sf, v8sf, v8sf); 23063 v16qi __builtin_ia32_vpcomeqb (v16qi, v16qi); 23064 v8hi __builtin_ia32_vpcomeqw (v8hi, v8hi); 23065 v4si __builtin_ia32_vpcomeqd (v4si, v4si); 23066 v2di __builtin_ia32_vpcomeqq (v2di, v2di); 23067 v16qi __builtin_ia32_vpcomequb (v16qi, v16qi); 23068 v4si __builtin_ia32_vpcomequd (v4si, v4si); 23069 v2di __builtin_ia32_vpcomequq (v2di, v2di); 23070 v8hi __builtin_ia32_vpcomequw (v8hi, v8hi); 23071 v8hi __builtin_ia32_vpcomeqw (v8hi, v8hi); 23072 v16qi __builtin_ia32_vpcomfalseb (v16qi, v16qi); 23073 v4si __builtin_ia32_vpcomfalsed (v4si, v4si); 23074 v2di __builtin_ia32_vpcomfalseq (v2di, v2di); 23075 v16qi __builtin_ia32_vpcomfalseub (v16qi, v16qi); 23076 v4si __builtin_ia32_vpcomfalseud (v4si, v4si); 23077 v2di __builtin_ia32_vpcomfalseuq (v2di, v2di); 23078 v8hi __builtin_ia32_vpcomfalseuw (v8hi, v8hi); 23079 v8hi __builtin_ia32_vpcomfalsew (v8hi, v8hi); 23080 v16qi __builtin_ia32_vpcomgeb (v16qi, v16qi); 23081 v4si __builtin_ia32_vpcomged (v4si, v4si); 23082 v2di __builtin_ia32_vpcomgeq (v2di, v2di); 23083 v16qi __builtin_ia32_vpcomgeub (v16qi, v16qi); 23084 v4si __builtin_ia32_vpcomgeud (v4si, v4si); 23085 v2di __builtin_ia32_vpcomgeuq (v2di, v2di); 23086 v8hi __builtin_ia32_vpcomgeuw (v8hi, v8hi); 23087 v8hi __builtin_ia32_vpcomgew (v8hi, v8hi); 23088 v16qi __builtin_ia32_vpcomgtb (v16qi, v16qi); 23089 v4si __builtin_ia32_vpcomgtd (v4si, v4si); 23090 v2di __builtin_ia32_vpcomgtq (v2di, v2di); 23091 v16qi __builtin_ia32_vpcomgtub (v16qi, v16qi); 23092 v4si __builtin_ia32_vpcomgtud (v4si, v4si); 23093 v2di __builtin_ia32_vpcomgtuq (v2di, v2di); 23094 v8hi __builtin_ia32_vpcomgtuw (v8hi, v8hi); 23095 v8hi __builtin_ia32_vpcomgtw (v8hi, v8hi); 23096 v16qi __builtin_ia32_vpcomleb (v16qi, v16qi); 23097 v4si __builtin_ia32_vpcomled (v4si, v4si); 23098 v2di __builtin_ia32_vpcomleq (v2di, v2di); 23099 v16qi __builtin_ia32_vpcomleub (v16qi, v16qi); 23100 v4si __builtin_ia32_vpcomleud (v4si, v4si); 23101 v2di __builtin_ia32_vpcomleuq (v2di, v2di); 23102 v8hi __builtin_ia32_vpcomleuw (v8hi, v8hi); 23103 v8hi __builtin_ia32_vpcomlew (v8hi, v8hi); 23104 v16qi __builtin_ia32_vpcomltb (v16qi, v16qi); 23105 v4si __builtin_ia32_vpcomltd (v4si, v4si); 23106 v2di __builtin_ia32_vpcomltq (v2di, v2di); 23107 v16qi __builtin_ia32_vpcomltub (v16qi, v16qi); 23108 v4si __builtin_ia32_vpcomltud (v4si, v4si); 23109 v2di __builtin_ia32_vpcomltuq (v2di, v2di); 23110 v8hi __builtin_ia32_vpcomltuw (v8hi, v8hi); 23111 v8hi __builtin_ia32_vpcomltw (v8hi, v8hi); 23112 v16qi __builtin_ia32_vpcomneb (v16qi, v16qi); 23113 v4si __builtin_ia32_vpcomned (v4si, v4si); 23114 v2di __builtin_ia32_vpcomneq (v2di, v2di); 23115 v16qi __builtin_ia32_vpcomneub (v16qi, v16qi); 23116 v4si __builtin_ia32_vpcomneud (v4si, v4si); 23117 v2di __builtin_ia32_vpcomneuq (v2di, v2di); 23118 v8hi __builtin_ia32_vpcomneuw (v8hi, v8hi); 23119 v8hi __builtin_ia32_vpcomnew (v8hi, v8hi); 23120 v16qi __builtin_ia32_vpcomtrueb (v16qi, v16qi); 23121 v4si __builtin_ia32_vpcomtrued (v4si, v4si); 23122 v2di __builtin_ia32_vpcomtrueq (v2di, v2di); 23123 v16qi __builtin_ia32_vpcomtrueub (v16qi, v16qi); 23124 v4si __builtin_ia32_vpcomtrueud (v4si, v4si); 23125 v2di __builtin_ia32_vpcomtrueuq (v2di, v2di); 23126 v8hi __builtin_ia32_vpcomtrueuw (v8hi, v8hi); 23127 v8hi __builtin_ia32_vpcomtruew (v8hi, v8hi); 23128 v4si __builtin_ia32_vphaddbd (v16qi); 23129 v2di __builtin_ia32_vphaddbq (v16qi); 23130 v8hi __builtin_ia32_vphaddbw (v16qi); 23131 v2di __builtin_ia32_vphadddq (v4si); 23132 v4si __builtin_ia32_vphaddubd (v16qi); 23133 v2di __builtin_ia32_vphaddubq (v16qi); 23134 v8hi __builtin_ia32_vphaddubw (v16qi); 23135 v2di __builtin_ia32_vphaddudq (v4si); 23136 v4si __builtin_ia32_vphadduwd (v8hi); 23137 v2di __builtin_ia32_vphadduwq (v8hi); 23138 v4si __builtin_ia32_vphaddwd (v8hi); 23139 v2di __builtin_ia32_vphaddwq (v8hi); 23140 v8hi __builtin_ia32_vphsubbw (v16qi); 23141 v2di __builtin_ia32_vphsubdq (v4si); 23142 v4si __builtin_ia32_vphsubwd (v8hi); 23143 v4si __builtin_ia32_vpmacsdd (v4si, v4si, v4si); 23144 v2di __builtin_ia32_vpmacsdqh (v4si, v4si, v2di); 23145 v2di __builtin_ia32_vpmacsdql (v4si, v4si, v2di); 23146 v4si __builtin_ia32_vpmacssdd (v4si, v4si, v4si); 23147 v2di __builtin_ia32_vpmacssdqh (v4si, v4si, v2di); 23148 v2di __builtin_ia32_vpmacssdql (v4si, v4si, v2di); 23149 v4si __builtin_ia32_vpmacsswd (v8hi, v8hi, v4si); 23150 v8hi __builtin_ia32_vpmacssww (v8hi, v8hi, v8hi); 23151 v4si __builtin_ia32_vpmacswd (v8hi, v8hi, v4si); 23152 v8hi __builtin_ia32_vpmacsww (v8hi, v8hi, v8hi); 23153 v4si __builtin_ia32_vpmadcsswd (v8hi, v8hi, v4si); 23154 v4si __builtin_ia32_vpmadcswd (v8hi, v8hi, v4si); 23155 v16qi __builtin_ia32_vpperm (v16qi, v16qi, v16qi); 23156 v16qi __builtin_ia32_vprotb (v16qi, v16qi); 23157 v4si __builtin_ia32_vprotd (v4si, v4si); 23158 v2di __builtin_ia32_vprotq (v2di, v2di); 23159 v8hi __builtin_ia32_vprotw (v8hi, v8hi); 23160 v16qi __builtin_ia32_vpshab (v16qi, v16qi); 23161 v4si __builtin_ia32_vpshad (v4si, v4si); 23162 v2di __builtin_ia32_vpshaq (v2di, v2di); 23163 v8hi __builtin_ia32_vpshaw (v8hi, v8hi); 23164 v16qi __builtin_ia32_vpshlb (v16qi, v16qi); 23165 v4si __builtin_ia32_vpshld (v4si, v4si); 23166 v2di __builtin_ia32_vpshlq (v2di, v2di); 23167 v8hi __builtin_ia32_vpshlw (v8hi, v8hi); 23168 @end smallexample 23169 23170 The following built-in functions are available when @option{-mfma4} is used. 23171 All of them generate the machine instruction that is part of the name. 23172 23173 @smallexample 23174 v2df __builtin_ia32_vfmaddpd (v2df, v2df, v2df); 23175 v4sf __builtin_ia32_vfmaddps (v4sf, v4sf, v4sf); 23176 v2df __builtin_ia32_vfmaddsd (v2df, v2df, v2df); 23177 v4sf __builtin_ia32_vfmaddss (v4sf, v4sf, v4sf); 23178 v2df __builtin_ia32_vfmsubpd (v2df, v2df, v2df); 23179 v4sf __builtin_ia32_vfmsubps (v4sf, v4sf, v4sf); 23180 v2df __builtin_ia32_vfmsubsd (v2df, v2df, v2df); 23181 v4sf __builtin_ia32_vfmsubss (v4sf, v4sf, v4sf); 23182 v2df __builtin_ia32_vfnmaddpd (v2df, v2df, v2df); 23183 v4sf __builtin_ia32_vfnmaddps (v4sf, v4sf, v4sf); 23184 v2df __builtin_ia32_vfnmaddsd (v2df, v2df, v2df); 23185 v4sf __builtin_ia32_vfnmaddss (v4sf, v4sf, v4sf); 23186 v2df __builtin_ia32_vfnmsubpd (v2df, v2df, v2df); 23187 v4sf __builtin_ia32_vfnmsubps (v4sf, v4sf, v4sf); 23188 v2df __builtin_ia32_vfnmsubsd (v2df, v2df, v2df); 23189 v4sf __builtin_ia32_vfnmsubss (v4sf, v4sf, v4sf); 23190 v2df __builtin_ia32_vfmaddsubpd (v2df, v2df, v2df); 23191 v4sf __builtin_ia32_vfmaddsubps (v4sf, v4sf, v4sf); 23192 v2df __builtin_ia32_vfmsubaddpd (v2df, v2df, v2df); 23193 v4sf __builtin_ia32_vfmsubaddps (v4sf, v4sf, v4sf); 23194 v4df __builtin_ia32_vfmaddpd256 (v4df, v4df, v4df); 23195 v8sf __builtin_ia32_vfmaddps256 (v8sf, v8sf, v8sf); 23196 v4df __builtin_ia32_vfmsubpd256 (v4df, v4df, v4df); 23197 v8sf __builtin_ia32_vfmsubps256 (v8sf, v8sf, v8sf); 23198 v4df __builtin_ia32_vfnmaddpd256 (v4df, v4df, v4df); 23199 v8sf __builtin_ia32_vfnmaddps256 (v8sf, v8sf, v8sf); 23200 v4df __builtin_ia32_vfnmsubpd256 (v4df, v4df, v4df); 23201 v8sf __builtin_ia32_vfnmsubps256 (v8sf, v8sf, v8sf); 23202 v4df __builtin_ia32_vfmaddsubpd256 (v4df, v4df, v4df); 23203 v8sf __builtin_ia32_vfmaddsubps256 (v8sf, v8sf, v8sf); 23204 v4df __builtin_ia32_vfmsubaddpd256 (v4df, v4df, v4df); 23205 v8sf __builtin_ia32_vfmsubaddps256 (v8sf, v8sf, v8sf); 23206 23207 @end smallexample 23208 23209 The following built-in functions are available when @option{-mlwp} is used. 23210 23211 @smallexample 23212 void __builtin_ia32_llwpcb16 (void *); 23213 void __builtin_ia32_llwpcb32 (void *); 23214 void __builtin_ia32_llwpcb64 (void *); 23215 void * __builtin_ia32_llwpcb16 (void); 23216 void * __builtin_ia32_llwpcb32 (void); 23217 void * __builtin_ia32_llwpcb64 (void); 23218 void __builtin_ia32_lwpval16 (unsigned short, unsigned int, unsigned short); 23219 void __builtin_ia32_lwpval32 (unsigned int, unsigned int, unsigned int); 23220 void __builtin_ia32_lwpval64 (unsigned __int64, unsigned int, unsigned int); 23221 unsigned char __builtin_ia32_lwpins16 (unsigned short, unsigned int, unsigned short); 23222 unsigned char __builtin_ia32_lwpins32 (unsigned int, unsigned int, unsigned int); 23223 unsigned char __builtin_ia32_lwpins64 (unsigned __int64, unsigned int, unsigned int); 23224 @end smallexample 23225 23226 The following built-in functions are available when @option{-mbmi} is used. 23227 All of them generate the machine instruction that is part of the name. 23228 @smallexample 23229 unsigned int __builtin_ia32_bextr_u32(unsigned int, unsigned int); 23230 unsigned long long __builtin_ia32_bextr_u64 (unsigned long long, unsigned long long); 23231 @end smallexample 23232 23233 The following built-in functions are available when @option{-mbmi2} is used. 23234 All of them generate the machine instruction that is part of the name. 23235 @smallexample 23236 unsigned int _bzhi_u32 (unsigned int, unsigned int); 23237 unsigned int _pdep_u32 (unsigned int, unsigned int); 23238 unsigned int _pext_u32 (unsigned int, unsigned int); 23239 unsigned long long _bzhi_u64 (unsigned long long, unsigned long long); 23240 unsigned long long _pdep_u64 (unsigned long long, unsigned long long); 23241 unsigned long long _pext_u64 (unsigned long long, unsigned long long); 23242 @end smallexample 23243 23244 The following built-in functions are available when @option{-mlzcnt} is used. 23245 All of them generate the machine instruction that is part of the name. 23246 @smallexample 23247 unsigned short __builtin_ia32_lzcnt_u16(unsigned short); 23248 unsigned int __builtin_ia32_lzcnt_u32(unsigned int); 23249 unsigned long long __builtin_ia32_lzcnt_u64 (unsigned long long); 23250 @end smallexample 23251 23252 The following built-in functions are available when @option{-mfxsr} is used. 23253 All of them generate the machine instruction that is part of the name. 23254 @smallexample 23255 void __builtin_ia32_fxsave (void *); 23256 void __builtin_ia32_fxrstor (void *); 23257 void __builtin_ia32_fxsave64 (void *); 23258 void __builtin_ia32_fxrstor64 (void *); 23259 @end smallexample 23260 23261 The following built-in functions are available when @option{-mxsave} is used. 23262 All of them generate the machine instruction that is part of the name. 23263 @smallexample 23264 void __builtin_ia32_xsave (void *, long long); 23265 void __builtin_ia32_xrstor (void *, long long); 23266 void __builtin_ia32_xsave64 (void *, long long); 23267 void __builtin_ia32_xrstor64 (void *, long long); 23268 @end smallexample 23269 23270 The following built-in functions are available when @option{-mxsaveopt} is used. 23271 All of them generate the machine instruction that is part of the name. 23272 @smallexample 23273 void __builtin_ia32_xsaveopt (void *, long long); 23274 void __builtin_ia32_xsaveopt64 (void *, long long); 23275 @end smallexample 23276 23277 The following built-in functions are available when @option{-mtbm} is used. 23278 Both of them generate the immediate form of the bextr machine instruction. 23279 @smallexample 23280 unsigned int __builtin_ia32_bextri_u32 (unsigned int, 23281 const unsigned int); 23282 unsigned long long __builtin_ia32_bextri_u64 (unsigned long long, 23283 const unsigned long long); 23284 @end smallexample 23285 23286 23287 The following built-in functions are available when @option{-m3dnow} is used. 23288 All of them generate the machine instruction that is part of the name. 23289 23290 @smallexample 23291 void __builtin_ia32_femms (void); 23292 v8qi __builtin_ia32_pavgusb (v8qi, v8qi); 23293 v2si __builtin_ia32_pf2id (v2sf); 23294 v2sf __builtin_ia32_pfacc (v2sf, v2sf); 23295 v2sf __builtin_ia32_pfadd (v2sf, v2sf); 23296 v2si __builtin_ia32_pfcmpeq (v2sf, v2sf); 23297 v2si __builtin_ia32_pfcmpge (v2sf, v2sf); 23298 v2si __builtin_ia32_pfcmpgt (v2sf, v2sf); 23299 v2sf __builtin_ia32_pfmax (v2sf, v2sf); 23300 v2sf __builtin_ia32_pfmin (v2sf, v2sf); 23301 v2sf __builtin_ia32_pfmul (v2sf, v2sf); 23302 v2sf __builtin_ia32_pfrcp (v2sf); 23303 v2sf __builtin_ia32_pfrcpit1 (v2sf, v2sf); 23304 v2sf __builtin_ia32_pfrcpit2 (v2sf, v2sf); 23305 v2sf __builtin_ia32_pfrsqrt (v2sf); 23306 v2sf __builtin_ia32_pfsub (v2sf, v2sf); 23307 v2sf __builtin_ia32_pfsubr (v2sf, v2sf); 23308 v2sf __builtin_ia32_pi2fd (v2si); 23309 v4hi __builtin_ia32_pmulhrw (v4hi, v4hi); 23310 @end smallexample 23311 23312 The following built-in functions are available when @option{-m3dnowa} is used. 23313 All of them generate the machine instruction that is part of the name. 23314 23315 @smallexample 23316 v2si __builtin_ia32_pf2iw (v2sf); 23317 v2sf __builtin_ia32_pfnacc (v2sf, v2sf); 23318 v2sf __builtin_ia32_pfpnacc (v2sf, v2sf); 23319 v2sf __builtin_ia32_pi2fw (v2si); 23320 v2sf __builtin_ia32_pswapdsf (v2sf); 23321 v2si __builtin_ia32_pswapdsi (v2si); 23322 @end smallexample 23323 23324 The following built-in functions are available when @option{-mrtm} is used 23325 They are used for restricted transactional memory. These are the internal 23326 low level functions. Normally the functions in 23327 @ref{x86 transactional memory intrinsics} should be used instead. 23328 23329 @smallexample 23330 int __builtin_ia32_xbegin (); 23331 void __builtin_ia32_xend (); 23332 void __builtin_ia32_xabort (status); 23333 int __builtin_ia32_xtest (); 23334 @end smallexample 23335 23336 The following built-in functions are available when @option{-mmwaitx} is used. 23337 All of them generate the machine instruction that is part of the name. 23338 @smallexample 23339 void __builtin_ia32_monitorx (void *, unsigned int, unsigned int); 23340 void __builtin_ia32_mwaitx (unsigned int, unsigned int, unsigned int); 23341 @end smallexample 23342 23343 The following built-in functions are available when @option{-mclzero} is used. 23344 All of them generate the machine instruction that is part of the name. 23345 @smallexample 23346 void __builtin_i32_clzero (void *); 23347 @end smallexample 23348 23349 The following built-in functions are available when @option{-mpku} is used. 23350 They generate reads and writes to PKRU. 23351 @smallexample 23352 void __builtin_ia32_wrpkru (unsigned int); 23353 unsigned int __builtin_ia32_rdpkru (); 23354 @end smallexample 23355 23356 The following built-in functions are available when 23357 @option{-mshstk} option is used. They support shadow stack 23358 machine instructions from Intel Control-flow Enforcement Technology (CET). 23359 Each built-in function generates the machine instruction that is part 23360 of the function's name. These are the internal low-level functions. 23361 Normally the functions in @ref{x86 control-flow protection intrinsics} 23362 should be used instead. 23363 23364 @smallexample 23365 unsigned int __builtin_ia32_rdsspd (void); 23366 unsigned long long __builtin_ia32_rdsspq (void); 23367 void __builtin_ia32_incsspd (unsigned int); 23368 void __builtin_ia32_incsspq (unsigned long long); 23369 void __builtin_ia32_saveprevssp(void); 23370 void __builtin_ia32_rstorssp(void *); 23371 void __builtin_ia32_wrssd(unsigned int, void *); 23372 void __builtin_ia32_wrssq(unsigned long long, void *); 23373 void __builtin_ia32_wrussd(unsigned int, void *); 23374 void __builtin_ia32_wrussq(unsigned long long, void *); 23375 void __builtin_ia32_setssbsy(void); 23376 void __builtin_ia32_clrssbsy(void *); 23377 @end smallexample 23378 23379 @node x86 transactional memory intrinsics 23380 @subsection x86 Transactional Memory Intrinsics 23381 23382 These hardware transactional memory intrinsics for x86 allow you to use 23383 memory transactions with RTM (Restricted Transactional Memory). 23384 This support is enabled with the @option{-mrtm} option. 23385 For using HLE (Hardware Lock Elision) see 23386 @ref{x86 specific memory model extensions for transactional memory} instead. 23387 23388 A memory transaction commits all changes to memory in an atomic way, 23389 as visible to other threads. If the transaction fails it is rolled back 23390 and all side effects discarded. 23391 23392 Generally there is no guarantee that a memory transaction ever succeeds 23393 and suitable fallback code always needs to be supplied. 23394 23395 @deftypefn {RTM Function} {unsigned} _xbegin () 23396 Start a RTM (Restricted Transactional Memory) transaction. 23397 Returns @code{_XBEGIN_STARTED} when the transaction 23398 started successfully (note this is not 0, so the constant has to be 23399 explicitly tested). 23400 23401 If the transaction aborts, all side effects 23402 are undone and an abort code encoded as a bit mask is returned. 23403 The following macros are defined: 23404 23405 @table @code 23406 @item _XABORT_EXPLICIT 23407 Transaction was explicitly aborted with @code{_xabort}. The parameter passed 23408 to @code{_xabort} is available with @code{_XABORT_CODE(status)}. 23409 @item _XABORT_RETRY 23410 Transaction retry is possible. 23411 @item _XABORT_CONFLICT 23412 Transaction abort due to a memory conflict with another thread. 23413 @item _XABORT_CAPACITY 23414 Transaction abort due to the transaction using too much memory. 23415 @item _XABORT_DEBUG 23416 Transaction abort due to a debug trap. 23417 @item _XABORT_NESTED 23418 Transaction abort in an inner nested transaction. 23419 @end table 23420 23421 There is no guarantee 23422 any transaction ever succeeds, so there always needs to be a valid 23423 fallback path. 23424 @end deftypefn 23425 23426 @deftypefn {RTM Function} {void} _xend () 23427 Commit the current transaction. When no transaction is active this faults. 23428 All memory side effects of the transaction become visible 23429 to other threads in an atomic manner. 23430 @end deftypefn 23431 23432 @deftypefn {RTM Function} {int} _xtest () 23433 Return a nonzero value if a transaction is currently active, otherwise 0. 23434 @end deftypefn 23435 23436 @deftypefn {RTM Function} {void} _xabort (status) 23437 Abort the current transaction. When no transaction is active this is a no-op. 23438 The @var{status} is an 8-bit constant; its value is encoded in the return 23439 value from @code{_xbegin}. 23440 @end deftypefn 23441 23442 Here is an example showing handling for @code{_XABORT_RETRY} 23443 and a fallback path for other failures: 23444 23445 @smallexample 23446 #include <immintrin.h> 23447 23448 int n_tries, max_tries; 23449 unsigned status = _XABORT_EXPLICIT; 23450 ... 23451 23452 for (n_tries = 0; n_tries < max_tries; n_tries++) 23453 @{ 23454 status = _xbegin (); 23455 if (status == _XBEGIN_STARTED || !(status & _XABORT_RETRY)) 23456 break; 23457 @} 23458 if (status == _XBEGIN_STARTED) 23459 @{ 23460 ... transaction code... 23461 _xend (); 23462 @} 23463 else 23464 @{ 23465 ... non-transactional fallback path... 23466 @} 23467 @end smallexample 23468 23469 @noindent 23470 Note that, in most cases, the transactional and non-transactional code 23471 must synchronize together to ensure consistency. 23472 23473 @node x86 control-flow protection intrinsics 23474 @subsection x86 Control-Flow Protection Intrinsics 23475 23476 @deftypefn {CET Function} {ret_type} _get_ssp (void) 23477 Get the current value of shadow stack pointer if shadow stack support 23478 from Intel CET is enabled in the hardware or @code{0} otherwise. 23479 The @code{ret_type} is @code{unsigned long long} for 64-bit targets 23480 and @code{unsigned int} for 32-bit targets. 23481 @end deftypefn 23482 23483 @deftypefn {CET Function} void _inc_ssp (unsigned int) 23484 Increment the current shadow stack pointer by the size specified by the 23485 function argument. The argument is masked to a byte value for security 23486 reasons, so to increment by more than 255 bytes you must call the function 23487 multiple times. 23488 @end deftypefn 23489 23490 The shadow stack unwind code looks like: 23491 23492 @smallexample 23493 #include <immintrin.h> 23494 23495 /* Unwind the shadow stack for EH. */ 23496 #define _Unwind_Frames_Extra(x) \ 23497 do \ 23498 @{ \ 23499 _Unwind_Word ssp = _get_ssp (); \ 23500 if (ssp != 0) \ 23501 @{ \ 23502 _Unwind_Word tmp = (x); \ 23503 while (tmp > 255) \ 23504 @{ \ 23505 _inc_ssp (tmp); \ 23506 tmp -= 255; \ 23507 @} \ 23508 _inc_ssp (tmp); \ 23509 @} \ 23510 @} \ 23511 while (0) 23512 @end smallexample 23513 23514 @noindent 23515 This code runs unconditionally on all 64-bit processors. For 32-bit 23516 processors the code runs on those that support multi-byte NOP instructions. 23517 23518 @node Target Format Checks 23519 @section Format Checks Specific to Particular Target Machines 23520 23521 For some target machines, GCC supports additional options to the 23522 format attribute 23523 (@pxref{Function Attributes,,Declaring Attributes of Functions}). 23524 23525 @menu 23526 * Solaris Format Checks:: 23527 * Darwin Format Checks:: 23528 @end menu 23529 23530 @node Solaris Format Checks 23531 @subsection Solaris Format Checks 23532 23533 Solaris targets support the @code{cmn_err} (or @code{__cmn_err__}) format 23534 check. @code{cmn_err} accepts a subset of the standard @code{printf} 23535 conversions, and the two-argument @code{%b} conversion for displaying 23536 bit-fields. See the Solaris man page for @code{cmn_err} for more information. 23537 23538 @node Darwin Format Checks 23539 @subsection Darwin Format Checks 23540 23541 In addition to the full set of format archetypes (attribute format style 23542 arguments such as @code{printf}, @code{scanf}, @code{strftime}, and 23543 @code{strfmon}), Darwin targets also support the @code{CFString} (or 23544 @code{__CFString__}) archetype in the @code{format} attribute. 23545 Declarations with this archetype are parsed for correct syntax 23546 and argument types. However, parsing of the format string itself and 23547 validating arguments against it in calls to such functions is currently 23548 not performed. 23549 23550 Additionally, @code{CFStringRefs} (defined by the @code{CoreFoundation} headers) may 23551 also be used as format arguments. Note that the relevant headers are only likely to be 23552 available on Darwin (OSX) installations. On such installations, the XCode and system 23553 documentation provide descriptions of @code{CFString}, @code{CFStringRefs} and 23554 associated functions. 23555 23556 @node Pragmas 23557 @section Pragmas Accepted by GCC 23558 @cindex pragmas 23559 @cindex @code{#pragma} 23560 23561 GCC supports several types of pragmas, primarily in order to compile 23562 code originally written for other compilers. Note that in general 23563 we do not recommend the use of pragmas; @xref{Function Attributes}, 23564 for further explanation. 23565 23566 The GNU C preprocessor recognizes several pragmas in addition to the 23567 compiler pragmas documented here. Refer to the CPP manual for more 23568 information. 23569 23570 @menu 23571 * AArch64 Pragmas:: 23572 * ARM Pragmas:: 23573 * M32C Pragmas:: 23574 * MeP Pragmas:: 23575 * PRU Pragmas:: 23576 * RS/6000 and PowerPC Pragmas:: 23577 * S/390 Pragmas:: 23578 * Darwin Pragmas:: 23579 * Solaris Pragmas:: 23580 * Symbol-Renaming Pragmas:: 23581 * Structure-Layout Pragmas:: 23582 * Weak Pragmas:: 23583 * Diagnostic Pragmas:: 23584 * Visibility Pragmas:: 23585 * Push/Pop Macro Pragmas:: 23586 * Function Specific Option Pragmas:: 23587 * Loop-Specific Pragmas:: 23588 @end menu 23589 23590 @node AArch64 Pragmas 23591 @subsection AArch64 Pragmas 23592 23593 The pragmas defined by the AArch64 target correspond to the AArch64 23594 target function attributes. They can be specified as below: 23595 @smallexample 23596 #pragma GCC target("string") 23597 @end smallexample 23598 23599 where @code{@var{string}} can be any string accepted as an AArch64 target 23600 attribute. @xref{AArch64 Function Attributes}, for more details 23601 on the permissible values of @code{string}. 23602 23603 @node ARM Pragmas 23604 @subsection ARM Pragmas 23605 23606 The ARM target defines pragmas for controlling the default addition of 23607 @code{long_call} and @code{short_call} attributes to functions. 23608 @xref{Function Attributes}, for information about the effects of these 23609 attributes. 23610 23611 @table @code 23612 @item long_calls 23613 @cindex pragma, long_calls 23614 Set all subsequent functions to have the @code{long_call} attribute. 23615 23616 @item no_long_calls 23617 @cindex pragma, no_long_calls 23618 Set all subsequent functions to have the @code{short_call} attribute. 23619 23620 @item long_calls_off 23621 @cindex pragma, long_calls_off 23622 Do not affect the @code{long_call} or @code{short_call} attributes of 23623 subsequent functions. 23624 @end table 23625 23626 @node M32C Pragmas 23627 @subsection M32C Pragmas 23628 23629 @table @code 23630 @item GCC memregs @var{number} 23631 @cindex pragma, memregs 23632 Overrides the command-line option @code{-memregs=} for the current 23633 file. Use with care! This pragma must be before any function in the 23634 file, and mixing different memregs values in different objects may 23635 make them incompatible. This pragma is useful when a 23636 performance-critical function uses a memreg for temporary values, 23637 as it may allow you to reduce the number of memregs used. 23638 23639 @item ADDRESS @var{name} @var{address} 23640 @cindex pragma, address 23641 For any declared symbols matching @var{name}, this does three things 23642 to that symbol: it forces the symbol to be located at the given 23643 address (a number), it forces the symbol to be volatile, and it 23644 changes the symbol's scope to be static. This pragma exists for 23645 compatibility with other compilers, but note that the common 23646 @code{1234H} numeric syntax is not supported (use @code{0x1234} 23647 instead). Example: 23648 23649 @smallexample 23650 #pragma ADDRESS port3 0x103 23651 char port3; 23652 @end smallexample 23653 23654 @end table 23655 23656 @node MeP Pragmas 23657 @subsection MeP Pragmas 23658 23659 @table @code 23660 23661 @item custom io_volatile (on|off) 23662 @cindex pragma, custom io_volatile 23663 Overrides the command-line option @code{-mio-volatile} for the current 23664 file. Note that for compatibility with future GCC releases, this 23665 option should only be used once before any @code{io} variables in each 23666 file. 23667 23668 @item GCC coprocessor available @var{registers} 23669 @cindex pragma, coprocessor available 23670 Specifies which coprocessor registers are available to the register 23671 allocator. @var{registers} may be a single register, register range 23672 separated by ellipses, or comma-separated list of those. Example: 23673 23674 @smallexample 23675 #pragma GCC coprocessor available $c0...$c10, $c28 23676 @end smallexample 23677 23678 @item GCC coprocessor call_saved @var{registers} 23679 @cindex pragma, coprocessor call_saved 23680 Specifies which coprocessor registers are to be saved and restored by 23681 any function using them. @var{registers} may be a single register, 23682 register range separated by ellipses, or comma-separated list of 23683 those. Example: 23684 23685 @smallexample 23686 #pragma GCC coprocessor call_saved $c4...$c6, $c31 23687 @end smallexample 23688 23689 @item GCC coprocessor subclass '(A|B|C|D)' = @var{registers} 23690 @cindex pragma, coprocessor subclass 23691 Creates and defines a register class. These register classes can be 23692 used by inline @code{asm} constructs. @var{registers} may be a single 23693 register, register range separated by ellipses, or comma-separated 23694 list of those. Example: 23695 23696 @smallexample 23697 #pragma GCC coprocessor subclass 'B' = $c2, $c4, $c6 23698 23699 asm ("cpfoo %0" : "=B" (x)); 23700 @end smallexample 23701 23702 @item GCC disinterrupt @var{name} , @var{name} @dots{} 23703 @cindex pragma, disinterrupt 23704 For the named functions, the compiler adds code to disable interrupts 23705 for the duration of those functions. If any functions so named 23706 are not encountered in the source, a warning is emitted that the pragma is 23707 not used. Examples: 23708 23709 @smallexample 23710 #pragma disinterrupt foo 23711 #pragma disinterrupt bar, grill 23712 int foo () @{ @dots{} @} 23713 @end smallexample 23714 23715 @item GCC call @var{name} , @var{name} @dots{} 23716 @cindex pragma, call 23717 For the named functions, the compiler always uses a register-indirect 23718 call model when calling the named functions. Examples: 23719 23720 @smallexample 23721 extern int foo (); 23722 #pragma call foo 23723 @end smallexample 23724 23725 @end table 23726 23727 @node PRU Pragmas 23728 @subsection PRU Pragmas 23729 23730 @table @code 23731 23732 @item ctable_entry @var{index} @var{constant_address} 23733 @cindex pragma, ctable_entry 23734 Specifies that the PRU CTABLE entry given by @var{index} has the value 23735 @var{constant_address}. This enables GCC to emit LBCO/SBCO instructions 23736 when the load/store address is known and can be addressed with some CTABLE 23737 entry. For example: 23738 23739 @smallexample 23740 /* will compile to "sbco Rx, 2, 0x10, 4" */ 23741 #pragma ctable_entry 2 0x4802a000 23742 *(unsigned int *)0x4802a010 = val; 23743 @end smallexample 23744 23745 @end table 23746 23747 @node RS/6000 and PowerPC Pragmas 23748 @subsection RS/6000 and PowerPC Pragmas 23749 23750 The RS/6000 and PowerPC targets define one pragma for controlling 23751 whether or not the @code{longcall} attribute is added to function 23752 declarations by default. This pragma overrides the @option{-mlongcall} 23753 option, but not the @code{longcall} and @code{shortcall} attributes. 23754 @xref{RS/6000 and PowerPC Options}, for more information about when long 23755 calls are and are not necessary. 23756 23757 @table @code 23758 @item longcall (1) 23759 @cindex pragma, longcall 23760 Apply the @code{longcall} attribute to all subsequent function 23761 declarations. 23762 23763 @item longcall (0) 23764 Do not apply the @code{longcall} attribute to subsequent function 23765 declarations. 23766 @end table 23767 23768 @c Describe h8300 pragmas here. 23769 @c Describe sh pragmas here. 23770 @c Describe v850 pragmas here. 23771 23772 @node S/390 Pragmas 23773 @subsection S/390 Pragmas 23774 23775 The pragmas defined by the S/390 target correspond to the S/390 23776 target function attributes and some the additional options: 23777 23778 @table @samp 23779 @item zvector 23780 @itemx no-zvector 23781 @end table 23782 23783 Note that options of the pragma, unlike options of the target 23784 attribute, do change the value of preprocessor macros like 23785 @code{__VEC__}. They can be specified as below: 23786 23787 @smallexample 23788 #pragma GCC target("string[,string]...") 23789 #pragma GCC target("string"[,"string"]...) 23790 @end smallexample 23791 23792 @node Darwin Pragmas 23793 @subsection Darwin Pragmas 23794 23795 The following pragmas are available for all architectures running the 23796 Darwin operating system. These are useful for compatibility with other 23797 Mac OS compilers. 23798 23799 @table @code 23800 @item mark @var{tokens}@dots{} 23801 @cindex pragma, mark 23802 This pragma is accepted, but has no effect. 23803 23804 @item options align=@var{alignment} 23805 @cindex pragma, options align 23806 This pragma sets the alignment of fields in structures. The values of 23807 @var{alignment} may be @code{mac68k}, to emulate m68k alignment, or 23808 @code{power}, to emulate PowerPC alignment. Uses of this pragma nest 23809 properly; to restore the previous setting, use @code{reset} for the 23810 @var{alignment}. 23811 23812 @item segment @var{tokens}@dots{} 23813 @cindex pragma, segment 23814 This pragma is accepted, but has no effect. 23815 23816 @item unused (@var{var} [, @var{var}]@dots{}) 23817 @cindex pragma, unused 23818 This pragma declares variables to be possibly unused. GCC does not 23819 produce warnings for the listed variables. The effect is similar to 23820 that of the @code{unused} attribute, except that this pragma may appear 23821 anywhere within the variables' scopes. 23822 @end table 23823 23824 @node Solaris Pragmas 23825 @subsection Solaris Pragmas 23826 23827 The Solaris target supports @code{#pragma redefine_extname} 23828 (@pxref{Symbol-Renaming Pragmas}). It also supports additional 23829 @code{#pragma} directives for compatibility with the system compiler. 23830 23831 @table @code 23832 @item align @var{alignment} (@var{variable} [, @var{variable}]...) 23833 @cindex pragma, align 23834 23835 Increase the minimum alignment of each @var{variable} to @var{alignment}. 23836 This is the same as GCC's @code{aligned} attribute @pxref{Variable 23837 Attributes}). Macro expansion occurs on the arguments to this pragma 23838 when compiling C and Objective-C@. It does not currently occur when 23839 compiling C++, but this is a bug which may be fixed in a future 23840 release. 23841 23842 @item fini (@var{function} [, @var{function}]...) 23843 @cindex pragma, fini 23844 23845 This pragma causes each listed @var{function} to be called after 23846 main, or during shared module unloading, by adding a call to the 23847 @code{.fini} section. 23848 23849 @item init (@var{function} [, @var{function}]...) 23850 @cindex pragma, init 23851 23852 This pragma causes each listed @var{function} to be called during 23853 initialization (before @code{main}) or during shared module loading, by 23854 adding a call to the @code{.init} section. 23855 23856 @end table 23857 23858 @node Symbol-Renaming Pragmas 23859 @subsection Symbol-Renaming Pragmas 23860 23861 GCC supports a @code{#pragma} directive that changes the name used in 23862 assembly for a given declaration. While this pragma is supported on all 23863 platforms, it is intended primarily to provide compatibility with the 23864 Solaris system headers. This effect can also be achieved using the asm 23865 labels extension (@pxref{Asm Labels}). 23866 23867 @table @code 23868 @item redefine_extname @var{oldname} @var{newname} 23869 @cindex pragma, redefine_extname 23870 23871 This pragma gives the C function @var{oldname} the assembly symbol 23872 @var{newname}. The preprocessor macro @code{__PRAGMA_REDEFINE_EXTNAME} 23873 is defined if this pragma is available (currently on all platforms). 23874 @end table 23875 23876 This pragma and the @code{asm} labels extension interact in a complicated 23877 manner. Here are some corner cases you may want to be aware of: 23878 23879 @enumerate 23880 @item This pragma silently applies only to declarations with external 23881 linkage. The @code{asm} label feature does not have this restriction. 23882 23883 @item In C++, this pragma silently applies only to declarations with 23884 ``C'' linkage. Again, @code{asm} labels do not have this restriction. 23885 23886 @item If either of the ways of changing the assembly name of a 23887 declaration are applied to a declaration whose assembly name has 23888 already been determined (either by a previous use of one of these 23889 features, or because the compiler needed the assembly name in order to 23890 generate code), and the new name is different, a warning issues and 23891 the name does not change. 23892 23893 @item The @var{oldname} used by @code{#pragma redefine_extname} is 23894 always the C-language name. 23895 @end enumerate 23896 23897 @node Structure-Layout Pragmas 23898 @subsection Structure-Layout Pragmas 23899 23900 For compatibility with Microsoft Windows compilers, GCC supports a 23901 set of @code{#pragma} directives that change the maximum alignment of 23902 members of structures (other than zero-width bit-fields), unions, and 23903 classes subsequently defined. The @var{n} value below always is required 23904 to be a small power of two and specifies the new alignment in bytes. 23905 23906 @enumerate 23907 @item @code{#pragma pack(@var{n})} simply sets the new alignment. 23908 @item @code{#pragma pack()} sets the alignment to the one that was in 23909 effect when compilation started (see also command-line option 23910 @option{-fpack-struct[=@var{n}]} @pxref{Code Gen Options}). 23911 @item @code{#pragma pack(push[,@var{n}])} pushes the current alignment 23912 setting on an internal stack and then optionally sets the new alignment. 23913 @item @code{#pragma pack(pop)} restores the alignment setting to the one 23914 saved at the top of the internal stack (and removes that stack entry). 23915 Note that @code{#pragma pack([@var{n}])} does not influence this internal 23916 stack; thus it is possible to have @code{#pragma pack(push)} followed by 23917 multiple @code{#pragma pack(@var{n})} instances and finalized by a single 23918 @code{#pragma pack(pop)}. 23919 @end enumerate 23920 23921 Some targets, e.g.@: x86 and PowerPC, support the @code{#pragma ms_struct} 23922 directive which lays out structures and unions subsequently defined as the 23923 documented @code{__attribute__ ((ms_struct))}. 23924 23925 @enumerate 23926 @item @code{#pragma ms_struct on} turns on the Microsoft layout. 23927 @item @code{#pragma ms_struct off} turns off the Microsoft layout. 23928 @item @code{#pragma ms_struct reset} goes back to the default layout. 23929 @end enumerate 23930 23931 Most targets also support the @code{#pragma scalar_storage_order} directive 23932 which lays out structures and unions subsequently defined as the documented 23933 @code{__attribute__ ((scalar_storage_order))}. 23934 23935 @enumerate 23936 @item @code{#pragma scalar_storage_order big-endian} sets the storage order 23937 of the scalar fields to big-endian. 23938 @item @code{#pragma scalar_storage_order little-endian} sets the storage order 23939 of the scalar fields to little-endian. 23940 @item @code{#pragma scalar_storage_order default} goes back to the endianness 23941 that was in effect when compilation started (see also command-line option 23942 @option{-fsso-struct=@var{endianness}} @pxref{C Dialect Options}). 23943 @end enumerate 23944 23945 @node Weak Pragmas 23946 @subsection Weak Pragmas 23947 23948 For compatibility with SVR4, GCC supports a set of @code{#pragma} 23949 directives for declaring symbols to be weak, and defining weak 23950 aliases. 23951 23952 @table @code 23953 @item #pragma weak @var{symbol} 23954 @cindex pragma, weak 23955 This pragma declares @var{symbol} to be weak, as if the declaration 23956 had the attribute of the same name. The pragma may appear before 23957 or after the declaration of @var{symbol}. It is not an error for 23958 @var{symbol} to never be defined at all. 23959 23960 @item #pragma weak @var{symbol1} = @var{symbol2} 23961 This pragma declares @var{symbol1} to be a weak alias of @var{symbol2}. 23962 It is an error if @var{symbol2} is not defined in the current 23963 translation unit. 23964 @end table 23965 23966 @node Diagnostic Pragmas 23967 @subsection Diagnostic Pragmas 23968 23969 GCC allows the user to selectively enable or disable certain types of 23970 diagnostics, and change the kind of the diagnostic. For example, a 23971 project's policy might require that all sources compile with 23972 @option{-Werror} but certain files might have exceptions allowing 23973 specific types of warnings. Or, a project might selectively enable 23974 diagnostics and treat them as errors depending on which preprocessor 23975 macros are defined. 23976 23977 @table @code 23978 @item #pragma GCC diagnostic @var{kind} @var{option} 23979 @cindex pragma, diagnostic 23980 23981 Modifies the disposition of a diagnostic. Note that not all 23982 diagnostics are modifiable; at the moment only warnings (normally 23983 controlled by @samp{-W@dots{}}) can be controlled, and not all of them. 23984 Use @option{-fdiagnostics-show-option} to determine which diagnostics 23985 are controllable and which option controls them. 23986 23987 @var{kind} is @samp{error} to treat this diagnostic as an error, 23988 @samp{warning} to treat it like a warning (even if @option{-Werror} is 23989 in effect), or @samp{ignored} if the diagnostic is to be ignored. 23990 @var{option} is a double quoted string that matches the command-line 23991 option. 23992 23993 @smallexample 23994 #pragma GCC diagnostic warning "-Wformat" 23995 #pragma GCC diagnostic error "-Wformat" 23996 #pragma GCC diagnostic ignored "-Wformat" 23997 @end smallexample 23998 23999 Note that these pragmas override any command-line options. GCC keeps 24000 track of the location of each pragma, and issues diagnostics according 24001 to the state as of that point in the source file. Thus, pragmas occurring 24002 after a line do not affect diagnostics caused by that line. 24003 24004 @item #pragma GCC diagnostic push 24005 @itemx #pragma GCC diagnostic pop 24006 24007 Causes GCC to remember the state of the diagnostics as of each 24008 @code{push}, and restore to that point at each @code{pop}. If a 24009 @code{pop} has no matching @code{push}, the command-line options are 24010 restored. 24011 24012 @smallexample 24013 #pragma GCC diagnostic error "-Wuninitialized" 24014 foo(a); /* error is given for this one */ 24015 #pragma GCC diagnostic push 24016 #pragma GCC diagnostic ignored "-Wuninitialized" 24017 foo(b); /* no diagnostic for this one */ 24018 #pragma GCC diagnostic pop 24019 foo(c); /* error is given for this one */ 24020 #pragma GCC diagnostic pop 24021 foo(d); /* depends on command-line options */ 24022 @end smallexample 24023 24024 @item #pragma GCC diagnostic ignored_attributes 24025 24026 Similarly to @option{-Wno-attributes=}, this pragma allows users to suppress 24027 warnings about unknown scoped attributes (in C++11 and C2X). For example, 24028 @code{#pragma GCC diagnostic ignored_attributes "vendor::attr"} disables 24029 warning about the following declaration: 24030 24031 @smallexample 24032 [[vendor::attr]] void f(); 24033 @end smallexample 24034 24035 whereas @code{#pragma GCC diagnostic ignored_attributes "vendor::"} prevents 24036 warning about both of these declarations: 24037 24038 @smallexample 24039 [[vendor::safe]] void f(); 24040 [[vendor::unsafe]] void f2(); 24041 @end smallexample 24042 24043 @end table 24044 24045 GCC also offers a simple mechanism for printing messages during 24046 compilation. 24047 24048 @table @code 24049 @item #pragma message @var{string} 24050 @cindex pragma, diagnostic 24051 24052 Prints @var{string} as a compiler message on compilation. The message 24053 is informational only, and is neither a compilation warning nor an 24054 error. Newlines can be included in the string by using the @samp{\n} 24055 escape sequence. 24056 24057 @smallexample 24058 #pragma message "Compiling " __FILE__ "..." 24059 @end smallexample 24060 24061 @var{string} may be parenthesized, and is printed with location 24062 information. For example, 24063 24064 @smallexample 24065 #define DO_PRAGMA(x) _Pragma (#x) 24066 #define TODO(x) DO_PRAGMA(message ("TODO - " #x)) 24067 24068 TODO(Remember to fix this) 24069 @end smallexample 24070 24071 @noindent 24072 prints @samp{/tmp/file.c:4: note: #pragma message: 24073 TODO - Remember to fix this}. 24074 24075 @item #pragma GCC error @var{message} 24076 @cindex pragma, diagnostic 24077 Generates an error message. This pragma @emph{is} considered to 24078 indicate an error in the compilation, and it will be treated as such. 24079 24080 Newlines can be included in the string by using the @samp{\n} 24081 escape sequence. They will be displayed as newlines even if the 24082 @option{-fmessage-length} option is set to zero. 24083 24084 The error is only generated if the pragma is present in the code after 24085 pre-processing has been completed. It does not matter however if the 24086 code containing the pragma is unreachable: 24087 24088 @smallexample 24089 #if 0 24090 #pragma GCC error "this error is not seen" 24091 #endif 24092 void foo (void) 24093 @{ 24094 return; 24095 #pragma GCC error "this error is seen" 24096 @} 24097 @end smallexample 24098 24099 @item #pragma GCC warning @var{message} 24100 @cindex pragma, diagnostic 24101 This is just like @samp{pragma GCC error} except that a warning 24102 message is issued instead of an error message. Unless 24103 @option{-Werror} is in effect, in which case this pragma will generate 24104 an error as well. 24105 24106 @end table 24107 24108 @node Visibility Pragmas 24109 @subsection Visibility Pragmas 24110 24111 @table @code 24112 @item #pragma GCC visibility push(@var{visibility}) 24113 @itemx #pragma GCC visibility pop 24114 @cindex pragma, visibility 24115 24116 This pragma allows the user to set the visibility for multiple 24117 declarations without having to give each a visibility attribute 24118 (@pxref{Function Attributes}). 24119 24120 In C++, @samp{#pragma GCC visibility} affects only namespace-scope 24121 declarations. Class members and template specializations are not 24122 affected; if you want to override the visibility for a particular 24123 member or instantiation, you must use an attribute. 24124 24125 @end table 24126 24127 24128 @node Push/Pop Macro Pragmas 24129 @subsection Push/Pop Macro Pragmas 24130 24131 For compatibility with Microsoft Windows compilers, GCC supports 24132 @samp{#pragma push_macro(@var{"macro_name"})} 24133 and @samp{#pragma pop_macro(@var{"macro_name"})}. 24134 24135 @table @code 24136 @item #pragma push_macro(@var{"macro_name"}) 24137 @cindex pragma, push_macro 24138 This pragma saves the value of the macro named as @var{macro_name} to 24139 the top of the stack for this macro. 24140 24141 @item #pragma pop_macro(@var{"macro_name"}) 24142 @cindex pragma, pop_macro 24143 This pragma sets the value of the macro named as @var{macro_name} to 24144 the value on top of the stack for this macro. If the stack for 24145 @var{macro_name} is empty, the value of the macro remains unchanged. 24146 @end table 24147 24148 For example: 24149 24150 @smallexample 24151 #define X 1 24152 #pragma push_macro("X") 24153 #undef X 24154 #define X -1 24155 #pragma pop_macro("X") 24156 int x [X]; 24157 @end smallexample 24158 24159 @noindent 24160 In this example, the definition of X as 1 is saved by @code{#pragma 24161 push_macro} and restored by @code{#pragma pop_macro}. 24162 24163 @node Function Specific Option Pragmas 24164 @subsection Function Specific Option Pragmas 24165 24166 @table @code 24167 @item #pragma GCC target (@var{string}, @dots{}) 24168 @cindex pragma GCC target 24169 24170 This pragma allows you to set target-specific options for functions 24171 defined later in the source file. One or more strings can be 24172 specified. Each function that is defined after this point is treated 24173 as if it had been declared with one @code{target(}@var{string}@code{)} 24174 attribute for each @var{string} argument. The parentheses around 24175 the strings in the pragma are optional. @xref{Function Attributes}, 24176 for more information about the @code{target} attribute and the attribute 24177 syntax. 24178 24179 The @code{#pragma GCC target} pragma is presently implemented for 24180 x86, ARM, AArch64, PowerPC, S/390, and Nios II targets only. 24181 24182 @item #pragma GCC optimize (@var{string}, @dots{}) 24183 @cindex pragma GCC optimize 24184 24185 This pragma allows you to set global optimization options for functions 24186 defined later in the source file. One or more strings can be 24187 specified. Each function that is defined after this point is treated 24188 as if it had been declared with one @code{optimize(}@var{string}@code{)} 24189 attribute for each @var{string} argument. The parentheses around 24190 the strings in the pragma are optional. @xref{Function Attributes}, 24191 for more information about the @code{optimize} attribute and the attribute 24192 syntax. 24193 24194 @item #pragma GCC push_options 24195 @itemx #pragma GCC pop_options 24196 @cindex pragma GCC push_options 24197 @cindex pragma GCC pop_options 24198 24199 These pragmas maintain a stack of the current target and optimization 24200 options. It is intended for include files where you temporarily want 24201 to switch to using a different @samp{#pragma GCC target} or 24202 @samp{#pragma GCC optimize} and then to pop back to the previous 24203 options. 24204 24205 @item #pragma GCC reset_options 24206 @cindex pragma GCC reset_options 24207 24208 This pragma clears the current @code{#pragma GCC target} and 24209 @code{#pragma GCC optimize} to use the default switches as specified 24210 on the command line. 24211 24212 @end table 24213 24214 @node Loop-Specific Pragmas 24215 @subsection Loop-Specific Pragmas 24216 24217 @table @code 24218 @item #pragma GCC ivdep 24219 @cindex pragma GCC ivdep 24220 24221 With this pragma, the programmer asserts that there are no loop-carried 24222 dependencies which would prevent consecutive iterations of 24223 the following loop from executing concurrently with SIMD 24224 (single instruction multiple data) instructions. 24225 24226 For example, the compiler can only unconditionally vectorize the following 24227 loop with the pragma: 24228 24229 @smallexample 24230 void foo (int n, int *a, int *b, int *c) 24231 @{ 24232 int i, j; 24233 #pragma GCC ivdep 24234 for (i = 0; i < n; ++i) 24235 a[i] = b[i] + c[i]; 24236 @} 24237 @end smallexample 24238 24239 @noindent 24240 In this example, using the @code{restrict} qualifier had the same 24241 effect. In the following example, that would not be possible. Assume 24242 @math{k < -m} or @math{k >= m}. Only with the pragma, the compiler knows 24243 that it can unconditionally vectorize the following loop: 24244 24245 @smallexample 24246 void ignore_vec_dep (int *a, int k, int c, int m) 24247 @{ 24248 #pragma GCC ivdep 24249 for (int i = 0; i < m; i++) 24250 a[i] = a[i + k] * c; 24251 @} 24252 @end smallexample 24253 24254 @item #pragma GCC unroll @var{n} 24255 @cindex pragma GCC unroll @var{n} 24256 24257 You can use this pragma to control how many times a loop should be unrolled. 24258 It must be placed immediately before a @code{for}, @code{while} or @code{do} 24259 loop or a @code{#pragma GCC ivdep}, and applies only to the loop that follows. 24260 @var{n} is an integer constant expression specifying the unrolling factor. 24261 The values of @math{0} and @math{1} block any unrolling of the loop. 24262 24263 @end table 24264 24265 @node Unnamed Fields 24266 @section Unnamed Structure and Union Fields 24267 @cindex @code{struct} 24268 @cindex @code{union} 24269 24270 As permitted by ISO C11 and for compatibility with other compilers, 24271 GCC allows you to define 24272 a structure or union that contains, as fields, structures and unions 24273 without names. For example: 24274 24275 @smallexample 24276 struct @{ 24277 int a; 24278 union @{ 24279 int b; 24280 float c; 24281 @}; 24282 int d; 24283 @} foo; 24284 @end smallexample 24285 24286 @noindent 24287 In this example, you are able to access members of the unnamed 24288 union with code like @samp{foo.b}. Note that only unnamed structs and 24289 unions are allowed, you may not have, for example, an unnamed 24290 @code{int}. 24291 24292 You must never create such structures that cause ambiguous field definitions. 24293 For example, in this structure: 24294 24295 @smallexample 24296 struct @{ 24297 int a; 24298 struct @{ 24299 int a; 24300 @}; 24301 @} foo; 24302 @end smallexample 24303 24304 @noindent 24305 it is ambiguous which @code{a} is being referred to with @samp{foo.a}. 24306 The compiler gives errors for such constructs. 24307 24308 @opindex fms-extensions 24309 Unless @option{-fms-extensions} is used, the unnamed field must be a 24310 structure or union definition without a tag (for example, @samp{struct 24311 @{ int a; @};}). If @option{-fms-extensions} is used, the field may 24312 also be a definition with a tag such as @samp{struct foo @{ int a; 24313 @};}, a reference to a previously defined structure or union such as 24314 @samp{struct foo;}, or a reference to a @code{typedef} name for a 24315 previously defined structure or union type. 24316 24317 @opindex fplan9-extensions 24318 The option @option{-fplan9-extensions} enables 24319 @option{-fms-extensions} as well as two other extensions. First, a 24320 pointer to a structure is automatically converted to a pointer to an 24321 anonymous field for assignments and function calls. For example: 24322 24323 @smallexample 24324 struct s1 @{ int a; @}; 24325 struct s2 @{ struct s1; @}; 24326 extern void f1 (struct s1 *); 24327 void f2 (struct s2 *p) @{ f1 (p); @} 24328 @end smallexample 24329 24330 @noindent 24331 In the call to @code{f1} inside @code{f2}, the pointer @code{p} is 24332 converted into a pointer to the anonymous field. 24333 24334 Second, when the type of an anonymous field is a @code{typedef} for a 24335 @code{struct} or @code{union}, code may refer to the field using the 24336 name of the @code{typedef}. 24337 24338 @smallexample 24339 typedef struct @{ int a; @} s1; 24340 struct s2 @{ s1; @}; 24341 s1 f1 (struct s2 *p) @{ return p->s1; @} 24342 @end smallexample 24343 24344 These usages are only permitted when they are not ambiguous. 24345 24346 @node Thread-Local 24347 @section Thread-Local Storage 24348 @cindex Thread-Local Storage 24349 @cindex @acronym{TLS} 24350 @cindex @code{__thread} 24351 24352 Thread-local storage (@acronym{TLS}) is a mechanism by which variables 24353 are allocated such that there is one instance of the variable per extant 24354 thread. The runtime model GCC uses to implement this originates 24355 in the IA-64 processor-specific ABI, but has since been migrated 24356 to other processors as well. It requires significant support from 24357 the linker (@command{ld}), dynamic linker (@command{ld.so}), and 24358 system libraries (@file{libc.so} and @file{libpthread.so}), so it 24359 is not available everywhere. 24360 24361 At the user level, the extension is visible with a new storage 24362 class keyword: @code{__thread}. For example: 24363 24364 @smallexample 24365 __thread int i; 24366 extern __thread struct state s; 24367 static __thread char *p; 24368 @end smallexample 24369 24370 The @code{__thread} specifier may be used alone, with the @code{extern} 24371 or @code{static} specifiers, but with no other storage class specifier. 24372 When used with @code{extern} or @code{static}, @code{__thread} must appear 24373 immediately after the other storage class specifier. 24374 24375 The @code{__thread} specifier may be applied to any global, file-scoped 24376 static, function-scoped static, or static data member of a class. It may 24377 not be applied to block-scoped automatic or non-static data member. 24378 24379 When the address-of operator is applied to a thread-local variable, it is 24380 evaluated at run time and returns the address of the current thread's 24381 instance of that variable. An address so obtained may be used by any 24382 thread. When a thread terminates, any pointers to thread-local variables 24383 in that thread become invalid. 24384 24385 No static initialization may refer to the address of a thread-local variable. 24386 24387 In C++, if an initializer is present for a thread-local variable, it must 24388 be a @var{constant-expression}, as defined in 5.19.2 of the ANSI/ISO C++ 24389 standard. 24390 24391 See @uref{https://www.akkadia.org/drepper/tls.pdf, 24392 ELF Handling For Thread-Local Storage} for a detailed explanation of 24393 the four thread-local storage addressing models, and how the runtime 24394 is expected to function. 24395 24396 @menu 24397 * C99 Thread-Local Edits:: 24398 * C++98 Thread-Local Edits:: 24399 @end menu 24400 24401 @node C99 Thread-Local Edits 24402 @subsection ISO/IEC 9899:1999 Edits for Thread-Local Storage 24403 24404 The following are a set of changes to ISO/IEC 9899:1999 (aka C99) 24405 that document the exact semantics of the language extension. 24406 24407 @itemize @bullet 24408 @item 24409 @cite{5.1.2 Execution environments} 24410 24411 Add new text after paragraph 1 24412 24413 @quotation 24414 Within either execution environment, a @dfn{thread} is a flow of 24415 control within a program. It is implementation defined whether 24416 or not there may be more than one thread associated with a program. 24417 It is implementation defined how threads beyond the first are 24418 created, the name and type of the function called at thread 24419 startup, and how threads may be terminated. However, objects 24420 with thread storage duration shall be initialized before thread 24421 startup. 24422 @end quotation 24423 24424 @item 24425 @cite{6.2.4 Storage durations of objects} 24426 24427 Add new text before paragraph 3 24428 24429 @quotation 24430 An object whose identifier is declared with the storage-class 24431 specifier @w{@code{__thread}} has @dfn{thread storage duration}. 24432 Its lifetime is the entire execution of the thread, and its 24433 stored value is initialized only once, prior to thread startup. 24434 @end quotation 24435 24436 @item 24437 @cite{6.4.1 Keywords} 24438 24439 Add @code{__thread}. 24440 24441 @item 24442 @cite{6.7.1 Storage-class specifiers} 24443 24444 Add @code{__thread} to the list of storage class specifiers in 24445 paragraph 1. 24446 24447 Change paragraph 2 to 24448 24449 @quotation 24450 With the exception of @code{__thread}, at most one storage-class 24451 specifier may be given [@dots{}]. The @code{__thread} specifier may 24452 be used alone, or immediately following @code{extern} or 24453 @code{static}. 24454 @end quotation 24455 24456 Add new text after paragraph 6 24457 24458 @quotation 24459 The declaration of an identifier for a variable that has 24460 block scope that specifies @code{__thread} shall also 24461 specify either @code{extern} or @code{static}. 24462 24463 The @code{__thread} specifier shall be used only with 24464 variables. 24465 @end quotation 24466 @end itemize 24467 24468 @node C++98 Thread-Local Edits 24469 @subsection ISO/IEC 14882:1998 Edits for Thread-Local Storage 24470 24471 The following are a set of changes to ISO/IEC 14882:1998 (aka C++98) 24472 that document the exact semantics of the language extension. 24473 24474 @itemize @bullet 24475 @item 24476 @b{[intro.execution]} 24477 24478 New text after paragraph 4 24479 24480 @quotation 24481 A @dfn{thread} is a flow of control within the abstract machine. 24482 It is implementation defined whether or not there may be more than 24483 one thread. 24484 @end quotation 24485 24486 New text after paragraph 7 24487 24488 @quotation 24489 It is unspecified whether additional action must be taken to 24490 ensure when and whether side effects are visible to other threads. 24491 @end quotation 24492 24493 @item 24494 @b{[lex.key]} 24495 24496 Add @code{__thread}. 24497 24498 @item 24499 @b{[basic.start.main]} 24500 24501 Add after paragraph 5 24502 24503 @quotation 24504 The thread that begins execution at the @code{main} function is called 24505 the @dfn{main thread}. It is implementation defined how functions 24506 beginning threads other than the main thread are designated or typed. 24507 A function so designated, as well as the @code{main} function, is called 24508 a @dfn{thread startup function}. It is implementation defined what 24509 happens if a thread startup function returns. It is implementation 24510 defined what happens to other threads when any thread calls @code{exit}. 24511 @end quotation 24512 24513 @item 24514 @b{[basic.start.init]} 24515 24516 Add after paragraph 4 24517 24518 @quotation 24519 The storage for an object of thread storage duration shall be 24520 statically initialized before the first statement of the thread startup 24521 function. An object of thread storage duration shall not require 24522 dynamic initialization. 24523 @end quotation 24524 24525 @item 24526 @b{[basic.start.term]} 24527 24528 Add after paragraph 3 24529 24530 @quotation 24531 The type of an object with thread storage duration shall not have a 24532 non-trivial destructor, nor shall it be an array type whose elements 24533 (directly or indirectly) have non-trivial destructors. 24534 @end quotation 24535 24536 @item 24537 @b{[basic.stc]} 24538 24539 Add ``thread storage duration'' to the list in paragraph 1. 24540 24541 Change paragraph 2 24542 24543 @quotation 24544 Thread, static, and automatic storage durations are associated with 24545 objects introduced by declarations [@dots{}]. 24546 @end quotation 24547 24548 Add @code{__thread} to the list of specifiers in paragraph 3. 24549 24550 @item 24551 @b{[basic.stc.thread]} 24552 24553 New section before @b{[basic.stc.static]} 24554 24555 @quotation 24556 The keyword @code{__thread} applied to a non-local object gives the 24557 object thread storage duration. 24558 24559 A local variable or class data member declared both @code{static} 24560 and @code{__thread} gives the variable or member thread storage 24561 duration. 24562 @end quotation 24563 24564 @item 24565 @b{[basic.stc.static]} 24566 24567 Change paragraph 1 24568 24569 @quotation 24570 All objects that have neither thread storage duration, dynamic 24571 storage duration nor are local [@dots{}]. 24572 @end quotation 24573 24574 @item 24575 @b{[dcl.stc]} 24576 24577 Add @code{__thread} to the list in paragraph 1. 24578 24579 Change paragraph 1 24580 24581 @quotation 24582 With the exception of @code{__thread}, at most one 24583 @var{storage-class-specifier} shall appear in a given 24584 @var{decl-specifier-seq}. The @code{__thread} specifier may 24585 be used alone, or immediately following the @code{extern} or 24586 @code{static} specifiers. [@dots{}] 24587 @end quotation 24588 24589 Add after paragraph 5 24590 24591 @quotation 24592 The @code{__thread} specifier can be applied only to the names of objects 24593 and to anonymous unions. 24594 @end quotation 24595 24596 @item 24597 @b{[class.mem]} 24598 24599 Add after paragraph 6 24600 24601 @quotation 24602 Non-@code{static} members shall not be @code{__thread}. 24603 @end quotation 24604 @end itemize 24605 24606 @node Binary constants 24607 @section Binary Constants using the @samp{0b} Prefix 24608 @cindex Binary constants using the @samp{0b} prefix 24609 24610 Integer constants can be written as binary constants, consisting of a 24611 sequence of @samp{0} and @samp{1} digits, prefixed by @samp{0b} or 24612 @samp{0B}. This is particularly useful in environments that operate a 24613 lot on the bit level (like microcontrollers). 24614 24615 The following statements are identical: 24616 24617 @smallexample 24618 i = 42; 24619 i = 0x2a; 24620 i = 052; 24621 i = 0b101010; 24622 @end smallexample 24623 24624 The type of these constants follows the same rules as for octal or 24625 hexadecimal integer constants, so suffixes like @samp{L} or @samp{UL} 24626 can be applied. 24627 24628 @node C++ Extensions 24629 @chapter Extensions to the C++ Language 24630 @cindex extensions, C++ language 24631 @cindex C++ language extensions 24632 24633 The GNU compiler provides these extensions to the C++ language (and you 24634 can also use most of the C language extensions in your C++ programs). If you 24635 want to write code that checks whether these features are available, you can 24636 test for the GNU compiler the same way as for C programs: check for a 24637 predefined macro @code{__GNUC__}. You can also use @code{__GNUG__} to 24638 test specifically for GNU C++ (@pxref{Common Predefined Macros,, 24639 Predefined Macros,cpp,The GNU C Preprocessor}). 24640 24641 @menu 24642 * C++ Volatiles:: What constitutes an access to a volatile object. 24643 * Restricted Pointers:: C99 restricted pointers and references. 24644 * Vague Linkage:: Where G++ puts inlines, vtables and such. 24645 * C++ Interface:: You can use a single C++ header file for both 24646 declarations and definitions. 24647 * Template Instantiation:: Methods for ensuring that exactly one copy of 24648 each needed template instantiation is emitted. 24649 * Bound member functions:: You can extract a function pointer to the 24650 method denoted by a @samp{->*} or @samp{.*} expression. 24651 * C++ Attributes:: Variable, function, and type attributes for C++ only. 24652 * Function Multiversioning:: Declaring multiple function versions. 24653 * Type Traits:: Compiler support for type traits. 24654 * C++ Concepts:: Improved support for generic programming. 24655 * Deprecated Features:: Things will disappear from G++. 24656 * Backwards Compatibility:: Compatibilities with earlier definitions of C++. 24657 @end menu 24658 24659 @node C++ Volatiles 24660 @section When is a Volatile C++ Object Accessed? 24661 @cindex accessing volatiles 24662 @cindex volatile read 24663 @cindex volatile write 24664 @cindex volatile access 24665 24666 The C++ standard differs from the C standard in its treatment of 24667 volatile objects. It fails to specify what constitutes a volatile 24668 access, except to say that C++ should behave in a similar manner to C 24669 with respect to volatiles, where possible. However, the different 24670 lvalueness of expressions between C and C++ complicate the behavior. 24671 G++ behaves the same as GCC for volatile access, @xref{C 24672 Extensions,,Volatiles}, for a description of GCC's behavior. 24673 24674 The C and C++ language specifications differ when an object is 24675 accessed in a void context: 24676 24677 @smallexample 24678 volatile int *src = @var{somevalue}; 24679 *src; 24680 @end smallexample 24681 24682 The C++ standard specifies that such expressions do not undergo lvalue 24683 to rvalue conversion, and that the type of the dereferenced object may 24684 be incomplete. The C++ standard does not specify explicitly that it 24685 is lvalue to rvalue conversion that is responsible for causing an 24686 access. There is reason to believe that it is, because otherwise 24687 certain simple expressions become undefined. However, because it 24688 would surprise most programmers, G++ treats dereferencing a pointer to 24689 volatile object of complete type as GCC would do for an equivalent 24690 type in C@. When the object has incomplete type, G++ issues a 24691 warning; if you wish to force an error, you must force a conversion to 24692 rvalue with, for instance, a static cast. 24693 24694 When using a reference to volatile, G++ does not treat equivalent 24695 expressions as accesses to volatiles, but instead issues a warning that 24696 no volatile is accessed. The rationale for this is that otherwise it 24697 becomes difficult to determine where volatile access occur, and not 24698 possible to ignore the return value from functions returning volatile 24699 references. Again, if you wish to force a read, cast the reference to 24700 an rvalue. 24701 24702 G++ implements the same behavior as GCC does when assigning to a 24703 volatile object---there is no reread of the assigned-to object, the 24704 assigned rvalue is reused. Note that in C++ assignment expressions 24705 are lvalues, and if used as an lvalue, the volatile object is 24706 referred to. For instance, @var{vref} refers to @var{vobj}, as 24707 expected, in the following example: 24708 24709 @smallexample 24710 volatile int vobj; 24711 volatile int &vref = vobj = @var{something}; 24712 @end smallexample 24713 24714 @node Restricted Pointers 24715 @section Restricting Pointer Aliasing 24716 @cindex restricted pointers 24717 @cindex restricted references 24718 @cindex restricted this pointer 24719 24720 As with the C front end, G++ understands the C99 feature of restricted pointers, 24721 specified with the @code{__restrict__}, or @code{__restrict} type 24722 qualifier. Because you cannot compile C++ by specifying the @option{-std=c99} 24723 language flag, @code{restrict} is not a keyword in C++. 24724 24725 In addition to allowing restricted pointers, you can specify restricted 24726 references, which indicate that the reference is not aliased in the local 24727 context. 24728 24729 @smallexample 24730 void fn (int *__restrict__ rptr, int &__restrict__ rref) 24731 @{ 24732 /* @r{@dots{}} */ 24733 @} 24734 @end smallexample 24735 24736 @noindent 24737 In the body of @code{fn}, @var{rptr} points to an unaliased integer and 24738 @var{rref} refers to a (different) unaliased integer. 24739 24740 You may also specify whether a member function's @var{this} pointer is 24741 unaliased by using @code{__restrict__} as a member function qualifier. 24742 24743 @smallexample 24744 void T::fn () __restrict__ 24745 @{ 24746 /* @r{@dots{}} */ 24747 @} 24748 @end smallexample 24749 24750 @noindent 24751 Within the body of @code{T::fn}, @var{this} has the effective 24752 definition @code{T *__restrict__ const this}. Notice that the 24753 interpretation of a @code{__restrict__} member function qualifier is 24754 different to that of @code{const} or @code{volatile} qualifier, in that it 24755 is applied to the pointer rather than the object. This is consistent with 24756 other compilers that implement restricted pointers. 24757 24758 As with all outermost parameter qualifiers, @code{__restrict__} is 24759 ignored in function definition matching. This means you only need to 24760 specify @code{__restrict__} in a function definition, rather than 24761 in a function prototype as well. 24762 24763 @node Vague Linkage 24764 @section Vague Linkage 24765 @cindex vague linkage 24766 24767 There are several constructs in C++ that require space in the object 24768 file but are not clearly tied to a single translation unit. We say that 24769 these constructs have ``vague linkage''. Typically such constructs are 24770 emitted wherever they are needed, though sometimes we can be more 24771 clever. 24772 24773 @table @asis 24774 @item Inline Functions 24775 Inline functions are typically defined in a header file which can be 24776 included in many different compilations. Hopefully they can usually be 24777 inlined, but sometimes an out-of-line copy is necessary, if the address 24778 of the function is taken or if inlining fails. In general, we emit an 24779 out-of-line copy in all translation units where one is needed. As an 24780 exception, we only emit inline virtual functions with the vtable, since 24781 it always requires a copy. 24782 24783 Local static variables and string constants used in an inline function 24784 are also considered to have vague linkage, since they must be shared 24785 between all inlined and out-of-line instances of the function. 24786 24787 @item VTables 24788 @cindex vtable 24789 C++ virtual functions are implemented in most compilers using a lookup 24790 table, known as a vtable. The vtable contains pointers to the virtual 24791 functions provided by a class, and each object of the class contains a 24792 pointer to its vtable (or vtables, in some multiple-inheritance 24793 situations). If the class declares any non-inline, non-pure virtual 24794 functions, the first one is chosen as the ``key method'' for the class, 24795 and the vtable is only emitted in the translation unit where the key 24796 method is defined. 24797 24798 @emph{Note:} If the chosen key method is later defined as inline, the 24799 vtable is still emitted in every translation unit that defines it. 24800 Make sure that any inline virtuals are declared inline in the class 24801 body, even if they are not defined there. 24802 24803 @item @code{type_info} objects 24804 @cindex @code{type_info} 24805 @cindex RTTI 24806 C++ requires information about types to be written out in order to 24807 implement @samp{dynamic_cast}, @samp{typeid} and exception handling. 24808 For polymorphic classes (classes with virtual functions), the @samp{type_info} 24809 object is written out along with the vtable so that @samp{dynamic_cast} 24810 can determine the dynamic type of a class object at run time. For all 24811 other types, we write out the @samp{type_info} object when it is used: when 24812 applying @samp{typeid} to an expression, throwing an object, or 24813 referring to a type in a catch clause or exception specification. 24814 24815 @item Template Instantiations 24816 Most everything in this section also applies to template instantiations, 24817 but there are other options as well. 24818 @xref{Template Instantiation,,Where's the Template?}. 24819 24820 @end table 24821 24822 When used with GNU ld version 2.8 or later on an ELF system such as 24823 GNU/Linux or Solaris 2, or on Microsoft Windows, duplicate copies of 24824 these constructs will be discarded at link time. This is known as 24825 COMDAT support. 24826 24827 On targets that don't support COMDAT, but do support weak symbols, GCC 24828 uses them. This way one copy overrides all the others, but 24829 the unused copies still take up space in the executable. 24830 24831 For targets that do not support either COMDAT or weak symbols, 24832 most entities with vague linkage are emitted as local symbols to 24833 avoid duplicate definition errors from the linker. This does not happen 24834 for local statics in inlines, however, as having multiple copies 24835 almost certainly breaks things. 24836 24837 @xref{C++ Interface,,Declarations and Definitions in One Header}, for 24838 another way to control placement of these constructs. 24839 24840 @node C++ Interface 24841 @section C++ Interface and Implementation Pragmas 24842 24843 @cindex interface and implementation headers, C++ 24844 @cindex C++ interface and implementation headers 24845 @cindex pragmas, interface and implementation 24846 24847 @code{#pragma interface} and @code{#pragma implementation} provide the 24848 user with a way of explicitly directing the compiler to emit entities 24849 with vague linkage (and debugging information) in a particular 24850 translation unit. 24851 24852 @emph{Note:} These @code{#pragma}s have been superceded as of GCC 2.7.2 24853 by COMDAT support and the ``key method'' heuristic 24854 mentioned in @ref{Vague Linkage}. Using them can actually cause your 24855 program to grow due to unnecessary out-of-line copies of inline 24856 functions. 24857 24858 @table @code 24859 @item #pragma interface 24860 @itemx #pragma interface "@var{subdir}/@var{objects}.h" 24861 @kindex #pragma interface 24862 Use this directive in @emph{header files} that define object classes, to save 24863 space in most of the object files that use those classes. Normally, 24864 local copies of certain information (backup copies of inline member 24865 functions, debugging information, and the internal tables that implement 24866 virtual functions) must be kept in each object file that includes class 24867 definitions. You can use this pragma to avoid such duplication. When a 24868 header file containing @samp{#pragma interface} is included in a 24869 compilation, this auxiliary information is not generated (unless 24870 the main input source file itself uses @samp{#pragma implementation}). 24871 Instead, the object files contain references to be resolved at link 24872 time. 24873 24874 The second form of this directive is useful for the case where you have 24875 multiple headers with the same name in different directories. If you 24876 use this form, you must specify the same string to @samp{#pragma 24877 implementation}. 24878 24879 @item #pragma implementation 24880 @itemx #pragma implementation "@var{objects}.h" 24881 @kindex #pragma implementation 24882 Use this pragma in a @emph{main input file}, when you want full output from 24883 included header files to be generated (and made globally visible). The 24884 included header file, in turn, should use @samp{#pragma interface}. 24885 Backup copies of inline member functions, debugging information, and the 24886 internal tables used to implement virtual functions are all generated in 24887 implementation files. 24888 24889 @cindex implied @code{#pragma implementation} 24890 @cindex @code{#pragma implementation}, implied 24891 @cindex naming convention, implementation headers 24892 If you use @samp{#pragma implementation} with no argument, it applies to 24893 an include file with the same basename@footnote{A file's @dfn{basename} 24894 is the name stripped of all leading path information and of trailing 24895 suffixes, such as @samp{.h} or @samp{.C} or @samp{.cc}.} as your source 24896 file. For example, in @file{allclass.cc}, giving just 24897 @samp{#pragma implementation} 24898 by itself is equivalent to @samp{#pragma implementation "allclass.h"}. 24899 24900 Use the string argument if you want a single implementation file to 24901 include code from multiple header files. (You must also use 24902 @samp{#include} to include the header file; @samp{#pragma 24903 implementation} only specifies how to use the file---it doesn't actually 24904 include it.) 24905 24906 There is no way to split up the contents of a single header file into 24907 multiple implementation files. 24908 @end table 24909 24910 @cindex inlining and C++ pragmas 24911 @cindex C++ pragmas, effect on inlining 24912 @cindex pragmas in C++, effect on inlining 24913 @samp{#pragma implementation} and @samp{#pragma interface} also have an 24914 effect on function inlining. 24915 24916 If you define a class in a header file marked with @samp{#pragma 24917 interface}, the effect on an inline function defined in that class is 24918 similar to an explicit @code{extern} declaration---the compiler emits 24919 no code at all to define an independent version of the function. Its 24920 definition is used only for inlining with its callers. 24921 24922 @opindex fno-implement-inlines 24923 Conversely, when you include the same header file in a main source file 24924 that declares it as @samp{#pragma implementation}, the compiler emits 24925 code for the function itself; this defines a version of the function 24926 that can be found via pointers (or by callers compiled without 24927 inlining). If all calls to the function can be inlined, you can avoid 24928 emitting the function by compiling with @option{-fno-implement-inlines}. 24929 If any calls are not inlined, you will get linker errors. 24930 24931 @node Template Instantiation 24932 @section Where's the Template? 24933 @cindex template instantiation 24934 24935 C++ templates were the first language feature to require more 24936 intelligence from the environment than was traditionally found on a UNIX 24937 system. Somehow the compiler and linker have to make sure that each 24938 template instance occurs exactly once in the executable if it is needed, 24939 and not at all otherwise. There are two basic approaches to this 24940 problem, which are referred to as the Borland model and the Cfront model. 24941 24942 @table @asis 24943 @item Borland model 24944 Borland C++ solved the template instantiation problem by adding the code 24945 equivalent of common blocks to their linker; the compiler emits template 24946 instances in each translation unit that uses them, and the linker 24947 collapses them together. The advantage of this model is that the linker 24948 only has to consider the object files themselves; there is no external 24949 complexity to worry about. The disadvantage is that compilation time 24950 is increased because the template code is being compiled repeatedly. 24951 Code written for this model tends to include definitions of all 24952 templates in the header file, since they must be seen to be 24953 instantiated. 24954 24955 @item Cfront model 24956 The AT&T C++ translator, Cfront, solved the template instantiation 24957 problem by creating the notion of a template repository, an 24958 automatically maintained place where template instances are stored. A 24959 more modern version of the repository works as follows: As individual 24960 object files are built, the compiler places any template definitions and 24961 instantiations encountered in the repository. At link time, the link 24962 wrapper adds in the objects in the repository and compiles any needed 24963 instances that were not previously emitted. The advantages of this 24964 model are more optimal compilation speed and the ability to use the 24965 system linker; to implement the Borland model a compiler vendor also 24966 needs to replace the linker. The disadvantages are vastly increased 24967 complexity, and thus potential for error; for some code this can be 24968 just as transparent, but in practice it can been very difficult to build 24969 multiple programs in one directory and one program in multiple 24970 directories. Code written for this model tends to separate definitions 24971 of non-inline member templates into a separate file, which should be 24972 compiled separately. 24973 @end table 24974 24975 G++ implements the Borland model on targets where the linker supports it, 24976 including ELF targets (such as GNU/Linux), Mac OS X and Microsoft Windows. 24977 Otherwise G++ implements neither automatic model. 24978 24979 You have the following options for dealing with template instantiations: 24980 24981 @enumerate 24982 @item 24983 Do nothing. Code written for the Borland model works fine, but 24984 each translation unit contains instances of each of the templates it 24985 uses. The duplicate instances will be discarded by the linker, but in 24986 a large program, this can lead to an unacceptable amount of code 24987 duplication in object files or shared libraries. 24988 24989 Duplicate instances of a template can be avoided by defining an explicit 24990 instantiation in one object file, and preventing the compiler from doing 24991 implicit instantiations in any other object files by using an explicit 24992 instantiation declaration, using the @code{extern template} syntax: 24993 24994 @smallexample 24995 extern template int max (int, int); 24996 @end smallexample 24997 24998 This syntax is defined in the C++ 2011 standard, but has been supported by 24999 G++ and other compilers since well before 2011. 25000 25001 Explicit instantiations can be used for the largest or most frequently 25002 duplicated instances, without having to know exactly which other instances 25003 are used in the rest of the program. You can scatter the explicit 25004 instantiations throughout your program, perhaps putting them in the 25005 translation units where the instances are used or the translation units 25006 that define the templates themselves; you can put all of the explicit 25007 instantiations you need into one big file; or you can create small files 25008 like 25009 25010 @smallexample 25011 #include "Foo.h" 25012 #include "Foo.cc" 25013 25014 template class Foo<int>; 25015 template ostream& operator << 25016 (ostream&, const Foo<int>&); 25017 @end smallexample 25018 25019 @noindent 25020 for each of the instances you need, and create a template instantiation 25021 library from those. 25022 25023 This is the simplest option, but also offers flexibility and 25024 fine-grained control when necessary. It is also the most portable 25025 alternative and programs using this approach will work with most modern 25026 compilers. 25027 25028 @item 25029 @opindex fno-implicit-templates 25030 Compile your code with @option{-fno-implicit-templates} to disable the 25031 implicit generation of template instances, and explicitly instantiate 25032 all the ones you use. This approach requires more knowledge of exactly 25033 which instances you need than do the others, but it's less 25034 mysterious and allows greater control if you want to ensure that only 25035 the intended instances are used. 25036 25037 If you are using Cfront-model code, you can probably get away with not 25038 using @option{-fno-implicit-templates} when compiling files that don't 25039 @samp{#include} the member template definitions. 25040 25041 If you use one big file to do the instantiations, you may want to 25042 compile it without @option{-fno-implicit-templates} so you get all of the 25043 instances required by your explicit instantiations (but not by any 25044 other files) without having to specify them as well. 25045 25046 In addition to forward declaration of explicit instantiations 25047 (with @code{extern}), G++ has extended the template instantiation 25048 syntax to support instantiation of the compiler support data for a 25049 template class (i.e.@: the vtable) without instantiating any of its 25050 members (with @code{inline}), and instantiation of only the static data 25051 members of a template class, without the support data or member 25052 functions (with @code{static}): 25053 25054 @smallexample 25055 inline template class Foo<int>; 25056 static template class Foo<int>; 25057 @end smallexample 25058 @end enumerate 25059 25060 @node Bound member functions 25061 @section Extracting the Function Pointer from a Bound Pointer to Member Function 25062 @cindex pmf 25063 @cindex pointer to member function 25064 @cindex bound pointer to member function 25065 25066 In C++, pointer to member functions (PMFs) are implemented using a wide 25067 pointer of sorts to handle all the possible call mechanisms; the PMF 25068 needs to store information about how to adjust the @samp{this} pointer, 25069 and if the function pointed to is virtual, where to find the vtable, and 25070 where in the vtable to look for the member function. If you are using 25071 PMFs in an inner loop, you should really reconsider that decision. If 25072 that is not an option, you can extract the pointer to the function that 25073 would be called for a given object/PMF pair and call it directly inside 25074 the inner loop, to save a bit of time. 25075 25076 Note that you still pay the penalty for the call through a 25077 function pointer; on most modern architectures, such a call defeats the 25078 branch prediction features of the CPU@. This is also true of normal 25079 virtual function calls. 25080 25081 The syntax for this extension is 25082 25083 @smallexample 25084 extern A a; 25085 extern int (A::*fp)(); 25086 typedef int (*fptr)(A *); 25087 25088 fptr p = (fptr)(a.*fp); 25089 @end smallexample 25090 25091 For PMF constants (i.e.@: expressions of the form @samp{&Klasse::Member}), 25092 no object is needed to obtain the address of the function. They can be 25093 converted to function pointers directly: 25094 25095 @smallexample 25096 fptr p1 = (fptr)(&A::foo); 25097 @end smallexample 25098 25099 @opindex Wno-pmf-conversions 25100 You must specify @option{-Wno-pmf-conversions} to use this extension. 25101 25102 @node C++ Attributes 25103 @section C++-Specific Variable, Function, and Type Attributes 25104 25105 Some attributes only make sense for C++ programs. 25106 25107 @table @code 25108 @item abi_tag ("@var{tag}", ...) 25109 @cindex @code{abi_tag} function attribute 25110 @cindex @code{abi_tag} variable attribute 25111 @cindex @code{abi_tag} type attribute 25112 The @code{abi_tag} attribute can be applied to a function, variable, or class 25113 declaration. It modifies the mangled name of the entity to 25114 incorporate the tag name, in order to distinguish the function or 25115 class from an earlier version with a different ABI; perhaps the class 25116 has changed size, or the function has a different return type that is 25117 not encoded in the mangled name. 25118 25119 The attribute can also be applied to an inline namespace, but does not 25120 affect the mangled name of the namespace; in this case it is only used 25121 for @option{-Wabi-tag} warnings and automatic tagging of functions and 25122 variables. Tagging inline namespaces is generally preferable to 25123 tagging individual declarations, but the latter is sometimes 25124 necessary, such as when only certain members of a class need to be 25125 tagged. 25126 25127 The argument can be a list of strings of arbitrary length. The 25128 strings are sorted on output, so the order of the list is 25129 unimportant. 25130 25131 A redeclaration of an entity must not add new ABI tags, 25132 since doing so would change the mangled name. 25133 25134 The ABI tags apply to a name, so all instantiations and 25135 specializations of a template have the same tags. The attribute will 25136 be ignored if applied to an explicit specialization or instantiation. 25137 25138 The @option{-Wabi-tag} flag enables a warning about a class which does 25139 not have all the ABI tags used by its subobjects and virtual functions; for users with code 25140 that needs to coexist with an earlier ABI, using this option can help 25141 to find all affected types that need to be tagged. 25142 25143 When a type involving an ABI tag is used as the type of a variable or 25144 return type of a function where that tag is not already present in the 25145 signature of the function, the tag is automatically applied to the 25146 variable or function. @option{-Wabi-tag} also warns about this 25147 situation; this warning can be avoided by explicitly tagging the 25148 variable or function or moving it into a tagged inline namespace. 25149 25150 @item init_priority (@var{priority}) 25151 @cindex @code{init_priority} variable attribute 25152 25153 In Standard C++, objects defined at namespace scope are guaranteed to be 25154 initialized in an order in strict accordance with that of their definitions 25155 @emph{in a given translation unit}. No guarantee is made for initializations 25156 across translation units. However, GNU C++ allows users to control the 25157 order of initialization of objects defined at namespace scope with the 25158 @code{init_priority} attribute by specifying a relative @var{priority}, 25159 a constant integral expression currently bounded between 101 and 65535 25160 inclusive. Lower numbers indicate a higher priority. 25161 25162 In the following example, @code{A} would normally be created before 25163 @code{B}, but the @code{init_priority} attribute reverses that order: 25164 25165 @smallexample 25166 Some_Class A __attribute__ ((init_priority (2000))); 25167 Some_Class B __attribute__ ((init_priority (543))); 25168 @end smallexample 25169 25170 @noindent 25171 Note that the particular values of @var{priority} do not matter; only their 25172 relative ordering. 25173 25174 @item warn_unused 25175 @cindex @code{warn_unused} type attribute 25176 25177 For C++ types with non-trivial constructors and/or destructors it is 25178 impossible for the compiler to determine whether a variable of this 25179 type is truly unused if it is not referenced. This type attribute 25180 informs the compiler that variables of this type should be warned 25181 about if they appear to be unused, just like variables of fundamental 25182 types. 25183 25184 This attribute is appropriate for types which just represent a value, 25185 such as @code{std::string}; it is not appropriate for types which 25186 control a resource, such as @code{std::lock_guard}. 25187 25188 This attribute is also accepted in C, but it is unnecessary because C 25189 does not have constructors or destructors. 25190 25191 @end table 25192 25193 @node Function Multiversioning 25194 @section Function Multiversioning 25195 @cindex function versions 25196 25197 With the GNU C++ front end, for x86 targets, you may specify multiple 25198 versions of a function, where each function is specialized for a 25199 specific target feature. At runtime, the appropriate version of the 25200 function is automatically executed depending on the characteristics of 25201 the execution platform. Here is an example. 25202 25203 @smallexample 25204 __attribute__ ((target ("default"))) 25205 int foo () 25206 @{ 25207 // The default version of foo. 25208 return 0; 25209 @} 25210 25211 __attribute__ ((target ("sse4.2"))) 25212 int foo () 25213 @{ 25214 // foo version for SSE4.2 25215 return 1; 25216 @} 25217 25218 __attribute__ ((target ("arch=atom"))) 25219 int foo () 25220 @{ 25221 // foo version for the Intel ATOM processor 25222 return 2; 25223 @} 25224 25225 __attribute__ ((target ("arch=amdfam10"))) 25226 int foo () 25227 @{ 25228 // foo version for the AMD Family 0x10 processors. 25229 return 3; 25230 @} 25231 25232 int main () 25233 @{ 25234 int (*p)() = &foo; 25235 assert ((*p) () == foo ()); 25236 return 0; 25237 @} 25238 @end smallexample 25239 25240 In the above example, four versions of function foo are created. The 25241 first version of foo with the target attribute "default" is the default 25242 version. This version gets executed when no other target specific 25243 version qualifies for execution on a particular platform. A new version 25244 of foo is created by using the same function signature but with a 25245 different target string. Function foo is called or a pointer to it is 25246 taken just like a regular function. GCC takes care of doing the 25247 dispatching to call the right version at runtime. Refer to the 25248 @uref{https://gcc.gnu.org/wiki/FunctionMultiVersioning, GCC wiki on 25249 Function Multiversioning} for more details. 25250 25251 @node Type Traits 25252 @section Type Traits 25253 25254 The C++ front end implements syntactic extensions that allow 25255 compile-time determination of 25256 various characteristics of a type (or of a 25257 pair of types). 25258 25259 @table @code 25260 @item __has_nothrow_assign (type) 25261 If @code{type} is @code{const}-qualified or is a reference type then 25262 the trait is @code{false}. Otherwise if @code{__has_trivial_assign (type)} 25263 is @code{true} then the trait is @code{true}, else if @code{type} is 25264 a cv-qualified class or union type with copy assignment operators that are 25265 known not to throw an exception then the trait is @code{true}, else it is 25266 @code{false}. 25267 Requires: @code{type} shall be a complete type, (possibly cv-qualified) 25268 @code{void}, or an array of unknown bound. 25269 25270 @item __has_nothrow_copy (type) 25271 If @code{__has_trivial_copy (type)} is @code{true} then the trait is 25272 @code{true}, else if @code{type} is a cv-qualified class or union type 25273 with copy constructors that are known not to throw an exception then 25274 the trait is @code{true}, else it is @code{false}. 25275 Requires: @code{type} shall be a complete type, (possibly cv-qualified) 25276 @code{void}, or an array of unknown bound. 25277 25278 @item __has_nothrow_constructor (type) 25279 If @code{__has_trivial_constructor (type)} is @code{true} then the trait 25280 is @code{true}, else if @code{type} is a cv class or union type (or array 25281 thereof) with a default constructor that is known not to throw an 25282 exception then the trait is @code{true}, else it is @code{false}. 25283 Requires: @code{type} shall be a complete type, (possibly cv-qualified) 25284 @code{void}, or an array of unknown bound. 25285 25286 @item __has_trivial_assign (type) 25287 If @code{type} is @code{const}- qualified or is a reference type then 25288 the trait is @code{false}. Otherwise if @code{__is_trivial (type)} is 25289 @code{true} then the trait is @code{true}, else if @code{type} is 25290 a cv-qualified class or union type with a trivial copy assignment 25291 ([class.copy]) then the trait is @code{true}, else it is @code{false}. 25292 Requires: @code{type} shall be a complete type, (possibly cv-qualified) 25293 @code{void}, or an array of unknown bound. 25294 25295 @item __has_trivial_copy (type) 25296 If @code{__is_trivial (type)} is @code{true} or @code{type} is a reference 25297 type then the trait is @code{true}, else if @code{type} is a cv class 25298 or union type with a trivial copy constructor ([class.copy]) then the trait 25299 is @code{true}, else it is @code{false}. Requires: @code{type} shall be 25300 a complete type, (possibly cv-qualified) @code{void}, or an array of unknown 25301 bound. 25302 25303 @item __has_trivial_constructor (type) 25304 If @code{__is_trivial (type)} is @code{true} then the trait is @code{true}, 25305 else if @code{type} is a cv-qualified class or union type (or array thereof) 25306 with a trivial default constructor ([class.ctor]) then the trait is @code{true}, 25307 else it is @code{false}. 25308 Requires: @code{type} shall be a complete type, (possibly cv-qualified) 25309 @code{void}, or an array of unknown bound. 25310 25311 @item __has_trivial_destructor (type) 25312 If @code{__is_trivial (type)} is @code{true} or @code{type} is a reference type 25313 then the trait is @code{true}, else if @code{type} is a cv class or union 25314 type (or array thereof) with a trivial destructor ([class.dtor]) then 25315 the trait is @code{true}, else it is @code{false}. 25316 Requires: @code{type} shall be a complete type, (possibly cv-qualified) 25317 @code{void}, or an array of unknown bound. 25318 25319 @item __has_virtual_destructor (type) 25320 If @code{type} is a class type with a virtual destructor 25321 ([class.dtor]) then the trait is @code{true}, else it is @code{false}. 25322 Requires: @code{type} shall be a complete type, (possibly cv-qualified) 25323 @code{void}, or an array of unknown bound. 25324 25325 @item __is_abstract (type) 25326 If @code{type} is an abstract class ([class.abstract]) then the trait 25327 is @code{true}, else it is @code{false}. 25328 Requires: @code{type} shall be a complete type, (possibly cv-qualified) 25329 @code{void}, or an array of unknown bound. 25330 25331 @item __is_base_of (base_type, derived_type) 25332 If @code{base_type} is a base class of @code{derived_type} 25333 ([class.derived]) then the trait is @code{true}, otherwise it is @code{false}. 25334 Top-level cv-qualifications of @code{base_type} and 25335 @code{derived_type} are ignored. For the purposes of this trait, a 25336 class type is considered is own base. 25337 Requires: if @code{__is_class (base_type)} and @code{__is_class (derived_type)} 25338 are @code{true} and @code{base_type} and @code{derived_type} are not the same 25339 type (disregarding cv-qualifiers), @code{derived_type} shall be a complete 25340 type. A diagnostic is produced if this requirement is not met. 25341 25342 @item __is_class (type) 25343 If @code{type} is a cv-qualified class type, and not a union type 25344 ([basic.compound]) the trait is @code{true}, else it is @code{false}. 25345 25346 @item __is_empty (type) 25347 If @code{__is_class (type)} is @code{false} then the trait is @code{false}. 25348 Otherwise @code{type} is considered empty if and only if: @code{type} 25349 has no non-static data members, or all non-static data members, if 25350 any, are bit-fields of length 0, and @code{type} has no virtual 25351 members, and @code{type} has no virtual base classes, and @code{type} 25352 has no base classes @code{base_type} for which 25353 @code{__is_empty (base_type)} is @code{false}. 25354 Requires: @code{type} shall be a complete type, (possibly cv-qualified) 25355 @code{void}, or an array of unknown bound. 25356 25357 @item __is_enum (type) 25358 If @code{type} is a cv enumeration type ([basic.compound]) the trait is 25359 @code{true}, else it is @code{false}. 25360 25361 @item __is_literal_type (type) 25362 If @code{type} is a literal type ([basic.types]) the trait is 25363 @code{true}, else it is @code{false}. 25364 Requires: @code{type} shall be a complete type, (possibly cv-qualified) 25365 @code{void}, or an array of unknown bound. 25366 25367 @item __is_pod (type) 25368 If @code{type} is a cv POD type ([basic.types]) then the trait is @code{true}, 25369 else it is @code{false}. 25370 Requires: @code{type} shall be a complete type, (possibly cv-qualified) 25371 @code{void}, or an array of unknown bound. 25372 25373 @item __is_polymorphic (type) 25374 If @code{type} is a polymorphic class ([class.virtual]) then the trait 25375 is @code{true}, else it is @code{false}. 25376 Requires: @code{type} shall be a complete type, (possibly cv-qualified) 25377 @code{void}, or an array of unknown bound. 25378 25379 @item __is_standard_layout (type) 25380 If @code{type} is a standard-layout type ([basic.types]) the trait is 25381 @code{true}, else it is @code{false}. 25382 Requires: @code{type} shall be a complete type, (possibly cv-qualified) 25383 @code{void}, or an array of unknown bound. 25384 25385 @item __is_trivial (type) 25386 If @code{type} is a trivial type ([basic.types]) the trait is 25387 @code{true}, else it is @code{false}. 25388 Requires: @code{type} shall be a complete type, (possibly cv-qualified) 25389 @code{void}, or an array of unknown bound. 25390 25391 @item __is_union (type) 25392 If @code{type} is a cv union type ([basic.compound]) the trait is 25393 @code{true}, else it is @code{false}. 25394 25395 @item __underlying_type (type) 25396 The underlying type of @code{type}. 25397 Requires: @code{type} shall be an enumeration type ([dcl.enum]). 25398 25399 @item __integer_pack (length) 25400 When used as the pattern of a pack expansion within a template 25401 definition, expands to a template argument pack containing integers 25402 from @code{0} to @code{length-1}. This is provided for efficient 25403 implementation of @code{std::make_integer_sequence}. 25404 25405 @end table 25406 25407 25408 @node C++ Concepts 25409 @section C++ Concepts 25410 25411 C++ concepts provide much-improved support for generic programming. In 25412 particular, they allow the specification of constraints on template arguments. 25413 The constraints are used to extend the usual overloading and partial 25414 specialization capabilities of the language, allowing generic data structures 25415 and algorithms to be ``refined'' based on their properties rather than their 25416 type names. 25417 25418 The following keywords are reserved for concepts. 25419 25420 @table @code 25421 @item assumes 25422 States an expression as an assumption, and if possible, verifies that the 25423 assumption is valid. For example, @code{assume(n > 0)}. 25424 25425 @item axiom 25426 Introduces an axiom definition. Axioms introduce requirements on values. 25427 25428 @item forall 25429 Introduces a universally quantified object in an axiom. For example, 25430 @code{forall (int n) n + 0 == n}). 25431 25432 @item concept 25433 Introduces a concept definition. Concepts are sets of syntactic and semantic 25434 requirements on types and their values. 25435 25436 @item requires 25437 Introduces constraints on template arguments or requirements for a member 25438 function of a class template. 25439 25440 @end table 25441 25442 The front end also exposes a number of internal mechanism that can be used 25443 to simplify the writing of type traits. Note that some of these traits are 25444 likely to be removed in the future. 25445 25446 @table @code 25447 @item __is_same (type1, type2) 25448 A binary type trait: @code{true} whenever the type arguments are the same. 25449 25450 @end table 25451 25452 25453 @node Deprecated Features 25454 @section Deprecated Features 25455 25456 In the past, the GNU C++ compiler was extended to experiment with new 25457 features, at a time when the C++ language was still evolving. Now that 25458 the C++ standard is complete, some of those features are superseded by 25459 superior alternatives. Using the old features might cause a warning in 25460 some cases that the feature will be dropped in the future. In other 25461 cases, the feature might be gone already. 25462 25463 G++ allows a virtual function returning @samp{void *} to be overridden 25464 by one returning a different pointer type. This extension to the 25465 covariant return type rules is now deprecated and will be removed from a 25466 future version. 25467 25468 The use of default arguments in function pointers, function typedefs 25469 and other places where they are not permitted by the standard is 25470 deprecated and will be removed from a future version of G++. 25471 25472 G++ allows floating-point literals to appear in integral constant expressions, 25473 e.g.@: @samp{ enum E @{ e = int(2.2 * 3.7) @} } 25474 This extension is deprecated and will be removed from a future version. 25475 25476 G++ allows static data members of const floating-point type to be declared 25477 with an initializer in a class definition. The standard only allows 25478 initializers for static members of const integral types and const 25479 enumeration types so this extension has been deprecated and will be removed 25480 from a future version. 25481 25482 G++ allows attributes to follow a parenthesized direct initializer, 25483 e.g.@: @samp{ int f (0) __attribute__ ((something)); } This extension 25484 has been ignored since G++ 3.3 and is deprecated. 25485 25486 G++ allows anonymous structs and unions to have members that are not 25487 public non-static data members (i.e.@: fields). These extensions are 25488 deprecated. 25489 25490 @node Backwards Compatibility 25491 @section Backwards Compatibility 25492 @cindex Backwards Compatibility 25493 @cindex ARM [Annotated C++ Reference Manual] 25494 25495 Now that there is a definitive ISO standard C++, G++ has a specification 25496 to adhere to. The C++ language evolved over time, and features that 25497 used to be acceptable in previous drafts of the standard, such as the ARM 25498 [Annotated C++ Reference Manual], are no longer accepted. In order to allow 25499 compilation of C++ written to such drafts, G++ contains some backwards 25500 compatibilities. @emph{All such backwards compatibility features are 25501 liable to disappear in future versions of G++.} They should be considered 25502 deprecated. @xref{Deprecated Features}. 25503 25504 @table @code 25505 25506 @item Implicit C language 25507 Old C system header files did not contain an @code{extern "C" @{@dots{}@}} 25508 scope to set the language. On such systems, all system header files are 25509 implicitly scoped inside a C language scope. Such headers must 25510 correctly prototype function argument types, there is no leeway for 25511 @code{()} to indicate an unspecified set of arguments. 25512 25513 @end table 25514 25515 @c LocalWords: emph deftypefn builtin ARCv2EM SIMD builtins msimd 25516 @c LocalWords: typedef v4si v8hi DMA dma vdiwr vdowr 25517
Indexes created Wed Mar 04 15:26:31 UTC 2026