diff options
Diffstat (limited to 'contrib/llvm-project/clang/include/clang/Basic/AttrDocs.td')
| -rw-r--r-- | contrib/llvm-project/clang/include/clang/Basic/AttrDocs.td | 314 |
1 files changed, 224 insertions, 90 deletions
diff --git a/contrib/llvm-project/clang/include/clang/Basic/AttrDocs.td b/contrib/llvm-project/clang/include/clang/Basic/AttrDocs.td index 7976d08a5258..3cba3a3d96f9 100644 --- a/contrib/llvm-project/clang/include/clang/Basic/AttrDocs.td +++ b/contrib/llvm-project/clang/include/clang/Basic/AttrDocs.td @@ -140,7 +140,8 @@ def NoEscapeDocs : Documentation { the compiler that the pointer cannot escape: that is, no reference to the object the pointer points to that is derived from the parameter value will survive after the function returns. Users are responsible for making sure parameters -annotated with ``noescape`` do not actuallly escape. +annotated with ``noescape`` do not actually escape. Calling ``free()`` on such +a parameter does not constitute an escape. For example: @@ -260,6 +261,7 @@ The ``sycl_kernel`` attribute specifies that a function template will be used to outline device code and to generate an OpenCL kernel. Here is a code example of the SYCL program, which demonstrates the compiler's outlining job: + .. code-block:: c++ int foo(int x) { return ++x; } @@ -282,27 +284,29 @@ compilation of functions for the device part can be found in the SYCL 1.2.1 specification Section 6.4. To show to the compiler entry point to the "device part" of the code, the SYCL runtime can use the ``sycl_kernel`` attribute in the following way: + .. code-block:: c++ -namespace cl { -namespace sycl { -class handler { - template <typename KernelName, typename KernelType/*, ...*/> - __attribute__((sycl_kernel)) void sycl_kernel_function(KernelType KernelFuncObj) { - // ... - KernelFuncObj(); - } - template <typename KernelName, typename KernelType, int Dims> - void parallel_for(range<Dims> NumWorkItems, KernelType KernelFunc) { -#ifdef __SYCL_DEVICE_ONLY__ - sycl_kernel_function<KernelName, KernelType, Dims>(KernelFunc); -#else - // Host implementation -#endif - } -}; -} // namespace sycl -} // namespace cl + namespace cl { + namespace sycl { + class handler { + template <typename KernelName, typename KernelType/*, ...*/> + __attribute__((sycl_kernel)) void sycl_kernel_function(KernelType KernelFuncObj) { + // ... + KernelFuncObj(); + } + + template <typename KernelName, typename KernelType, int Dims> + void parallel_for(range<Dims> NumWorkItems, KernelType KernelFunc) { + #ifdef __SYCL_DEVICE_ONLY__ + sycl_kernel_function<KernelName, KernelType, Dims>(KernelFunc); + #else + // Host implementation + #endif + } + }; + } // namespace sycl + } // namespace cl The compiler will also generate an OpenCL kernel using the function marked with the ``sycl_kernel`` attribute. @@ -320,7 +324,7 @@ function marked with the ``sycl_kernel`` attribute: compiler uses function object type fields to generate OpenCL kernel parameters. - The function must return void. The compiler reuses the body of marked functions to - generate the OpenCL kernel body, and the OpenCL kernel must return `void`. + generate the OpenCL kernel body, and the OpenCL kernel must return ``void``. The SYCL kernel in the previous code sample meets these expectations. }]; @@ -346,6 +350,20 @@ that appears to be capable of returning to its caller. }]; } +def NoMergeDocs : Documentation { + let Category = DocCatFunction; + let Content = [{ +If a statement is marked ``nomerge`` and contains call experessions, those call +expressions inside the statement will not be merged during optimization. This +attribute can be used to prevent the optimizer from obscuring the source +location of certain calls. For example, it will prevent tail merging otherwise +identical code sequences that raise an exception or terminate the program. Tail +merging normally reduces the precision of source location information, making +stack traces less useful for debugging. This attribute gives the user control +over the tradeoff between code size and debug information precision. + }]; +} + def AssertCapabilityDocs : Documentation { let Category = DocCatFunction; let Heading = "assert_capability, assert_shared_capability"; @@ -481,7 +499,7 @@ parameter. Note that this attribute merely informs the compiler that a function always returns a sufficiently aligned pointer. It does not cause the compiler to emit code to enforce that alignment. The behavior is undefined if the returned -poitner is not sufficiently aligned. +pointer is not sufficiently aligned. }]; } @@ -939,11 +957,11 @@ The behavior of a function with respect to reference counting for Foundation convention (e.g. functions starting with "get" are assumed to return at ``+0``). -It can be overriden using a family of the following attributes. In +It can be overridden using a family of the following attributes. In Objective-C, the annotation ``__attribute__((ns_returns_retained))`` applied to a function communicates that the object is returned at ``+1``, and the caller is responsible for freeing it. -Similiarly, the annotation ``__attribute__((ns_returns_not_retained))`` +Similarly, the annotation ``__attribute__((ns_returns_not_retained))`` specifies that the object is returned at ``+0`` and the ownership remains with the callee. The annotation ``__attribute__((ns_consumes_self))`` specifies that @@ -1159,7 +1177,7 @@ def ObjCRuntimeNameDocs : Documentation { let Category = DocCatDecl; let Content = [{ By default, the Objective-C interface or protocol identifier is used -in the metadata name for that object. The `objc_runtime_name` +in the metadata name for that object. The ``objc_runtime_name`` attribute allows annotated interfaces or protocols to use the specified string argument in the object's metadata name instead of the default name. @@ -1287,7 +1305,7 @@ correspond to different platforms. For most platforms, the availability attribute with the platform corresponding to the target platform will be used; any others will be ignored. However, the availability for ``watchOS`` and ``tvOS`` can be implicitly inferred from an ``iOS`` availability attribute. -Any explicit availability attributes for those platforms are still prefered over +Any explicit availability attributes for those platforms are still preferred over the implicitly inferred availability attributes. If no availability attribute specifies availability for the current target platform, the availability attributes are ignored. Supported platforms are: @@ -1395,7 +1413,7 @@ pragma rather than using the inferred ``iOS`` availability from the declaration: void getsThePragmaTVOSAvailabilityAttribute(void) __attribute__((availability(iOS,introduced=11.0))); #pragma clang attribute pop -The compiler is also able to apply implicly inferred attributes from a pragma +The compiler is also able to apply implicitly inferred attributes from a pragma as well. For example, when targeting ``tvOS``, the function below will receive a ``tvOS`` availability attribute that is implicitly inferred from the ``iOS`` availability attribute applied by the pragma: @@ -1563,7 +1581,7 @@ expression are discarded under suspicious circumstances. A diagnostic is generated when a function or its return type is marked with ``[[nodiscard]]`` (or ``__attribute__((warn_unused_result))``) and the function call appears as a potentially-evaluated discarded-value expression that is not explicitly cast to -`void`. +``void``. A string literal may optionally be provided to the attribute, which will be reproduced in any resulting diagnostics. Redeclarations using different forms @@ -1713,7 +1731,7 @@ def BPFPreserveAccessIndexDocs : Documentation { Clang supports the ``__attribute__((preserve_access_index))`` attribute for the BPF target. This attribute may be attached to a struct or union declaration, where if -g is specified, it enables -preserving struct or union member access debuginfo indicies of this +preserving struct or union member access debuginfo indices of this struct or union, similar to clang ``__builtin_preserve_acceess_index()``. }]; } @@ -1729,7 +1747,7 @@ directly as an interrupt service routine. By default, the compiler will produce a function prologue and epilogue suitable for an interrupt service routine that handles an External Interrupt Controller (eic) -generated interrupt. This behaviour can be explicitly requested with the "eic" +generated interrupt. This behavior can be explicitly requested with the "eic" argument. Otherwise, for use with vectored interrupt mode, the argument passed should be @@ -1767,7 +1785,7 @@ Clang supports the GNU style ``__attribute__((micromips))`` and may be attached to a function definition and instructs the backend to generate or not to generate microMIPS code for that function. -These attributes override the `-mmicromips` and `-mno-micromips` options +These attributes override the ``-mmicromips`` and ``-mno-micromips`` options on the command line. }]; } @@ -2764,11 +2782,13 @@ The ``trivial_abi`` attribute can be applied to a C++ class, struct, or union. It instructs the compiler to pass and return the type using the C ABI for the underlying type when the type would otherwise be considered non-trivial for the purpose of calls. -A class annotated with `trivial_abi` can have non-trivial destructors or copy/move constructors without automatically becoming non-trivial for the purposes of calls. For example: +A class annotated with ``trivial_abi`` can have non-trivial destructors or +copy/move constructors without automatically becoming non-trivial for the +purposes of calls. For example: .. code-block:: c++ - // A is trivial for the purposes of calls because `trivial_abi` makes the + // A is trivial for the purposes of calls because ``trivial_abi`` makes the // user-provided special functions trivial. struct __attribute__((trivial_abi)) A { ~A(); @@ -2790,6 +2810,7 @@ destroy the object before returning. Attribute ``trivial_abi`` has no effect in the following cases: - The class directly declares a virtual base or virtual methods. +- Copy constructors and move constructors of the class are all deleted. - The class has a base class that is non-trivial for the purposes of calls. - The class has a non-static data member whose type is non-trivial for the purposes of calls, which includes: @@ -3296,15 +3317,15 @@ def OMPDeclareSimdDocs : Documentation { let Category = DocCatFunction; let Heading = "#pragma omp declare simd"; let Content = [{ -The `declare simd` construct can be applied to a function to enable the creation +The ``declare simd`` construct can be applied to a function to enable the creation of one or more versions that can process multiple arguments using SIMD -instructions from a single invocation in a SIMD loop. The `declare simd` -directive is a declarative directive. There may be multiple `declare simd` -directives for a function. The use of a `declare simd` construct on a function +instructions from a single invocation in a SIMD loop. The ``declare simd`` +directive is a declarative directive. There may be multiple ``declare simd`` +directives for a function. The use of a ``declare simd`` construct on a function enables the creation of SIMD versions of the associated function that can be used to process multiple arguments from a single invocation from a SIMD loop concurrently. -The syntax of the `declare simd` construct is as follows: +The syntax of the ``declare simd`` construct is as follows: .. code-block:: none @@ -3331,7 +3352,7 @@ def OMPDeclareTargetDocs : Documentation { let Category = DocCatFunction; let Heading = "#pragma omp declare target"; let Content = [{ -The `declare target` directive specifies that variables and functions are mapped +The ``declare target`` directive specifies that variables and functions are mapped to a device for OpenMP offload mechanism. The syntax of the declare target directive is as follows: @@ -3369,10 +3390,10 @@ def OMPDeclareVariantDocs : Documentation { let Category = DocCatFunction; let Heading = "#pragma omp declare variant"; let Content = [{ -The `declare variant` directive declares a specialized variant of a base - function and specifies the context in which that specialized variant is used. - The declare variant directive is a declarative directive. -The syntax of the `declare variant` construct is as follows: +The ``declare variant`` directive declares a specialized variant of a base +function and specifies the context in which that specialized variant is used. +The declare variant directive is a declarative directive. +The syntax of the ``declare variant`` construct is as follows: .. code-block:: none @@ -3387,8 +3408,23 @@ where clause is one of the following: match(context-selector-specification) -and where `variant-func-id` is the name of a function variant that is either a - base language identifier or, for C++, a template-id. +and where ``variant-func-id`` is the name of a function variant that is either a +base language identifier or, for C++, a template-id. + +Clang provides the following context selector extensions, used via +``implementation={extension(EXTENSION)}``: + + .. code-block:: none + + match_all + match_any + match_none + +The match extensions change when the *entire* context selector is considered a +match for an OpenMP context. The default is ``all``, with ``none`` no trait in the +selector is allowed to be in the OpenMP context, with ``any`` a single trait in +both the selector and OpenMP context is sufficient. Only a single match +extension trait is allowed per context selector. }]; } @@ -3473,7 +3509,7 @@ def NoThrowDocs : Documentation { let Category = DocCatFunction; let Content = [{ Clang supports the GNU style ``__attribute__((nothrow))`` and Microsoft style -``__declspec(nothrow)`` attribute as an equivalent of `noexcept` on function +``__declspec(nothrow)`` attribute as an equivalent of ``noexcept`` on function declarations. This attribute informs the compiler that the annotated function does not throw an exception. This prevents exception-unwinding. This attribute is particularly useful on functions in the C Standard Library that are @@ -3676,7 +3712,7 @@ using the Swift calling convention for a function or function pointer. The lowering for the Swift calling convention, as described by the Swift ABI documentation, occurs in multiple phases. The first, "high-level" phase breaks down the formal parameters and results into innately direct -and indirect components, adds implicit paraameters for the generic +and indirect components, adds implicit parameters for the generic signature, and assigns the context and error ABI treatments to parameters where applicable. The second phase breaks down the direct parameters and results from the first phase and assigns them to registers or the @@ -3718,7 +3754,7 @@ of the first phase, as follows: ``swiftcall`` does not support variadic arguments or unprototyped functions. The parameter ABI treatment attributes are aspects of the function type. -A function type which which applies an ABI treatment attribute to a +A function type which applies an ABI treatment attribute to a parameter is a different type from an otherwise-identical function type that does not. A single parameter may not have multiple ABI treatment attributes. @@ -3847,7 +3883,7 @@ with different ABI versions supported. For example, a newer version of a class could have a different set of data members and thus have a different size. Using the ``abi_tag`` attribute, it is possible to have different mangled names for a global variable of the class type. Therefore, the old code could keep using -the old manged name and the new code will use the new mangled name with tags. +the old mangled name and the new code will use the new mangled name with tags. }]; } @@ -3873,10 +3909,10 @@ that have a hot path and a cold path. The hot path is usually a small piece of code that doesn't use many registers. The cold path might need to call out to another function and therefore only needs to preserve the caller-saved registers, which haven't already been saved by the caller. The -`preserve_most` calling convention is very similar to the ``cold`` calling +``preserve_most`` calling convention is very similar to the ``cold`` calling convention in terms of caller/callee-saved registers, but they are used for different types of function calls. ``coldcc`` is for function calls that are -rarely executed, whereas `preserve_most` function calls are intended to be +rarely executed, whereas ``preserve_most`` function calls are intended to be on the hot path and definitely executed a lot. Furthermore ``preserve_most`` doesn't prevent the inliner from inlining the function call. @@ -3930,11 +3966,11 @@ Consider the function declaration for a hypothetical function ``f``: void f(void) __attribute__((deprecated("message", "replacement"))); -When spelled as `__attribute__((deprecated))`, the deprecated attribute can have +When spelled as ``__attribute__((deprecated))``, the deprecated attribute can have two optional string arguments. The first one is the message to display when emitting the warning; the second one enables the compiler to provide a Fix-It to replace the deprecated name with a new name. Otherwise, when spelled as -`[[gnu::deprecated]] or [[deprecated]]`, the attribute can have one optional +``[[gnu::deprecated]]`` or ``[[deprecated]]``, the attribute can have one optional string argument which is the message to display when emitting the warning. }]; } @@ -4001,9 +4037,9 @@ takes precedence over the command line option ``-fpatchable-function-entry=N,M`` def TransparentUnionDocs : Documentation { let Category = DocCatDecl; let Content = [{ -This attribute can be applied to a union to change the behaviour of calls to +This attribute can be applied to a union to change the behavior of calls to functions that have an argument with a transparent union type. The compiler -behaviour is changed in the following manner: +behavior is changed in the following manner: - A value whose type is any member of the transparent union can be passed as an argument without the need to cast that value. @@ -4033,7 +4069,7 @@ initialized classes. A non-lazy class will be initialized eagerly when the Objective-C runtime is loaded. This is required for certain system classes which have instances allocated in non-standard ways, such as the classes for blocks and constant strings. Adding this attribute is essentially equivalent to -providing a trivial `+load` method but avoids the (fairly small) load-time +providing a trivial ``+load`` method but avoids the (fairly small) load-time overheads associated with defining and calling such a method. }]; } @@ -4073,8 +4109,8 @@ ways: including calling the ``+initialize`` method if present. - The implicit ``_cmd`` parameter containing the method's selector is still defined. - In order to minimize code-size costs, the implementation will not emit a reference - to the selector if the parameter is unused within the method. + In order to minimize code-size costs, the implementation will not emit a reference + to the selector if the parameter is unused within the method. Symbols for direct method implementations are implicitly given hidden visibility, meaning that they can only be called within the same linkage unit. @@ -4115,7 +4151,7 @@ documentation for more information. def ObjCDirectMembersDocs : Documentation { let Category = DocCatDecl; let Content = [{ -The ``objc_direct_members`` attribute can be placed on an Objective-C +The ``objc_direct_members`` attribute can be placed on an Objective-C ``@interface`` or ``@implementation`` to mark that methods declared therein should be considered direct by default. See the documentation for ``objc_direct`` for more information about direct methods. @@ -4124,9 +4160,7 @@ When ``objc_direct_members`` is placed on an ``@interface`` block, every method in the block is considered to be declared as direct. This includes any implicit method declarations introduced by property declarations. If the method redeclares a non-direct method, the declaration is ill-formed, exactly as if the -method was annotated with the ``objc_direct`` attribute. ``objc_direct_members`` -cannot be placed on the primary interface of a class, only on category or class -extension interfaces. +method was annotated with the ``objc_direct`` attribute. When ``objc_direct_members`` is placed on an ``@implementation`` block, methods defined in the block are considered to be declared as direct unless @@ -4329,7 +4363,7 @@ with this attribute. This is because previously constructed subobjects need to be destroyed if an exception gets thrown before the initialization of the complete object is complete. For instance: -.. code-block::c++ +.. code-block:: c++ void f() { try { @@ -4340,7 +4374,7 @@ complete object is complete. For instance: } } -Here, if the construction of `array[9]` fails with an exception, `array[0..8]` +Here, if the construction of ``array[9]`` fails with an exception, ``array[0..8]`` will be destroyed, so the element's destructor needs to be accessible. }]; } @@ -4357,6 +4391,29 @@ it rather documents the programmer's intent. }]; } +def LoaderUninitializedDocs : Documentation { + let Category = DocCatVariable; + let Content = [{ +The ``loader_uninitialized`` attribute can be placed on global variables to +indicate that the variable does not need to be zero initialized by the loader. +On most targets, zero-initialization does not incur any additional cost. +For example, most general purpose operating systems deliberately ensure +that all memory is properly initialized in order to avoid leaking privileged +information from the kernel or other programs. However, some targets +do not make this guarantee, and on these targets, avoiding an unnecessary +zero-initialization can have a significant impact on load times and/or code +size. + +A declaration with this attribute is a non-tentative definition just as if it +provided an initializer. Variables with this attribute are considered to be +uninitialized in the same sense as a local variable, and the programs must +write to them before reading from them. If the variable's type is a C++ class +type with a non-trivial default constructor, or an array thereof, this attribute +only suppresses the static zero-initialization of the variable, not the dynamic +initialization provided by executing the default constructor. + }]; +} + def CallbackDocs : Documentation { let Category = DocCatFunction; let Content = [{ @@ -4366,7 +4423,7 @@ arguments, are identified by their parameter name or position (starting with 1!) in the annotated function. The first position in the attribute identifies the callback callee, the following positions declare describe its arguments. The callback callee is required to be callable with the number, and order, of -the specified arguments. The index `0`, or the identifier `this`, is used to +the specified arguments. The index ``0``, or the identifier ``this``, is used to represent an implicit "this" pointer in class methods. If there is no implicit "this" pointer it shall not be referenced. The index '-1', or the name "__", represents an unknown callback callee argument. This can be a value which is @@ -4383,13 +4440,13 @@ position, it is undefined if that parameter is used for anything other than the actual callback. Inspected, captured, or modified parameters shall not be listed in the ``callback`` metadata. -Example encodings for the callback performed by `pthread_create` are shown +Example encodings for the callback performed by ``pthread_create`` are shown below. The explicit attribute annotation indicates that the third parameter -(`start_routine`) is called zero or more times by the `pthread_create` function, -and that the fourth parameter (`arg`) is passed along. Note that the callback -behavior of `pthread_create` is automatically recognized by Clang. In addition, -the declarations of `__kmpc_fork_teams` and `__kmpc_fork_call`, generated for -`#pragma omp target teams` and `#pragma omp parallel`, respectively, are also +(``start_routine``) is called zero or more times by the ``pthread_create`` function, +and that the fourth parameter (``arg``) is passed along. Note that the callback +behavior of ``pthread_create`` is automatically recognized by Clang. In addition, +the declarations of ``__kmpc_fork_teams`` and ``__kmpc_fork_call``, generated for +``#pragma omp target teams`` and ``#pragma omp parallel``, respectively, are also automatically recognized as broker functions. Further functions might be added in the future. @@ -4514,7 +4571,7 @@ When applied to the definition of a function, method, or block, every parameter of the function with implicit strong retainable object pointer type is considered externally-retained, and becomes ``const``. By explicitly annotating a parameter with ``__strong``, you can opt back into the default -non-externally-retained behaviour for that parameter. For instance, +non-externally-retained behavior for that parameter. For instance, ``first_param`` is externally-retained below, but not ``second_param``: .. code-block:: objc @@ -4536,7 +4593,7 @@ def MIGConventionDocs : Documentation { The Mach Interface Generator release-on-success convention dictates functions that follow it to only release arguments passed to them when they return "success" (a ``kern_return_t`` error code that indicates that -no errors have occured). Otherwise the release is performed by the MIG client +no errors have occurred). Otherwise the release is performed by the MIG client that called the function. The annotation ``__attribute__((mig_server_routine))`` is applied in order to specify which functions are expected to follow the convention. This allows the Static Analyzer to find bugs caused by violations of @@ -4588,15 +4645,25 @@ only call one function. }]; } -def HIPPinnedShadowDocs : Documentation { +def CUDADeviceBuiltinSurfaceTypeDocs : Documentation { + let Category = DocCatType; + let Content = [{ +The ``device_builtin_surface_type`` attribute can be applied to a class +template when declaring the surface reference. A surface reference variable +could be accessed on the host side and, on the device side, might be translated +into an internal surface object, which is established through surface bind and +unbind runtime APIs. + }]; +} + +def CUDADeviceBuiltinTextureTypeDocs : Documentation { let Category = DocCatType; let Content = [{ -The GNU style attribute __attribute__((hip_pinned_shadow)) or MSVC style attribute -__declspec(hip_pinned_shadow) can be added to the definition of a global variable -to indicate it is a HIP pinned shadow variable. A HIP pinned shadow variable can -be accessed on both device side and host side. It has external linkage and is -not initialized on device side. It has internal linkage and is initialized by -the initializer on host side. +The ``device_builtin_texture_type`` attribute can be applied to a class +template when declaring the texture reference. A texture reference variable +could be accessed on the host side and, on the device side, might be translated +into an internal texture object, which is established through texture bind and +unbind runtime APIs. }]; } @@ -4609,7 +4676,7 @@ def LifetimeOwnerDocs : Documentation { The attribute ``[[gsl::Owner(T)]]`` applies to structs and classes that own an object of type ``T``: -.. code-block:: c++ +.. code:: class [[gsl::Owner(int)]] IntOwner { private: @@ -4635,7 +4702,7 @@ def LifetimePointerDocs : Documentation { The attribute ``[[gsl::Pointer(T)]]`` applies to structs and classes that behave like pointers to an object of type ``T``: -.. code-block:: c++ +.. code:: class [[gsl::Pointer(int)]] IntPointer { private: @@ -4668,11 +4735,11 @@ When the Owner's lifetime ends, it will consider the Pointer to be dangling. }]; } -def ArmMveAliasDocs : Documentation { +def ArmBuiltinAliasDocs : Documentation { let Category = DocCatFunction; let Content = [{ -This attribute is used in the implementation of the ACLE intrinsics -for the Arm MVE instruction set. It allows the intrinsic functions to +This attribute is used in the implementation of the ACLE intrinsics. +It allows the intrinsic functions to be declared using the names defined in ACLE, and still be recognized as clang builtins equivalent to the underlying name. For example, ``arm_mve.h`` declares the function ``vaddq_u32`` with @@ -4683,8 +4750,8 @@ recognized as that clang builtin, and in the latter case, the choice of which builtin to identify the function as can be deferred until after overload resolution. -This attribute can only be used to set up the aliases for the MVE -intrinsic functions; it is intended for use only inside ``arm_mve.h``, +This attribute can only be used to set up the aliases for certain Arm +intrinsic functions; it is intended for use only inside ``arm_*.h`` and is not a general mechanism for declaring arbitrary aliases for clang builtin functions. }]; @@ -4694,7 +4761,7 @@ def NoBuiltinDocs : Documentation { let Category = DocCatFunction; let Content = [{ .. Note:: This attribute is not yet fully implemented, it is validated but has -no effect on the generated code. + no effect on the generated code. The ``__attribute__((no_builtin))`` is similar to the ``-fno-builtin`` flag except it is specific to the body of a function. The attribute may also be @@ -4765,7 +4832,7 @@ def UseHandleDocs : Documentation { let Category = HandleDocs; let Content = [{ A function taking a handle by value might close the handle. If a function -parameter is annotated with `use_handle` it is assumed to not to change +parameter is annotated with ``use_handle`` it is assumed to not to change the state of the handle. It is also assumed to require an open handle to work with. .. code-block:: c++ @@ -4779,7 +4846,7 @@ the state of the handle. It is also assumed to require an open handle to work wi def ReleaseHandleDocs : Documentation { let Category = HandleDocs; let Content = [{ -If a function parameter is annotated with `release_handle` it is assumed to +If a function parameter is annotated with ``release_handle`` it is assumed to close the handle. It is also assumed to require an open handle to work with. .. code-block:: c++ @@ -4787,3 +4854,70 @@ close the handle. It is also assumed to require an open handle to work with. zx_status_t zx_handle_close(zx_handle_t handle [[clang::release_handle]]); }]; } + +def ArmMveStrictPolymorphismDocs : Documentation { + let Category = DocCatType; + let Content = [{ +This attribute is used in the implementation of the ACLE intrinsics for the Arm +MVE instruction set. It is used to define the vector types used by the MVE +intrinsics. + +Its effect is to modify the behavior of a vector type with respect to function +overloading. If a candidate function for overload resolution has a parameter +type with this attribute, then the selection of that candidate function will be +disallowed if the actual argument can only be converted via a lax vector +conversion. The aim is to prevent spurious ambiguity in ARM MVE polymorphic +intrinsics. + +.. code-block:: c++ + + void overloaded(uint16x8_t vector, uint16_t scalar); + void overloaded(int32x4_t vector, int32_t scalar); + uint16x8_t myVector; + uint16_t myScalar; + + // myScalar is promoted to int32_t as a side effect of the addition, + // so if lax vector conversions are considered for myVector, then + // the two overloads are equally good (one argument conversion + // each). But if the vector has the __clang_arm_mve_strict_polymorphism + // attribute, only the uint16x8_t,uint16_t overload will match. + overloaded(myVector, myScalar + 1); + +However, this attribute does not prohibit lax vector conversions in contexts +other than overloading. + +.. code-block:: c++ + + uint16x8_t function(); + + // This is still permitted with lax vector conversion enabled, even + // if the vector types have __clang_arm_mve_strict_polymorphism + int32x4_t result = function(); + + }]; +} + +def ArmCmseNSCallDocs : Documentation { + let Category = DocCatType; + let Content = [{ +This attribute declares a non-secure function type. When compiling for secure +state, a call to such a function would switch from secure to non-secure state. +All non-secure function calls must happen only through a function pointer, and +a non-secure function type should only be used as a base type of a pointer. +See `ARMv8-M Security Extensions: Requirements on Development +Tools - Engineering Specification Documentation +<https://developer.arm.com/docs/ecm0359818/latest/>`_ for more information. + }]; +} + +def ArmCmseNSEntryDocs : Documentation { + let Category = DocCatFunction; + let Content = [{ +This attribute declares a function that can be called from non-secure state, or +from secure state. Entering from and returning to non-secure state would switch +to and from secure state, respectively, and prevent flow of information +to non-secure state, except via return values. See `ARMv8-M Security Extensions: +Requirements on Development Tools - Engineering Specification Documentation +<https://developer.arm.com/docs/ecm0359818/latest/>`_ for more information. + }]; +} |