1 //==--- AttrDocs.td - Attribute documentation ----------------------------===// 2 // 3 // The LLVM Compiler Infrastructure 4 // 5 // This file is distributed under the University of Illinois Open Source 6 // License. See LICENSE.TXT for details. 7 // 8 //===---------------------------------------------------------------------===// 9 10 def GlobalDocumentation { 11 code Intro =[{.. 12 ------------------------------------------------------------------- 13 NOTE: This file is automatically generated by running clang-tblgen 14 -gen-attr-docs. Do not edit this file by hand!! 15 ------------------------------------------------------------------- 16 17 =================== 18 Attributes in Clang 19 =================== 20 .. contents:: 21 :local: 22 23 Introduction 24 ============ 25 26 This page lists the attributes currently supported by Clang. 27 }]; 28 } 29 30 def SectionDocs : Documentation { 31 let Category = DocCatVariable; 32 let Content = [{ 33 The ``section`` attribute allows you to specify a specific section a 34 global variable or function should be in after translation. 35 }]; 36 let Heading = "section (gnu::section, __declspec(allocate))"; 37 } 38 39 def InitSegDocs : Documentation { 40 let Category = DocCatVariable; 41 let Content = [{ 42 The attribute applied by ``pragma init_seg()`` controls the section into 43 which global initialization function pointers are emitted. It is only 44 available with ``-fms-extensions``. Typically, this function pointer is 45 emitted into ``.CRT$XCU`` on Windows. The user can change the order of 46 initialization by using a different section name with the same 47 ``.CRT$XC`` prefix and a suffix that sorts lexicographically before or 48 after the standard ``.CRT$XCU`` sections. See the init_seg_ 49 documentation on MSDN for more information. 50 51 .. _init_seg: http://msdn.microsoft.com/en-us/library/7977wcck(v=vs.110).aspx 52 }]; 53 } 54 55 def TLSModelDocs : Documentation { 56 let Category = DocCatVariable; 57 let Content = [{ 58 The ``tls_model`` attribute allows you to specify which thread-local storage 59 model to use. It accepts the following strings: 60 61 * global-dynamic 62 * local-dynamic 63 * initial-exec 64 * local-exec 65 66 TLS models are mutually exclusive. 67 }]; 68 } 69 70 def ThreadDocs : Documentation { 71 let Category = DocCatVariable; 72 let Content = [{ 73 The ``__declspec(thread)`` attribute declares a variable with thread local 74 storage. It is available under the ``-fms-extensions`` flag for MSVC 75 compatibility. See the documentation for `__declspec(thread)`_ on MSDN. 76 77 .. _`__declspec(thread)`: http://msdn.microsoft.com/en-us/library/9w1sdazb.aspx 78 79 In Clang, ``__declspec(thread)`` is generally equivalent in functionality to the 80 GNU ``__thread`` keyword. The variable must not have a destructor and must have 81 a constant initializer, if any. The attribute only applies to variables 82 declared with static storage duration, such as globals, class static data 83 members, and static locals. 84 }]; 85 } 86 87 def CarriesDependencyDocs : Documentation { 88 let Category = DocCatFunction; 89 let Content = [{ 90 The ``carries_dependency`` attribute specifies dependency propagation into and 91 out of functions. 92 93 When specified on a function or Objective-C method, the ``carries_dependency`` 94 attribute means that the return value carries a dependency out of the function, 95 so that the implementation need not constrain ordering upon return from that 96 function. Implementations of the function and its caller may choose to preserve 97 dependencies instead of emitting memory ordering instructions such as fences. 98 99 Note, this attribute does not change the meaning of the program, but may result 100 in generation of more efficient code. 101 }]; 102 } 103 104 def C11NoReturnDocs : Documentation { 105 let Category = DocCatFunction; 106 let Content = [{ 107 A function declared as ``_Noreturn`` shall not return to its caller. The 108 compiler will generate a diagnostic for a function declared as ``_Noreturn`` 109 that appears to be capable of returning to its caller. 110 }]; 111 } 112 113 def CXX11NoReturnDocs : Documentation { 114 let Category = DocCatFunction; 115 let Content = [{ 116 A function declared as ``[[noreturn]]`` shall not return to its caller. The 117 compiler will generate a diagnostic for a function declared as ``[[noreturn]]`` 118 that appears to be capable of returning to its caller. 119 }]; 120 } 121 122 def AssertCapabilityDocs : Documentation { 123 let Category = DocCatFunction; 124 let Heading = "assert_capability (assert_shared_capability, clang::assert_capability, clang::assert_shared_capability)"; 125 let Content = [{ 126 Marks a function that dynamically tests whether a capability is held, and halts 127 the program if it is not held. 128 }]; 129 } 130 131 def AcquireCapabilityDocs : Documentation { 132 let Category = DocCatFunction; 133 let Heading = "acquire_capability (acquire_shared_capability, clang::acquire_capability, clang::acquire_shared_capability)"; 134 let Content = [{ 135 Marks a function as acquiring a capability. 136 }]; 137 } 138 139 def TryAcquireCapabilityDocs : Documentation { 140 let Category = DocCatFunction; 141 let Heading = "try_acquire_capability (try_acquire_shared_capability, clang::try_acquire_capability, clang::try_acquire_shared_capability)"; 142 let Content = [{ 143 Marks a function that attempts to acquire a capability. This function may fail to 144 actually acquire the capability; they accept a Boolean value determining 145 whether acquiring the capability means success (true), or failing to acquire 146 the capability means success (false). 147 }]; 148 } 149 150 def ReleaseCapabilityDocs : Documentation { 151 let Category = DocCatFunction; 152 let Heading = "release_capability (release_shared_capability, clang::release_capability, clang::release_shared_capability)"; 153 let Content = [{ 154 Marks a function as releasing a capability. 155 }]; 156 } 157 158 def AssumeAlignedDocs : Documentation { 159 let Category = DocCatFunction; 160 let Content = [{ 161 Use ``__attribute__((assume_aligned(<alignment>[,<offset>]))`` on a function 162 declaration to specify that the return value of the function (which must be a 163 pointer type) has the specified offset, in bytes, from an address with the 164 specified alignment. The offset is taken to be zero if omitted. 165 166 .. code-block:: c++ 167 168 // The returned pointer value has 32-byte alignment. 169 void *a() __attribute__((assume_aligned (32))); 170 171 // The returned pointer value is 4 bytes greater than an address having 172 // 32-byte alignment. 173 void *b() __attribute__((assume_aligned (32, 4))); 174 175 Note that this attribute provides information to the compiler regarding a 176 condition that the code already ensures is true. It does not cause the compiler 177 to enforce the provided alignment assumption. 178 }]; 179 } 180 181 def EnableIfDocs : Documentation { 182 let Category = DocCatFunction; 183 let Content = [{ 184 The ``enable_if`` attribute can be placed on function declarations to control 185 which overload is selected based on the values of the function's arguments. 186 When combined with the ``overloadable`` attribute, this feature is also 187 available in C. 188 189 .. code-block:: c++ 190 191 int isdigit(int c); 192 int isdigit(int c) __attribute__((enable_if(c <= -1 || c > 255, "chosen when 'c' is out of range"))) __attribute__((unavailable("'c' must have the value of an unsigned char or EOF"))); 193 194 void foo(char c) { 195 isdigit(c); 196 isdigit(10); 197 isdigit(-10); // results in a compile-time error. 198 } 199 200 The enable_if attribute takes two arguments, the first is an expression written 201 in terms of the function parameters, the second is a string explaining why this 202 overload candidate could not be selected to be displayed in diagnostics. The 203 expression is part of the function signature for the purposes of determining 204 whether it is a redeclaration (following the rules used when determining 205 whether a C++ template specialization is ODR-equivalent), but is not part of 206 the type. 207 208 The enable_if expression is evaluated as if it were the body of a 209 bool-returning constexpr function declared with the arguments of the function 210 it is being applied to, then called with the parameters at the call site. If the 211 result is false or could not be determined through constant expression 212 evaluation, then this overload will not be chosen and the provided string may 213 be used in a diagnostic if the compile fails as a result. 214 215 Because the enable_if expression is an unevaluated context, there are no global 216 state changes, nor the ability to pass information from the enable_if 217 expression to the function body. For example, suppose we want calls to 218 strnlen(strbuf, maxlen) to resolve to strnlen_chk(strbuf, maxlen, size of 219 strbuf) only if the size of strbuf can be determined: 220 221 .. code-block:: c++ 222 223 __attribute__((always_inline)) 224 static inline size_t strnlen(const char *s, size_t maxlen) 225 __attribute__((overloadable)) 226 __attribute__((enable_if(__builtin_object_size(s, 0) != -1))), 227 "chosen when the buffer size is known but 'maxlen' is not"))) 228 { 229 return strnlen_chk(s, maxlen, __builtin_object_size(s, 0)); 230 } 231 232 Multiple enable_if attributes may be applied to a single declaration. In this 233 case, the enable_if expressions are evaluated from left to right in the 234 following manner. First, the candidates whose enable_if expressions evaluate to 235 false or cannot be evaluated are discarded. If the remaining candidates do not 236 share ODR-equivalent enable_if expressions, the overload resolution is 237 ambiguous. Otherwise, enable_if overload resolution continues with the next 238 enable_if attribute on the candidates that have not been discarded and have 239 remaining enable_if attributes. In this way, we pick the most specific 240 overload out of a number of viable overloads using enable_if. 241 242 .. code-block:: c++ 243 244 void f() __attribute__((enable_if(true, ""))); // #1 245 void f() __attribute__((enable_if(true, ""))) __attribute__((enable_if(true, ""))); // #2 246 247 void g(int i, int j) __attribute__((enable_if(i, ""))); // #1 248 void g(int i, int j) __attribute__((enable_if(j, ""))) __attribute__((enable_if(true))); // #2 249 250 In this example, a call to f() is always resolved to #2, as the first enable_if 251 expression is ODR-equivalent for both declarations, but #1 does not have another 252 enable_if expression to continue evaluating, so the next round of evaluation has 253 only a single candidate. In a call to g(1, 1), the call is ambiguous even though 254 #2 has more enable_if attributes, because the first enable_if expressions are 255 not ODR-equivalent. 256 257 Query for this feature with ``__has_attribute(enable_if)``. 258 }]; 259 } 260 261 def OverloadableDocs : Documentation { 262 let Category = DocCatFunction; 263 let Content = [{ 264 Clang provides support for C++ function overloading in C. Function overloading 265 in C is introduced using the ``overloadable`` attribute. For example, one 266 might provide several overloaded versions of a ``tgsin`` function that invokes 267 the appropriate standard function computing the sine of a value with ``float``, 268 ``double``, or ``long double`` precision: 269 270 .. code-block:: c 271 272 #include <math.h> 273 float __attribute__((overloadable)) tgsin(float x) { return sinf(x); } 274 double __attribute__((overloadable)) tgsin(double x) { return sin(x); } 275 long double __attribute__((overloadable)) tgsin(long double x) { return sinl(x); } 276 277 Given these declarations, one can call ``tgsin`` with a ``float`` value to 278 receive a ``float`` result, with a ``double`` to receive a ``double`` result, 279 etc. Function overloading in C follows the rules of C++ function overloading 280 to pick the best overload given the call arguments, with a few C-specific 281 semantics: 282 283 * Conversion from ``float`` or ``double`` to ``long double`` is ranked as a 284 floating-point promotion (per C99) rather than as a floating-point conversion 285 (as in C++). 286 287 * A conversion from a pointer of type ``T*`` to a pointer of type ``U*`` is 288 considered a pointer conversion (with conversion rank) if ``T`` and ``U`` are 289 compatible types. 290 291 * A conversion from type ``T`` to a value of type ``U`` is permitted if ``T`` 292 and ``U`` are compatible types. This conversion is given "conversion" rank. 293 294 The declaration of ``overloadable`` functions is restricted to function 295 declarations and definitions. Most importantly, if any function with a given 296 name is given the ``overloadable`` attribute, then all function declarations 297 and definitions with that name (and in that scope) must have the 298 ``overloadable`` attribute. This rule even applies to redeclarations of 299 functions whose original declaration had the ``overloadable`` attribute, e.g., 300 301 .. code-block:: c 302 303 int f(int) __attribute__((overloadable)); 304 float f(float); // error: declaration of "f" must have the "overloadable" attribute 305 306 int g(int) __attribute__((overloadable)); 307 int g(int) { } // error: redeclaration of "g" must also have the "overloadable" attribute 308 309 Functions marked ``overloadable`` must have prototypes. Therefore, the 310 following code is ill-formed: 311 312 .. code-block:: c 313 314 int h() __attribute__((overloadable)); // error: h does not have a prototype 315 316 However, ``overloadable`` functions are allowed to use a ellipsis even if there 317 are no named parameters (as is permitted in C++). This feature is particularly 318 useful when combined with the ``unavailable`` attribute: 319 320 .. code-block:: c++ 321 322 void honeypot(...) __attribute__((overloadable, unavailable)); // calling me is an error 323 324 Functions declared with the ``overloadable`` attribute have their names mangled 325 according to the same rules as C++ function names. For example, the three 326 ``tgsin`` functions in our motivating example get the mangled names 327 ``_Z5tgsinf``, ``_Z5tgsind``, and ``_Z5tgsine``, respectively. There are two 328 caveats to this use of name mangling: 329 330 * Future versions of Clang may change the name mangling of functions overloaded 331 in C, so you should not depend on an specific mangling. To be completely 332 safe, we strongly urge the use of ``static inline`` with ``overloadable`` 333 functions. 334 335 * The ``overloadable`` attribute has almost no meaning when used in C++, 336 because names will already be mangled and functions are already overloadable. 337 However, when an ``overloadable`` function occurs within an ``extern "C"`` 338 linkage specification, it's name *will* be mangled in the same way as it 339 would in C. 340 341 Query for this feature with ``__has_extension(attribute_overloadable)``. 342 }]; 343 } 344 345 def ObjCMethodFamilyDocs : Documentation { 346 let Category = DocCatFunction; 347 let Content = [{ 348 Many methods in Objective-C have conventional meanings determined by their 349 selectors. It is sometimes useful to be able to mark a method as having a 350 particular conventional meaning despite not having the right selector, or as 351 not having the conventional meaning that its selector would suggest. For these 352 use cases, we provide an attribute to specifically describe the "method family" 353 that a method belongs to. 354 355 **Usage**: ``__attribute__((objc_method_family(X)))``, where ``X`` is one of 356 ``none``, ``alloc``, ``copy``, ``init``, ``mutableCopy``, or ``new``. This 357 attribute can only be placed at the end of a method declaration: 358 359 .. code-block:: objc 360 361 - (NSString *)initMyStringValue __attribute__((objc_method_family(none))); 362 363 Users who do not wish to change the conventional meaning of a method, and who 364 merely want to document its non-standard retain and release semantics, should 365 use the retaining behavior attributes (``ns_returns_retained``, 366 ``ns_returns_not_retained``, etc). 367 368 Query for this feature with ``__has_attribute(objc_method_family)``. 369 }]; 370 } 371 372 def NoDuplicateDocs : Documentation { 373 let Category = DocCatFunction; 374 let Content = [{ 375 The ``noduplicate`` attribute can be placed on function declarations to control 376 whether function calls to this function can be duplicated or not as a result of 377 optimizations. This is required for the implementation of functions with 378 certain special requirements, like the OpenCL "barrier" function, that might 379 need to be run concurrently by all the threads that are executing in lockstep 380 on the hardware. For example this attribute applied on the function 381 "nodupfunc" in the code below avoids that: 382 383 .. code-block:: c 384 385 void nodupfunc() __attribute__((noduplicate)); 386 // Setting it as a C++11 attribute is also valid 387 // void nodupfunc() [[clang::noduplicate]]; 388 void foo(); 389 void bar(); 390 391 nodupfunc(); 392 if (a > n) { 393 foo(); 394 } else { 395 bar(); 396 } 397 398 gets possibly modified by some optimizations into code similar to this: 399 400 .. code-block:: c 401 402 if (a > n) { 403 nodupfunc(); 404 foo(); 405 } else { 406 nodupfunc(); 407 bar(); 408 } 409 410 where the call to "nodupfunc" is duplicated and sunk into the two branches 411 of the condition. 412 }]; 413 } 414 415 def NoSplitStackDocs : Documentation { 416 let Category = DocCatFunction; 417 let Content = [{ 418 The ``no_split_stack`` attribute disables the emission of the split stack 419 preamble for a particular function. It has no effect if ``-fsplit-stack`` 420 is not specified. 421 }]; 422 } 423 424 def ObjCRequiresSuperDocs : Documentation { 425 let Category = DocCatFunction; 426 let Content = [{ 427 Some Objective-C classes allow a subclass to override a particular method in a 428 parent class but expect that the overriding method also calls the overridden 429 method in the parent class. For these cases, we provide an attribute to 430 designate that a method requires a "call to ``super``" in the overriding 431 method in the subclass. 432 433 **Usage**: ``__attribute__((objc_requires_super))``. This attribute can only 434 be placed at the end of a method declaration: 435 436 .. code-block:: objc 437 438 - (void)foo __attribute__((objc_requires_super)); 439 440 This attribute can only be applied the method declarations within a class, and 441 not a protocol. Currently this attribute does not enforce any placement of 442 where the call occurs in the overriding method (such as in the case of 443 ``-dealloc`` where the call must appear at the end). It checks only that it 444 exists. 445 446 Note that on both OS X and iOS that the Foundation framework provides a 447 convenience macro ``NS_REQUIRES_SUPER`` that provides syntactic sugar for this 448 attribute: 449 450 .. code-block:: objc 451 452 - (void)foo NS_REQUIRES_SUPER; 453 454 This macro is conditionally defined depending on the compiler's support for 455 this attribute. If the compiler does not support the attribute the macro 456 expands to nothing. 457 458 Operationally, when a method has this annotation the compiler will warn if the 459 implementation of an override in a subclass does not call super. For example: 460 461 .. code-block:: objc 462 463 warning: method possibly missing a [super AnnotMeth] call 464 - (void) AnnotMeth{}; 465 ^ 466 }]; 467 } 468 469 def ObjCRuntimeNameDocs : Documentation { 470 let Category = DocCatFunction; 471 let Content = [{ 472 By default, the Objective-C interface or protocol identifier is used 473 in the metadata name for that object. The `objc_runtime_name` 474 attribute allows annotated interfaces or protocols to use the 475 specified string argument in the object's metadata name instead of the 476 default name. 477 478 **Usage**: ``__attribute__((objc_runtime_name("MyLocalName")))``. This attribute 479 can only be placed before an @protocol or @interface declaration: 480 481 .. code-block:: objc 482 483 __attribute__((objc_runtime_name("MyLocalName"))) 484 @interface Message 485 @end 486 487 }]; 488 } 489 490 def AvailabilityDocs : Documentation { 491 let Category = DocCatFunction; 492 let Content = [{ 493 The ``availability`` attribute can be placed on declarations to describe the 494 lifecycle of that declaration relative to operating system versions. Consider 495 the function declaration for a hypothetical function ``f``: 496 497 .. code-block:: c++ 498 499 void f(void) __attribute__((availability(macosx,introduced=10.4,deprecated=10.6,obsoleted=10.7))); 500 501 The availability attribute states that ``f`` was introduced in Mac OS X 10.4, 502 deprecated in Mac OS X 10.6, and obsoleted in Mac OS X 10.7. This information 503 is used by Clang to determine when it is safe to use ``f``: for example, if 504 Clang is instructed to compile code for Mac OS X 10.5, a call to ``f()`` 505 succeeds. If Clang is instructed to compile code for Mac OS X 10.6, the call 506 succeeds but Clang emits a warning specifying that the function is deprecated. 507 Finally, if Clang is instructed to compile code for Mac OS X 10.7, the call 508 fails because ``f()`` is no longer available. 509 510 The availability attribute is a comma-separated list starting with the 511 platform name and then including clauses specifying important milestones in the 512 declaration's lifetime (in any order) along with additional information. Those 513 clauses can be: 514 515 introduced=\ *version* 516 The first version in which this declaration was introduced. 517 518 deprecated=\ *version* 519 The first version in which this declaration was deprecated, meaning that 520 users should migrate away from this API. 521 522 obsoleted=\ *version* 523 The first version in which this declaration was obsoleted, meaning that it 524 was removed completely and can no longer be used. 525 526 unavailable 527 This declaration is never available on this platform. 528 529 message=\ *string-literal* 530 Additional message text that Clang will provide when emitting a warning or 531 error about use of a deprecated or obsoleted declaration. Useful to direct 532 users to replacement APIs. 533 534 Multiple availability attributes can be placed on a declaration, which may 535 correspond to different platforms. Only the availability attribute with the 536 platform corresponding to the target platform will be used; any others will be 537 ignored. If no availability attribute specifies availability for the current 538 target platform, the availability attributes are ignored. Supported platforms 539 are: 540 541 ``ios`` 542 Apple's iOS operating system. The minimum deployment target is specified by 543 the ``-mios-version-min=*version*`` or ``-miphoneos-version-min=*version*`` 544 command-line arguments. 545 546 ``macosx`` 547 Apple's Mac OS X operating system. The minimum deployment target is 548 specified by the ``-mmacosx-version-min=*version*`` command-line argument. 549 550 A declaration can be used even when deploying back to a platform version prior 551 to when the declaration was introduced. When this happens, the declaration is 552 `weakly linked 553 <https://developer.apple.com/library/mac/#documentation/MacOSX/Conceptual/BPFrameworks/Concepts/WeakLinking.html>`_, 554 as if the ``weak_import`` attribute were added to the declaration. A 555 weakly-linked declaration may or may not be present a run-time, and a program 556 can determine whether the declaration is present by checking whether the 557 address of that declaration is non-NULL. 558 559 If there are multiple declarations of the same entity, the availability 560 attributes must either match on a per-platform basis or later 561 declarations must not have availability attributes for that 562 platform. For example: 563 564 .. code-block:: c 565 566 void g(void) __attribute__((availability(macosx,introduced=10.4))); 567 void g(void) __attribute__((availability(macosx,introduced=10.4))); // okay, matches 568 void g(void) __attribute__((availability(ios,introduced=4.0))); // okay, adds a new platform 569 void g(void); // okay, inherits both macosx and ios availability from above. 570 void g(void) __attribute__((availability(macosx,introduced=10.5))); // error: mismatch 571 572 When one method overrides another, the overriding method can be more widely available than the overridden method, e.g.,: 573 574 .. code-block:: objc 575 576 @interface A 577 - (id)method __attribute__((availability(macosx,introduced=10.4))); 578 - (id)method2 __attribute__((availability(macosx,introduced=10.4))); 579 @end 580 581 @interface B : A 582 - (id)method __attribute__((availability(macosx,introduced=10.3))); // okay: method moved into base class later 583 - (id)method __attribute__((availability(macosx,introduced=10.5))); // error: this method was available via the base class in 10.4 584 @end 585 }]; 586 } 587 588 def FallthroughDocs : Documentation { 589 let Category = DocCatStmt; 590 let Content = [{ 591 The ``clang::fallthrough`` attribute is used along with the 592 ``-Wimplicit-fallthrough`` argument to annotate intentional fall-through 593 between switch labels. It can only be applied to a null statement placed at a 594 point of execution between any statement and the next switch label. It is 595 common to mark these places with a specific comment, but this attribute is 596 meant to replace comments with a more strict annotation, which can be checked 597 by the compiler. This attribute doesn't change semantics of the code and can 598 be used wherever an intended fall-through occurs. It is designed to mimic 599 control-flow statements like ``break;``, so it can be placed in most places 600 where ``break;`` can, but only if there are no statements on the execution path 601 between it and the next switch label. 602 603 Here is an example: 604 605 .. code-block:: c++ 606 607 // compile with -Wimplicit-fallthrough 608 switch (n) { 609 case 22: 610 case 33: // no warning: no statements between case labels 611 f(); 612 case 44: // warning: unannotated fall-through 613 g(); 614 [[clang::fallthrough]]; 615 case 55: // no warning 616 if (x) { 617 h(); 618 break; 619 } 620 else { 621 i(); 622 [[clang::fallthrough]]; 623 } 624 case 66: // no warning 625 p(); 626 [[clang::fallthrough]]; // warning: fallthrough annotation does not 627 // directly precede case label 628 q(); 629 case 77: // warning: unannotated fall-through 630 r(); 631 } 632 }]; 633 } 634 635 def ARMInterruptDocs : Documentation { 636 let Category = DocCatFunction; 637 let Content = [{ 638 Clang supports the GNU style ``__attribute__((interrupt("TYPE")))`` attribute on 639 ARM targets. This attribute may be attached to a function definition and 640 instructs the backend to generate appropriate function entry/exit code so that 641 it can be used directly as an interrupt service routine. 642 643 The parameter passed to the interrupt attribute is optional, but if 644 provided it must be a string literal with one of the following values: "IRQ", 645 "FIQ", "SWI", "ABORT", "UNDEF". 646 647 The semantics are as follows: 648 649 - If the function is AAPCS, Clang instructs the backend to realign the stack to 650 8 bytes on entry. This is a general requirement of the AAPCS at public 651 interfaces, but may not hold when an exception is taken. Doing this allows 652 other AAPCS functions to be called. 653 - If the CPU is M-class this is all that needs to be done since the architecture 654 itself is designed in such a way that functions obeying the normal AAPCS ABI 655 constraints are valid exception handlers. 656 - If the CPU is not M-class, the prologue and epilogue are modified to save all 657 non-banked registers that are used, so that upon return the user-mode state 658 will not be corrupted. Note that to avoid unnecessary overhead, only 659 general-purpose (integer) registers are saved in this way. If VFP operations 660 are needed, that state must be saved manually. 661 662 Specifically, interrupt kinds other than "FIQ" will save all core registers 663 except "lr" and "sp". "FIQ" interrupts will save r0-r7. 664 - If the CPU is not M-class, the return instruction is changed to one of the 665 canonical sequences permitted by the architecture for exception return. Where 666 possible the function itself will make the necessary "lr" adjustments so that 667 the "preferred return address" is selected. 668 669 Unfortunately the compiler is unable to make this guarantee for an "UNDEF" 670 handler, where the offset from "lr" to the preferred return address depends on 671 the execution state of the code which generated the exception. In this case 672 a sequence equivalent to "movs pc, lr" will be used. 673 }]; 674 } 675 676 def DocCatAMDGPURegisterAttributes : 677 DocumentationCategory<"AMD GPU Register Attributes"> { 678 let Content = [{ 679 Clang supports attributes for controlling register usage on AMD GPU 680 targets. These attributes may be attached to a kernel function 681 definition and is an optimization hint to the backend for the maximum 682 number of registers to use. This is useful in cases where register 683 limited occupancy is known to be an important factor for the 684 performance for the kernel. 685 686 The semantics are as follows: 687 688 - The backend will attempt to limit the number of used registers to 689 the specified value, but the exact number used is not 690 guaranteed. The number used may be rounded up to satisfy the 691 allocation requirements or ABI constraints of the subtarget. For 692 example, on Southern Islands VGPRs may only be allocated in 693 increments of 4, so requesting a limit of 39 VGPRs will really 694 attempt to use up to 40. Requesting more registers than the 695 subtarget supports will truncate to the maximum allowed. The backend 696 may also use fewer registers than requested whenever possible. 697 698 - 0 implies the default no limit on register usage. 699 700 - Ignored on older VLIW subtargets which did not have separate scalar 701 and vector registers, R600 through Northern Islands. 702 703 }]; 704 } 705 706 707 def AMDGPUNumVGPRDocs : Documentation { 708 let Category = DocCatAMDGPURegisterAttributes; 709 let Content = [{ 710 Clang supports the 711 ``__attribute__((amdgpu_num_vgpr(<num_registers>)))`` attribute on AMD 712 Southern Islands GPUs and later for controlling the number of vector 713 registers. A typical value would be between 4 and 256 in increments 714 of 4. 715 }]; 716 } 717 718 def AMDGPUNumSGPRDocs : Documentation { 719 let Category = DocCatAMDGPURegisterAttributes; 720 let Content = [{ 721 722 Clang supports the 723 ``__attribute__((amdgpu_num_sgpr(<num_registers>)))`` attribute on AMD 724 Southern Islands GPUs and later for controlling the number of scalar 725 registers. A typical value would be between 8 and 104 in increments of 726 8. 727 728 Due to common instruction constraints, an additional 2-4 SGPRs are 729 typically required for internal use depending on features used. This 730 value is a hint for the total number of SGPRs to use, and not the 731 number of user SGPRs, so no special consideration needs to be given 732 for these. 733 }]; 734 } 735 736 def DocCatCallingConvs : DocumentationCategory<"Calling Conventions"> { 737 let Content = [{ 738 Clang supports several different calling conventions, depending on the target 739 platform and architecture. The calling convention used for a function determines 740 how parameters are passed, how results are returned to the caller, and other 741 low-level details of calling a function. 742 }]; 743 } 744 745 def PcsDocs : Documentation { 746 let Category = DocCatCallingConvs; 747 let Content = [{ 748 On ARM targets, this attribute can be used to select calling conventions 749 similar to ``stdcall`` on x86. Valid parameter values are "aapcs" and 750 "aapcs-vfp". 751 }]; 752 } 753 754 def RegparmDocs : Documentation { 755 let Category = DocCatCallingConvs; 756 let Content = [{ 757 On 32-bit x86 targets, the regparm attribute causes the compiler to pass 758 the first three integer parameters in EAX, EDX, and ECX instead of on the 759 stack. This attribute has no effect on variadic functions, and all parameters 760 are passed via the stack as normal. 761 }]; 762 } 763 764 def SysVABIDocs : Documentation { 765 let Category = DocCatCallingConvs; 766 let Content = [{ 767 On Windows x86_64 targets, this attribute changes the calling convention of a 768 function to match the default convention used on Sys V targets such as Linux, 769 Mac, and BSD. This attribute has no effect on other targets. 770 }]; 771 } 772 773 def MSABIDocs : Documentation { 774 let Category = DocCatCallingConvs; 775 let Content = [{ 776 On non-Windows x86_64 targets, this attribute changes the calling convention of 777 a function to match the default convention used on Windows x86_64. This 778 attribute has no effect on Windows targets or non-x86_64 targets. 779 }]; 780 } 781 782 def StdCallDocs : Documentation { 783 let Category = DocCatCallingConvs; 784 let Content = [{ 785 On 32-bit x86 targets, this attribute changes the calling convention of a 786 function to clear parameters off of the stack on return. This convention does 787 not support variadic calls or unprototyped functions in C, and has no effect on 788 x86_64 targets. This calling convention is used widely by the Windows API and 789 COM applications. See the documentation for `__stdcall`_ on MSDN. 790 791 .. _`__stdcall`: http://msdn.microsoft.com/en-us/library/zxk0tw93.aspx 792 }]; 793 } 794 795 def FastCallDocs : Documentation { 796 let Category = DocCatCallingConvs; 797 let Content = [{ 798 On 32-bit x86 targets, this attribute changes the calling convention of a 799 function to use ECX and EDX as register parameters and clear parameters off of 800 the stack on return. This convention does not support variadic calls or 801 unprototyped functions in C, and has no effect on x86_64 targets. This calling 802 convention is supported primarily for compatibility with existing code. Users 803 seeking register parameters should use the ``regparm`` attribute, which does 804 not require callee-cleanup. See the documentation for `__fastcall`_ on MSDN. 805 806 .. _`__fastcall`: http://msdn.microsoft.com/en-us/library/6xa169sk.aspx 807 }]; 808 } 809 810 def ThisCallDocs : Documentation { 811 let Category = DocCatCallingConvs; 812 let Content = [{ 813 On 32-bit x86 targets, this attribute changes the calling convention of a 814 function to use ECX for the first parameter (typically the implicit ``this`` 815 parameter of C++ methods) and clear parameters off of the stack on return. This 816 convention does not support variadic calls or unprototyped functions in C, and 817 has no effect on x86_64 targets. See the documentation for `__thiscall`_ on 818 MSDN. 819 820 .. _`__thiscall`: http://msdn.microsoft.com/en-us/library/ek8tkfbw.aspx 821 }]; 822 } 823 824 def VectorCallDocs : Documentation { 825 let Category = DocCatCallingConvs; 826 let Content = [{ 827 On 32-bit x86 *and* x86_64 targets, this attribute changes the calling 828 convention of a function to pass vector parameters in SSE registers. 829 830 On 32-bit x86 targets, this calling convention is similar to ``__fastcall``. 831 The first two integer parameters are passed in ECX and EDX. Subsequent integer 832 parameters are passed in memory, and callee clears the stack. On x86_64 833 targets, the callee does *not* clear the stack, and integer parameters are 834 passed in RCX, RDX, R8, and R9 as is done for the default Windows x64 calling 835 convention. 836 837 On both 32-bit x86 and x86_64 targets, vector and floating point arguments are 838 passed in XMM0-XMM5. Homogenous vector aggregates of up to four elements are 839 passed in sequential SSE registers if enough are available. If AVX is enabled, 840 256 bit vectors are passed in YMM0-YMM5. Any vector or aggregate type that 841 cannot be passed in registers for any reason is passed by reference, which 842 allows the caller to align the parameter memory. 843 844 See the documentation for `__vectorcall`_ on MSDN for more details. 845 846 .. _`__vectorcall`: http://msdn.microsoft.com/en-us/library/dn375768.aspx 847 }]; 848 } 849 850 def DocCatConsumed : DocumentationCategory<"Consumed Annotation Checking"> { 851 let Content = [{ 852 Clang supports additional attributes for checking basic resource management 853 properties, specifically for unique objects that have a single owning reference. 854 The following attributes are currently supported, although **the implementation 855 for these annotations is currently in development and are subject to change.** 856 }]; 857 } 858 859 def SetTypestateDocs : Documentation { 860 let Category = DocCatConsumed; 861 let Content = [{ 862 Annotate methods that transition an object into a new state with 863 ``__attribute__((set_typestate(new_state)))``. The new state must be 864 unconsumed, consumed, or unknown. 865 }]; 866 } 867 868 def CallableWhenDocs : Documentation { 869 let Category = DocCatConsumed; 870 let Content = [{ 871 Use ``__attribute__((callable_when(...)))`` to indicate what states a method 872 may be called in. Valid states are unconsumed, consumed, or unknown. Each 873 argument to this attribute must be a quoted string. E.g.: 874 875 ``__attribute__((callable_when("unconsumed", "unknown")))`` 876 }]; 877 } 878 879 def TestTypestateDocs : Documentation { 880 let Category = DocCatConsumed; 881 let Content = [{ 882 Use ``__attribute__((test_typestate(tested_state)))`` to indicate that a method 883 returns true if the object is in the specified state.. 884 }]; 885 } 886 887 def ParamTypestateDocs : Documentation { 888 let Category = DocCatConsumed; 889 let Content = [{ 890 This attribute specifies expectations about function parameters. Calls to an 891 function with annotated parameters will issue a warning if the corresponding 892 argument isn't in the expected state. The attribute is also used to set the 893 initial state of the parameter when analyzing the function's body. 894 }]; 895 } 896 897 def ReturnTypestateDocs : Documentation { 898 let Category = DocCatConsumed; 899 let Content = [{ 900 The ``return_typestate`` attribute can be applied to functions or parameters. 901 When applied to a function the attribute specifies the state of the returned 902 value. The function's body is checked to ensure that it always returns a value 903 in the specified state. On the caller side, values returned by the annotated 904 function are initialized to the given state. 905 906 When applied to a function parameter it modifies the state of an argument after 907 a call to the function returns. The function's body is checked to ensure that 908 the parameter is in the expected state before returning. 909 }]; 910 } 911 912 def ConsumableDocs : Documentation { 913 let Category = DocCatConsumed; 914 let Content = [{ 915 Each ``class`` that uses any of the typestate annotations must first be marked 916 using the ``consumable`` attribute. Failure to do so will result in a warning. 917 918 This attribute accepts a single parameter that must be one of the following: 919 ``unknown``, ``consumed``, or ``unconsumed``. 920 }]; 921 } 922 923 def NoSanitizeAddressDocs : Documentation { 924 let Category = DocCatFunction; 925 // This function has multiple distinct spellings, and so it requires a custom 926 // heading to be specified. The most common spelling is sufficient. 927 let Heading = "no_sanitize_address (no_address_safety_analysis, gnu::no_address_safety_analysis, gnu::no_sanitize_address)"; 928 let Content = [{ 929 .. _langext-address_sanitizer: 930 931 Use ``__attribute__((no_sanitize_address))`` on a function declaration to 932 specify that address safety instrumentation (e.g. AddressSanitizer) should 933 not be applied to that function. 934 }]; 935 } 936 937 def NoSanitizeThreadDocs : Documentation { 938 let Category = DocCatFunction; 939 let Content = [{ 940 .. _langext-thread_sanitizer: 941 942 Use ``__attribute__((no_sanitize_thread))`` on a function declaration to 943 specify that checks for data races on plain (non-atomic) memory accesses should 944 not be inserted by ThreadSanitizer. The function is still instrumented by the 945 tool to avoid false positives and provide meaningful stack traces. 946 }]; 947 } 948 949 def NoSanitizeMemoryDocs : Documentation { 950 let Category = DocCatFunction; 951 let Content = [{ 952 .. _langext-memory_sanitizer: 953 954 Use ``__attribute__((no_sanitize_memory))`` on a function declaration to 955 specify that checks for uninitialized memory should not be inserted 956 (e.g. by MemorySanitizer). The function may still be instrumented by the tool 957 to avoid false positives in other places. 958 }]; 959 } 960 961 def DocCatTypeSafety : DocumentationCategory<"Type Safety Checking"> { 962 let Content = [{ 963 Clang supports additional attributes to enable checking type safety properties 964 that can't be enforced by the C type system. Use cases include: 965 966 * MPI library implementations, where these attributes enable checking that 967 the buffer type matches the passed ``MPI_Datatype``; 968 * for HDF5 library there is a similar use case to MPI; 969 * checking types of variadic functions' arguments for functions like 970 ``fcntl()`` and ``ioctl()``. 971 972 You can detect support for these attributes with ``__has_attribute()``. For 973 example: 974 975 .. code-block:: c++ 976 977 #if defined(__has_attribute) 978 # if __has_attribute(argument_with_type_tag) && \ 979 __has_attribute(pointer_with_type_tag) && \ 980 __has_attribute(type_tag_for_datatype) 981 # define ATTR_MPI_PWT(buffer_idx, type_idx) __attribute__((pointer_with_type_tag(mpi,buffer_idx,type_idx))) 982 /* ... other macros ... */ 983 # endif 984 #endif 985 986 #if !defined(ATTR_MPI_PWT) 987 # define ATTR_MPI_PWT(buffer_idx, type_idx) 988 #endif 989 990 int MPI_Send(void *buf, int count, MPI_Datatype datatype /*, other args omitted */) 991 ATTR_MPI_PWT(1,3); 992 }]; 993 } 994 995 def ArgumentWithTypeTagDocs : Documentation { 996 let Category = DocCatTypeSafety; 997 let Heading = "argument_with_type_tag"; 998 let Content = [{ 999 Use ``__attribute__((argument_with_type_tag(arg_kind, arg_idx, 1000 type_tag_idx)))`` on a function declaration to specify that the function 1001 accepts a type tag that determines the type of some other argument. 1002 ``arg_kind`` is an identifier that should be used when annotating all 1003 applicable type tags. 1004 1005 This attribute is primarily useful for checking arguments of variadic functions 1006 (``pointer_with_type_tag`` can be used in most non-variadic cases). 1007 1008 For example: 1009 1010 .. code-block:: c++ 1011 1012 int fcntl(int fd, int cmd, ...) 1013 __attribute__(( argument_with_type_tag(fcntl,3,2) )); 1014 }]; 1015 } 1016 1017 def PointerWithTypeTagDocs : Documentation { 1018 let Category = DocCatTypeSafety; 1019 let Heading = "pointer_with_type_tag"; 1020 let Content = [{ 1021 Use ``__attribute__((pointer_with_type_tag(ptr_kind, ptr_idx, type_tag_idx)))`` 1022 on a function declaration to specify that the function accepts a type tag that 1023 determines the pointee type of some other pointer argument. 1024 1025 For example: 1026 1027 .. code-block:: c++ 1028 1029 int MPI_Send(void *buf, int count, MPI_Datatype datatype /*, other args omitted */) 1030 __attribute__(( pointer_with_type_tag(mpi,1,3) )); 1031 }]; 1032 } 1033 1034 def TypeTagForDatatypeDocs : Documentation { 1035 let Category = DocCatTypeSafety; 1036 let Content = [{ 1037 Clang supports annotating type tags of two forms. 1038 1039 * **Type tag that is an expression containing a reference to some declared 1040 identifier.** Use ``__attribute__((type_tag_for_datatype(kind, type)))`` on a 1041 declaration with that identifier: 1042 1043 .. code-block:: c++ 1044 1045 extern struct mpi_datatype mpi_datatype_int 1046 __attribute__(( type_tag_for_datatype(mpi,int) )); 1047 #define MPI_INT ((MPI_Datatype) &mpi_datatype_int) 1048 1049 * **Type tag that is an integral literal.** Introduce a ``static const`` 1050 variable with a corresponding initializer value and attach 1051 ``__attribute__((type_tag_for_datatype(kind, type)))`` on that declaration, 1052 for example: 1053 1054 .. code-block:: c++ 1055 1056 #define MPI_INT ((MPI_Datatype) 42) 1057 static const MPI_Datatype mpi_datatype_int 1058 __attribute__(( type_tag_for_datatype(mpi,int) )) = 42 1059 1060 The attribute also accepts an optional third argument that determines how the 1061 expression is compared to the type tag. There are two supported flags: 1062 1063 * ``layout_compatible`` will cause types to be compared according to 1064 layout-compatibility rules (C++11 [class.mem] p 17, 18). This is 1065 implemented to support annotating types like ``MPI_DOUBLE_INT``. 1066 1067 For example: 1068 1069 .. code-block:: c++ 1070 1071 /* In mpi.h */ 1072 struct internal_mpi_double_int { double d; int i; }; 1073 extern struct mpi_datatype mpi_datatype_double_int 1074 __attribute__(( type_tag_for_datatype(mpi, struct internal_mpi_double_int, layout_compatible) )); 1075 1076 #define MPI_DOUBLE_INT ((MPI_Datatype) &mpi_datatype_double_int) 1077 1078 /* In user code */ 1079 struct my_pair { double a; int b; }; 1080 struct my_pair *buffer; 1081 MPI_Send(buffer, 1, MPI_DOUBLE_INT /*, ... */); // no warning 1082 1083 struct my_int_pair { int a; int b; } 1084 struct my_int_pair *buffer2; 1085 MPI_Send(buffer2, 1, MPI_DOUBLE_INT /*, ... */); // warning: actual buffer element 1086 // type 'struct my_int_pair' 1087 // doesn't match specified MPI_Datatype 1088 1089 * ``must_be_null`` specifies that the expression should be a null pointer 1090 constant, for example: 1091 1092 .. code-block:: c++ 1093 1094 /* In mpi.h */ 1095 extern struct mpi_datatype mpi_datatype_null 1096 __attribute__(( type_tag_for_datatype(mpi, void, must_be_null) )); 1097 1098 #define MPI_DATATYPE_NULL ((MPI_Datatype) &mpi_datatype_null) 1099 1100 /* In user code */ 1101 MPI_Send(buffer, 1, MPI_DATATYPE_NULL /*, ... */); // warning: MPI_DATATYPE_NULL 1102 // was specified but buffer 1103 // is not a null pointer 1104 }]; 1105 } 1106 1107 def FlattenDocs : Documentation { 1108 let Category = DocCatFunction; 1109 let Content = [{ 1110 The ``flatten`` attribute causes calls within the attributed function to 1111 be inlined unless it is impossible to do so, for example if the body of the 1112 callee is unavailable or if the callee has the ``noinline`` attribute. 1113 }]; 1114 } 1115 1116 def FormatDocs : Documentation { 1117 let Category = DocCatFunction; 1118 let Content = [{ 1119 1120 Clang supports the ``format`` attribute, which indicates that the function 1121 accepts a ``printf`` or ``scanf``-like format string and corresponding 1122 arguments or a ``va_list`` that contains these arguments. 1123 1124 Please see `GCC documentation about format attribute 1125 <http://gcc.gnu.org/onlinedocs/gcc/Function-Attributes.html>`_ to find details 1126 about attribute syntax. 1127 1128 Clang implements two kinds of checks with this attribute. 1129 1130 #. Clang checks that the function with the ``format`` attribute is called with 1131 a format string that uses format specifiers that are allowed, and that 1132 arguments match the format string. This is the ``-Wformat`` warning, it is 1133 on by default. 1134 1135 #. Clang checks that the format string argument is a literal string. This is 1136 the ``-Wformat-nonliteral`` warning, it is off by default. 1137 1138 Clang implements this mostly the same way as GCC, but there is a difference 1139 for functions that accept a ``va_list`` argument (for example, ``vprintf``). 1140 GCC does not emit ``-Wformat-nonliteral`` warning for calls to such 1141 functions. Clang does not warn if the format string comes from a function 1142 parameter, where the function is annotated with a compatible attribute, 1143 otherwise it warns. For example: 1144 1145 .. code-block:: c 1146 1147 __attribute__((__format__ (__scanf__, 1, 3))) 1148 void foo(const char* s, char *buf, ...) { 1149 va_list ap; 1150 va_start(ap, buf); 1151 1152 vprintf(s, ap); // warning: format string is not a string literal 1153 } 1154 1155 In this case we warn because ``s`` contains a format string for a 1156 ``scanf``-like function, but it is passed to a ``printf``-like function. 1157 1158 If the attribute is removed, clang still warns, because the format string is 1159 not a string literal. 1160 1161 Another example: 1162 1163 .. code-block:: c 1164 1165 __attribute__((__format__ (__printf__, 1, 3))) 1166 void foo(const char* s, char *buf, ...) { 1167 va_list ap; 1168 va_start(ap, buf); 1169 1170 vprintf(s, ap); // warning 1171 } 1172 1173 In this case Clang does not warn because the format string ``s`` and 1174 the corresponding arguments are annotated. If the arguments are 1175 incorrect, the caller of ``foo`` will receive a warning. 1176 }]; 1177 } 1178 1179 def AlignValueDocs : Documentation { 1180 let Category = DocCatType; 1181 let Content = [{ 1182 The align_value attribute can be added to the typedef of a pointer type or the 1183 declaration of a variable of pointer or reference type. It specifies that the 1184 pointer will point to, or the reference will bind to, only objects with at 1185 least the provided alignment. This alignment value must be some positive power 1186 of 2. 1187 1188 .. code-block:: c 1189 1190 typedef double * aligned_double_ptr __attribute__((align_value(64))); 1191 void foo(double & x __attribute__((align_value(128)), 1192 aligned_double_ptr y) { ... } 1193 1194 If the pointer value does not have the specified alignment at runtime, the 1195 behavior of the program is undefined. 1196 }]; 1197 } 1198 1199 def FlagEnumDocs : Documentation { 1200 let Category = DocCatType; 1201 let Content = [{ 1202 This attribute can be added to an enumerator to signal to the compiler that it 1203 is intended to be used as a flag type. This will cause the compiler to assume 1204 that the range of the type includes all of the values that you can get by 1205 manipulating bits of the enumerator when issuing warnings. 1206 }]; 1207 } 1208 1209 def MSInheritanceDocs : Documentation { 1210 let Category = DocCatType; 1211 let Heading = "__single_inhertiance, __multiple_inheritance, __virtual_inheritance"; 1212 let Content = [{ 1213 This collection of keywords is enabled under ``-fms-extensions`` and controls 1214 the pointer-to-member representation used on ``*-*-win32`` targets. 1215 1216 The ``*-*-win32`` targets utilize a pointer-to-member representation which 1217 varies in size and alignment depending on the definition of the underlying 1218 class. 1219 1220 However, this is problematic when a forward declaration is only available and 1221 no definition has been made yet. In such cases, Clang is forced to utilize the 1222 most general representation that is available to it. 1223 1224 These keywords make it possible to use a pointer-to-member representation other 1225 than the most general one regardless of whether or not the definition will ever 1226 be present in the current translation unit. 1227 1228 This family of keywords belong between the ``class-key`` and ``class-name``: 1229 1230 .. code-block:: c++ 1231 1232 struct __single_inheritance S; 1233 int S::*i; 1234 struct S {}; 1235 1236 This keyword can be applied to class templates but only has an effect when used 1237 on full specializations: 1238 1239 .. code-block:: c++ 1240 1241 template <typename T, typename U> struct __single_inheritance A; // warning: inheritance model ignored on primary template 1242 template <typename T> struct __multiple_inheritance A<T, T>; // warning: inheritance model ignored on partial specialization 1243 template <> struct __single_inheritance A<int, float>; 1244 1245 Note that choosing an inheritance model less general than strictly necessary is 1246 an error: 1247 1248 .. code-block:: c++ 1249 1250 struct __multiple_inheritance S; // error: inheritance model does not match definition 1251 int S::*i; 1252 struct S {}; 1253 }]; 1254 } 1255 1256 def MSNoVTableDocs : Documentation { 1257 let Category = DocCatType; 1258 let Content = [{ 1259 This attribute can be added to a class declaration or definition to signal to 1260 the compiler that constructors and destructors will not reference the virtual 1261 function table. 1262 }]; 1263 } 1264 1265 def OptnoneDocs : Documentation { 1266 let Category = DocCatFunction; 1267 let Content = [{ 1268 The ``optnone`` attribute suppresses essentially all optimizations 1269 on a function or method, regardless of the optimization level applied to 1270 the compilation unit as a whole. This is particularly useful when you 1271 need to debug a particular function, but it is infeasible to build the 1272 entire application without optimization. Avoiding optimization on the 1273 specified function can improve the quality of the debugging information 1274 for that function. 1275 1276 This attribute is incompatible with the ``always_inline`` and ``minsize`` 1277 attributes. 1278 }]; 1279 } 1280 1281 def LoopHintDocs : Documentation { 1282 let Category = DocCatStmt; 1283 let Heading = "#pragma clang loop"; 1284 let Content = [{ 1285 The ``#pragma clang loop`` directive allows loop optimization hints to be 1286 specified for the subsequent loop. The directive allows vectorization, 1287 interleaving, and unrolling to be enabled or disabled. Vector width as well 1288 as interleave and unrolling count can be manually specified. See 1289 `language extensions 1290 <http://clang.llvm.org/docs/LanguageExtensions.html#extensions-for-loop-hint-optimizations>`_ 1291 for details. 1292 }]; 1293 } 1294 1295 def UnrollHintDocs : Documentation { 1296 let Category = DocCatStmt; 1297 let Heading = "#pragma unroll, #pragma nounroll"; 1298 let Content = [{ 1299 Loop unrolling optimization hints can be specified with ``#pragma unroll`` and 1300 ``#pragma nounroll``. The pragma is placed immediately before a for, while, 1301 do-while, or c++11 range-based for loop. 1302 1303 Specifying ``#pragma unroll`` without a parameter directs the loop unroller to 1304 attempt to fully unroll the loop if the trip count is known at compile time: 1305 1306 .. code-block:: c++ 1307 1308 #pragma unroll 1309 for (...) { 1310 ... 1311 } 1312 1313 Specifying the optional parameter, ``#pragma unroll _value_``, directs the 1314 unroller to unroll the loop ``_value_`` times. The parameter may optionally be 1315 enclosed in parentheses: 1316 1317 .. code-block:: c++ 1318 1319 #pragma unroll 16 1320 for (...) { 1321 ... 1322 } 1323 1324 #pragma unroll(16) 1325 for (...) { 1326 ... 1327 } 1328 1329 Specifying ``#pragma nounroll`` indicates that the loop should not be unrolled: 1330 1331 .. code-block:: c++ 1332 1333 #pragma nounroll 1334 for (...) { 1335 ... 1336 } 1337 1338 ``#pragma unroll`` and ``#pragma unroll _value_`` have identical semantics to 1339 ``#pragma clang loop unroll(full)`` and 1340 ``#pragma clang loop unroll_count(_value_)`` respectively. ``#pragma nounroll`` 1341 is equivalent to ``#pragma clang loop unroll(disable)``. See 1342 `language extensions 1343 <http://clang.llvm.org/docs/LanguageExtensions.html#extensions-for-loop-hint-optimizations>`_ 1344 for further details including limitations of the unroll hints. 1345 }]; 1346 } 1347 1348 def DocOpenCLAddressSpaces : DocumentationCategory<"OpenCL Address Spaces"> { 1349 let Content = [{ 1350 The address space qualifier may be used to specify the region of memory that is 1351 used to allocate the object. OpenCL supports the following address spaces: 1352 __generic(generic), __global(global), __local(local), __private(private), 1353 __constant(constant). 1354 1355 .. code-block:: c 1356 1357 __constant int c = ...; 1358 1359 __generic int* foo(global int* g) { 1360 __local int* l; 1361 private int p; 1362 ... 1363 return l; 1364 } 1365 1366 More details can be found in the OpenCL C language Spec v2.0, Section 6.5. 1367 }]; 1368 } 1369 1370 def OpenCLAddressSpaceGenericDocs : Documentation { 1371 let Category = DocOpenCLAddressSpaces; 1372 let Heading = "__generic(generic)"; 1373 let Content = [{ 1374 The generic address space attribute is only available with OpenCL v2.0 and later. 1375 It can be used with pointer types. Variables in global and local scope and 1376 function parameters in non-kernel functions can have the generic address space 1377 type attribute. It is intended to be a placeholder for any other address space 1378 except for '__constant' in OpenCL code which can be used with multiple address 1379 spaces. 1380 }]; 1381 } 1382 1383 def OpenCLAddressSpaceConstantDocs : Documentation { 1384 let Category = DocOpenCLAddressSpaces; 1385 let Heading = "__constant(constant)"; 1386 let Content = [{ 1387 The constant address space attribute signals that an object is located in 1388 a constant (non-modifiable) memory region. It is available to all work items. 1389 Any type can be annotated with the constant address space attribute. Objects 1390 with the constant address space qualifier can be declared in any scope and must 1391 have an initializer. 1392 }]; 1393 } 1394 1395 def OpenCLAddressSpaceGlobalDocs : Documentation { 1396 let Category = DocOpenCLAddressSpaces; 1397 let Heading = "__global(global)"; 1398 let Content = [{ 1399 The global address space attribute specifies that an object is allocated in 1400 global memory, which is accessible by all work items. The content stored in this 1401 memory area persists between kernel executions. Pointer types to the global 1402 address space are allowed as function parameters or local variables. Starting 1403 with OpenCL v2.0, the global address space can be used with global (program 1404 scope) variables and static local variable as well. 1405 }]; 1406 } 1407 1408 def OpenCLAddressSpaceLocalDocs : Documentation { 1409 let Category = DocOpenCLAddressSpaces; 1410 let Heading = "__local(local)"; 1411 let Content = [{ 1412 The local address space specifies that an object is allocated in the local (work 1413 group) memory area, which is accessible to all work items in the same work 1414 group. The content stored in this memory region is not accessible after 1415 the kernel execution ends. In a kernel function scope, any variable can be in 1416 the local address space. In other scopes, only pointer types to the local address 1417 space are allowed. Local address space variables cannot have an initializer. 1418 }]; 1419 } 1420 1421 def OpenCLAddressSpacePrivateDocs : Documentation { 1422 let Category = DocOpenCLAddressSpaces; 1423 let Heading = "__private(private)"; 1424 let Content = [{ 1425 The private address space specifies that an object is allocated in the private 1426 (work item) memory. Other work items cannot access the same memory area and its 1427 content is destroyed after work item execution ends. Local variables can be 1428 declared in the private address space. Function arguments are always in the 1429 private address space. Kernel function arguments of a pointer or an array type 1430 cannot point to the private address space. 1431 }]; 1432 } 1433