[llvm-branch-commits] [clang] [clang][docs] Check in attribute reference Markdown (PR #228592)
Reid Kleckner via llvm-branch-commits
llvm-branch-commits at lists.llvm.org
Sat Oct 10 09:13:41 PDT 2026
https://github.com/rnk updated https://github.com/llvm/llvm-project/pull/228592
>From 0d1acae486c2be692231a84ec4c92363dba1d8e5 Mon Sep 17 00:00:00 2001
From: Reid Kleckner <rkleckner at nvidia.com>
Date: Wed, 30 Sep 2026 23:46:29 +0000
Subject: [PATCH] [clang][docs] Check in attribute reference Markdown
Tracking issue: #227907
Implements stage 3 of #227907 by checking in AttributeReference.md and
AttributeReference/*.md, and by removing the docs build rules that
generated and split those Markdown sources.
This also adds the docs-build check for alphabetically sorted H3
attribute headings now that those headings are hand-authored in the
checked-in Markdown files.
The checked-in Markdown was populated with:
mkdir -p clang/docs/AttributeReference
cp build/tools/clang/docs/AttributeReference.md clang/docs/AttributeReference.md
cp build/tools/clang/docs/AttributeReference/*.md clang/docs/AttributeReference/
The AttrDocs TableGen backend is retained as a deterministic migration
tool for long-lived branches: rebase onto stage 2, generate before/after
Markdown, and apply the resulting Markdown diff when rebasing over this
stage.
---
clang/docs/AttributeReference.md | 66 +
.../AArch64SMEAttributes.md | 206 +
.../AttributeReference/AMDGPUAttributes.md | 166 +
.../AttributeReference/CallingConventions.md | 299 ++
.../ConsumedAnnotationChecking.md | 71 +
.../CustomizingSwiftImport.md | 253 +
.../DeclarationAttributes.md | 1287 +++++
.../AttributeReference/FieldAttributes.md | 436 ++
.../AttributeReference/FunctionAttributes.md | 4534 +++++++++++++++++
.../AttributeReference/HandleAttributes.md | 63 +
.../NullabilityAttributes.md | 200 +
.../AttributeReference/OpenCLAddressSpaces.md | 108 +
.../PerformanceConstraintAttributes.md | 60 +
.../AttributeReference/StatementAttributes.md | 807 +++
.../docs/AttributeReference/TypeAttributes.md | 801 +++
.../AttributeReference/TypeSafetyChecking.md | 210 +
clang/docs/AttributeReference/Undocumented.md | 579 +++
.../AttributeReference/VariableAttributes.md | 1128 ++++
clang/docs/CMakeLists.txt | 26 -
clang/docs/_extensions/clang_attr_syntaxes.py | 35 +
20 files changed, 11309 insertions(+), 26 deletions(-)
create mode 100644 clang/docs/AttributeReference.md
create mode 100644 clang/docs/AttributeReference/AArch64SMEAttributes.md
create mode 100644 clang/docs/AttributeReference/AMDGPUAttributes.md
create mode 100644 clang/docs/AttributeReference/CallingConventions.md
create mode 100644 clang/docs/AttributeReference/ConsumedAnnotationChecking.md
create mode 100644 clang/docs/AttributeReference/CustomizingSwiftImport.md
create mode 100644 clang/docs/AttributeReference/DeclarationAttributes.md
create mode 100644 clang/docs/AttributeReference/FieldAttributes.md
create mode 100644 clang/docs/AttributeReference/FunctionAttributes.md
create mode 100644 clang/docs/AttributeReference/HandleAttributes.md
create mode 100644 clang/docs/AttributeReference/NullabilityAttributes.md
create mode 100644 clang/docs/AttributeReference/OpenCLAddressSpaces.md
create mode 100644 clang/docs/AttributeReference/PerformanceConstraintAttributes.md
create mode 100644 clang/docs/AttributeReference/StatementAttributes.md
create mode 100644 clang/docs/AttributeReference/TypeAttributes.md
create mode 100644 clang/docs/AttributeReference/TypeSafetyChecking.md
create mode 100644 clang/docs/AttributeReference/Undocumented.md
create mode 100644 clang/docs/AttributeReference/VariableAttributes.md
diff --git a/clang/docs/AttributeReference.md b/clang/docs/AttributeReference.md
new file mode 100644
index 0000000000000..fde6c74f637d6
--- /dev/null
+++ b/clang/docs/AttributeReference.md
@@ -0,0 +1,66 @@
+% -------------------------------------------------------------------
+% NOTE: This file is automatically generated by running clang-tblgen
+% -gen-attr-docs. Do not edit this file by hand!!
+% -------------------------------------------------------------------
+
+# Attributes in Clang
+
+
+```{program} clang
+```
+
+## Introduction
+
+This page lists the attributes currently supported by Clang.
+
+:::{include} AttributeReference/AArch64SMEAttributes.md
+:::
+
+:::{include} AttributeReference/AMDGPUAttributes.md
+:::
+
+:::{include} AttributeReference/CallingConventions.md
+:::
+
+:::{include} AttributeReference/ConsumedAnnotationChecking.md
+:::
+
+:::{include} AttributeReference/CustomizingSwiftImport.md
+:::
+
+:::{include} AttributeReference/DeclarationAttributes.md
+:::
+
+:::{include} AttributeReference/FieldAttributes.md
+:::
+
+:::{include} AttributeReference/FunctionAttributes.md
+:::
+
+:::{include} AttributeReference/HandleAttributes.md
+:::
+
+:::{include} AttributeReference/NullabilityAttributes.md
+:::
+
+:::{include} AttributeReference/OpenCLAddressSpaces.md
+:::
+
+:::{include} AttributeReference/PerformanceConstraintAttributes.md
+:::
+
+:::{include} AttributeReference/StatementAttributes.md
+:::
+
+:::{include} AttributeReference/TypeAttributes.md
+:::
+
+:::{include} AttributeReference/TypeSafetyChecking.md
+:::
+
+:::{include} AttributeReference/Undocumented.md
+:::
+
+:::{include} AttributeReference/VariableAttributes.md
+:::
+
diff --git a/clang/docs/AttributeReference/AArch64SMEAttributes.md b/clang/docs/AttributeReference/AArch64SMEAttributes.md
new file mode 100644
index 0000000000000..5e95ebf5bdcd0
--- /dev/null
+++ b/clang/docs/AttributeReference/AArch64SMEAttributes.md
@@ -0,0 +1,206 @@
+## AArch64 SME Attributes
+
+Clang supports a number of AArch64-specific attributes to manage state
+added by the Scalable Matrix Extension (SME). This state includes the
+runtime mode that the processor is in (e.g. non-streaming or streaming)
+as well as the state of the `ZA` Matrix Storage.
+
+The attributes come in the form of type- and declaration attributes:
+
+- The SME declaration attributes can appear anywhere that a standard
+ `[[...]]` declaration attribute can appear.
+- The SME type attributes apply only to prototyped functions and can appear
+ anywhere that a standard `[[...]]` type attribute can appear. The SME
+ type attributes do not apply to functions having a K&R-style
+ unprototyped function type.
+
+See [Arm C Language Extensions](https://github.com/ARM-software/acle)
+for more details about the features related to the SME extension.
+
+See [Procedure Call Standard for the Arm® 64-bit Architecture (AArch64)](https://github.com/ARM-software/abi-aa) for more details about
+streaming-interface functions and shared/private-ZA interface functions.
+
+### __arm_agnostic
+
+{clang-attr-syntaxes}`ArmAgnosticDocs`
+
+The `__arm_agnostic` keyword applies to prototyped function types and
+affects the function's calling convention for a given state S. This
+attribute allows the user to describe a function that preserves S, without
+requiring the function to share S with its callers and without making
+the assumption that S exists.
+
+If a function has the `__arm_agnostic(S)` attribute and calls a function
+without this attribute, then the function's object code will contain code
+to preserve state S. Otherwise, the function's object code will be the same
+as if it did not have the attribute.
+
+The attribute takes string arguments to describe state S. The supported
+states are:
+
+- `"sme_za_state"` for state enabled by PSTATE.ZA, such as ZA and ZT0.
+
+The attribute `__arm_agnostic("sme_za_state")` cannot be used in conjunction
+with `__arm_in(S)`, `__arm_out(S)`, `__arm_inout(S)` or
+`__arm_preserves(S)` where state S describes state enabled by PSTATE.ZA,
+such as "za" or "zt0".
+
+
+### __arm_in
+
+{clang-attr-syntaxes}`ArmInDocs`
+
+The `__arm_in` keyword applies to prototyped function types and specifies
+that the function shares a given state S with its caller. For `__arm_in`, the
+function takes the state S as input and returns with the state S unchanged.
+
+The attribute takes string arguments to instruct the compiler which state
+is shared. The supported states for S are:
+
+- `"za"` for Matrix Storage (requires SME)
+
+The attributes `__arm_in(S)`, `__arm_out(S)`, `__arm_inout(S)` and
+`__arm_preserves(S)` are all mutually exclusive for the same state S.
+
+
+### __arm_inout
+
+{clang-attr-syntaxes}`ArmInOutDocs`
+
+The `__arm_inout` keyword applies to prototyped function types and specifies
+that the function shares a given state S with its caller. For `__arm_inout`,
+the function takes the state S as input and returns new state for S.
+
+The attribute takes string arguments to instruct the compiler which state
+is shared. The supported states for S are:
+
+- `"za"` for Matrix Storage (requires SME)
+
+The attributes `__arm_in(S)`, `__arm_out(S)`, `__arm_inout(S)` and
+`__arm_preserves(S)` are all mutually exclusive for the same state S.
+
+
+### __arm_locally_streaming
+
+{clang-attr-syntaxes}`ArmSmeLocallyStreamingDocs`
+
+The `__arm_locally_streaming` keyword applies to function declarations
+and specifies that all the statements in the function are executed in
+streaming mode. This means that:
+
+- the function requires that the target processor implements the Scalable Matrix
+ Extension (SME).
+- the program automatically puts the machine into streaming mode before
+ executing the statements and automatically restores the previous mode
+ afterwards.
+
+Clang manages PSTATE.SM automatically; it is not the source code's
+responsibility to do this. For example, Clang will emit code to enable
+streaming mode at the start of the function, and disable streaming mode
+at the end of the function.
+
+
+### __arm_new
+
+{clang-attr-syntaxes}`ArmNewDocs`
+
+The `__arm_new` keyword applies to function declarations and specifies
+that the function will create a new scope for state S.
+
+The attribute takes string arguments to instruct the compiler for which state
+to create new scope. The supported states for S are:
+
+- `"za"` for Matrix Storage (requires SME)
+
+For state `"za"`, this means that:
+
+- the function requires that the target processor implements the Scalable Matrix
+ Extension (SME).
+- the function will commit any lazily saved ZA data.
+- the function will create a new ZA context and enable PSTATE.ZA.
+- the function will disable PSTATE.ZA (by setting it to 0) before returning.
+
+For `__arm_new("za")` functions Clang will set up the ZA context automatically
+on entry to the function and disable it before returning. For example, if ZA is
+in a dormant state Clang will generate the code to commit a lazy-save and set up
+a new ZA state before executing user code.
+
+
+### __arm_out
+
+{clang-attr-syntaxes}`ArmOutDocs`
+
+The `__arm_out` keyword applies to prototyped function types and specifies
+that the function shares a given state S with its caller. For `__arm_out`,
+the function ignores the incoming state for S and returns new state for S.
+
+The attribute takes string arguments to instruct the compiler which state
+is shared. The supported states for S are:
+
+- `"za"` for Matrix Storage (requires SME)
+
+The attributes `__arm_in(S)`, `__arm_out(S)`, `__arm_inout(S)` and
+`__arm_preserves(S)` are all mutually exclusive for the same state S.
+
+
+### __arm_preserves
+
+{clang-attr-syntaxes}`ArmPreservesDocs`
+
+The `__arm_preserves` keyword applies to prototyped function types and
+specifies that the function does not read a given state S and returns
+with state S unchanged.
+
+The attribute takes string arguments to instruct the compiler which state
+is shared. The supported states for S are:
+
+- `"za"` for Matrix Storage (requires SME)
+
+The attributes `__arm_in(S)`, `__arm_out(S)`, `__arm_inout(S)` and
+`__arm_preserves(S)` are all mutually exclusive for the same state S.
+
+
+### __arm_streaming
+
+{clang-attr-syntaxes}`ArmSmeStreamingDocs`
+
+The `__arm_streaming` keyword applies to prototyped function types and specifies
+that the function has a "streaming interface". This means that:
+
+- the function requires that the processor implements the Scalable Matrix
+ Extension (SME).
+- the function must be entered in streaming mode (that is, with PSTATE.SM
+ set to 1)
+- the function must return in streaming mode
+
+Clang manages PSTATE.SM automatically; it is not the source code's
+responsibility to do this. For example, if a non-streaming
+function calls an `__arm_streaming` function, Clang generates code
+that switches into streaming mode before calling the function and
+switches back to non-streaming mode on return.
+
+
+### __arm_streaming_compatible
+
+{clang-attr-syntaxes}`ArmSmeStreamingCompatibleDocs`
+
+The `__arm_streaming_compatible` keyword applies to prototyped function types and
+specifies that the function has a "streaming compatible interface". This
+means that:
+
+- the function may be entered in either non-streaming mode (PSTATE.SM=0) or
+ in streaming mode (PSTATE.SM=1).
+- the function must return in the same mode as it was entered.
+- the code executed in the function is compatible with either mode.
+
+Clang manages PSTATE.SM automatically; it is not the source code's
+responsibility to do this. Clang will ensure that the generated code in
+streaming-compatible functions is valid in either mode (PSTATE.SM=0 or
+PSTATE.SM=1). For example, if an `__arm_streaming_compatible` function calls a
+non-streaming function, Clang generates code to temporarily switch out of streaming
+mode before calling the function and switch back to streaming-mode on return if
+`PSTATE.SM` is `1` on entry of the caller. If `PSTATE.SM` is `0` on
+entry to the `__arm_streaming_compatible` function, the call will be executed
+without changing modes.
+
+
diff --git a/clang/docs/AttributeReference/AMDGPUAttributes.md b/clang/docs/AttributeReference/AMDGPUAttributes.md
new file mode 100644
index 0000000000000..0943dc4d32ea7
--- /dev/null
+++ b/clang/docs/AttributeReference/AMDGPUAttributes.md
@@ -0,0 +1,166 @@
+## AMD GPU Attributes
+
+
+
+### amdgpu_av
+
+{clang-attr-syntaxes}`AMDGPUAvailableVisibleDocs`
+
+This attribute controls availability and visibility as described in the [AMDGPU
+Memory Model](https://llvm.org/docs/AMDGPUMemoryModel.html). When placed on
+an atomic expression or fence, the resulting atomic or fence instruction carries
+the corresponding *AV Metadata*.
+
+The attribute takes a string literal as an argument, which currently has only
+one supported value:
+
+- `"none"`: Disable MakeAvailable and MakeVisible semantics on release and
+ acquire operations respectively.
+
+```c++
+[[clang::amdgpu_av("none")]] __atomic_thread_fence(__ATOMIC_SEQ_CST);
+[[clang::amdgpu_av("none")]] __atomic_fetch_add(ptr, 1, __ATOMIC_ACQ_REL);
+
+// Also works with _Atomic type qualifier operations.
+_Atomic int *p;
+[[clang::amdgpu_av("none")]] *p += 1;
+```
+
+
+### amdgpu_flat_work_group_size
+
+{clang-attr-syntaxes}`AMDGPUFlatWorkGroupSizeDocs`
+
+The flat work-group size is the number of work-items in the work-group size
+specified when the kernel is dispatched. It is the product of the sizes of the
+x, y, and z dimension of the work-group.
+
+Clang supports the
+`__attribute__((amdgpu_flat_work_group_size(<min>, <max>)))` attribute for the
+AMDGPU target. This attribute may be attached to a kernel function definition
+and is an optimization hint.
+
+`<min>` parameter specifies the minimum flat work-group size, and `<max>`
+parameter specifies the maximum flat work-group size (must be greater than
+`<min>`) to which all dispatches of the kernel will conform. Passing `0, 0`
+as `<min>, <max>` implies the default behavior (`128, 256`).
+
+If specified, the AMDGPU target backend might be able to produce better machine
+code for barriers and perform scratch promotion by estimating available group
+segment size.
+
+An error will be given if:
+: - Specified values violate subtarget specifications;
+ - Specified values are not compatible with values provided through other
+ attributes.
+
+
+### amdgpu_max_num_work_groups
+
+{clang-attr-syntaxes}`AMDGPUMaxNumWorkGroupsDocs`
+
+This attribute specifies the max number of work groups when the kernel
+is dispatched.
+
+Clang supports the
+`__attribute__((amdgpu_max_num_work_groups(<x>, <y>, <z>)))` or
+`[[clang::amdgpu_max_num_work_groups(<x>, <y>, <z>)]]` attribute for the
+AMDGPU target. This attribute may be attached to HIP or OpenCL kernel function
+definitions and is an optimization hint.
+
+The `<x>` parameter specifies the maximum number of work groups in the x dimension.
+Similarly `<y>` and `<z>` are for the y and z dimensions respectively.
+Each of the three values must be greater than 0 when provided. The `<x>` parameter
+is required, while `<y>` and `<z>` are optional with default value of 1.
+
+If specified, the AMDGPU target backend might be able to produce better machine
+code.
+
+An error will be given if:
+: - Specified values violate subtarget specifications;
+ - Specified values are not compatible with values provided through other
+ attributes.
+
+
+### amdgpu_num_sgpr, amdgpu_num_vgpr
+
+{clang-attr-syntaxes}`AMDGPUNumSGPRNumVGPRDocs`
+
+:::{warning}
+These attributes are deprecated. Use the `amdgpu_waves_per_eu` attribute to
+control SGPR and VGPR usage instead.
+:::
+
+Clang supports the `__attribute__((amdgpu_num_sgpr(<num_sgpr>)))` and
+`__attribute__((amdgpu_num_vgpr(<num_vgpr>)))` attributes for the AMDGPU
+target. These attributes may be attached to a kernel function definition and are
+an optimization hint.
+
+If these attributes are specified, then the AMDGPU target backend will attempt
+to limit the number of SGPRs and/or VGPRs used to the specified value(s). The
+number of used SGPRs and/or VGPRs may further be rounded up to satisfy the
+allocation requirements or constraints of the subtarget. Passing `0` as
+`num_sgpr` and/or `num_vgpr` implies the default behavior (no limits).
+
+These attributes can be used to test the AMDGPU target backend. It is
+recommended that the `amdgpu_waves_per_eu` attribute be used to control
+resources such as SGPRs and VGPRs since it is aware of the limits for different
+subtargets.
+
+An error will be given if:
+: - Specified values violate subtarget specifications;
+ - Specified values are not compatible with values provided through other
+ attributes;
+ - The AMDGPU target backend is unable to create machine code that can meet the
+ request.
+
+
+### amdgpu_waves_per_eu
+
+{clang-attr-syntaxes}`AMDGPUWavesPerEUDocs`
+
+A compute unit (CU) is responsible for executing the wavefronts of a work-group.
+It is composed of one or more execution units (EU), which are responsible for
+executing the wavefronts. An EU can have enough resources to maintain the state
+of more than one executing wavefront. This allows an EU to hide latency by
+switching between wavefronts in a similar way to symmetric multithreading on a
+CPU. In order to allow the state for multiple wavefronts to fit on an EU, the
+resources used by a single wavefront have to be limited. For example, the number
+of SGPRs and VGPRs. Limiting such resources can allow greater latency hiding,
+but can result in having to spill some register state to memory.
+
+Clang supports the `__attribute__((amdgpu_waves_per_eu(<min>[, <max>])))`
+attribute for the AMDGPU target. This attribute may be attached to a kernel
+function definition and is an optimization hint.
+
+`<min>` parameter specifies the requested minimum number of waves per EU, and
+*optional* `<max>` parameter specifies the requested maximum number of waves
+per EU (must be greater than `<min>` if specified). If `<max>` is omitted,
+then there is no restriction on the maximum number of waves per EU other than
+the one dictated by the hardware for which the kernel is compiled. Passing
+`0, 0` as `<min>, <max>` implies the default behavior (no limits).
+
+If specified, this attribute allows an advanced developer to tune the number of
+wavefronts that are capable of fitting within the resources of an EU. The AMDGPU
+target backend can use this information to limit resources, such as number of
+SGPRs, number of VGPRs, size of available group and private memory segments, in
+such a way that guarantees that at least `<min>` wavefronts and at most
+`<max>` wavefronts are able to fit within the resources of an EU. Requesting
+more wavefronts can hide memory latency but limits available registers which
+can result in spilling. Requesting fewer wavefronts can help reduce cache
+thrashing, but can reduce memory latency hiding.
+
+This attribute controls the machine code generated by the AMDGPU target backend
+to ensure it is capable of meeting the requested values. However, when the
+kernel is executed, there may be other reasons that prevent meeting the request,
+for example, there may be wavefronts from other kernels executing on the EU.
+
+An error will be given if:
+: - Specified values violate subtarget specifications;
+ - Specified values are not compatible with values provided through other
+ attributes;
+
+The AMDGPU target backend will emit a warning whenever it is unable to
+create machine code that meets the request.
+
+
diff --git a/clang/docs/AttributeReference/CallingConventions.md b/clang/docs/AttributeReference/CallingConventions.md
new file mode 100644
index 0000000000000..fa4d32341d925
--- /dev/null
+++ b/clang/docs/AttributeReference/CallingConventions.md
@@ -0,0 +1,299 @@
+## Calling Conventions
+
+Clang supports several different calling conventions, depending on the target
+platform and architecture. The calling convention used for a function determines
+how parameters are passed, how results are returned to the caller, and other
+low-level details of calling a function.
+
+### aarch64_sve_pcs
+
+{clang-attr-syntaxes}`AArch64SVEPcsDocs`
+
+On AArch64 targets, this attribute changes the calling convention of a
+function to preserve additional Scalable Vector registers and Scalable
+Predicate registers relative to the default calling convention used for
+AArch64.
+
+This means it is more efficient to call such functions from code that performs
+extensive scalable vector and scalable predicate calculations, because fewer
+live SVE registers need to be saved. This property makes it well-suited for SVE
+math library functions, which are typically leaf functions that require a small
+number of registers.
+
+However, using this attribute also means that it is more expensive to call
+a function that adheres to the default calling convention from within such
+a function. Therefore, it is recommended that this attribute is only used
+for leaf functions.
+
+For more information, see the documentation for `aarch64_sve_pcs` in the
+ARM C Language Extension (ACLE) documentation.
+
+[aarch64_sve_pcs]: https://github.com/ARM-software/acle/blob/main/main/acle.md#scalable-vector-extension-procedure-call-standard-attribute
+
+
+### aarch64_vector_pcs
+
+{clang-attr-syntaxes}`AArch64VectorPcsDocs`
+
+On AArch64 targets, this attribute changes the calling convention of a
+function to preserve additional floating-point and Advanced SIMD registers
+relative to the default calling convention used for AArch64.
+
+This means it is more efficient to call such functions from code that performs
+extensive floating-point and vector calculations, because fewer live SIMD and FP
+registers need to be saved. This property makes it well-suited for e.g.
+floating-point or vector math library functions, which are typically leaf
+functions that require a small number of registers.
+
+However, using this attribute also means that it is more expensive to call
+a function that adheres to the default calling convention from within such
+a function. Therefore, it is recommended that this attribute is only used
+for leaf functions.
+
+For more information, see the documentation for [aarch64_vector_pcs][aarch64_vector_pcs] on
+the Arm Developer website.
+
+[aarch64_vector_pcs]: https://developer.arm.com/products/software-development-tools/hpc/arm-compiler-for-hpc/vector-function-abi
+
+
+### fastcall
+
+{clang-attr-syntaxes}`FastCallDocs`
+
+On 32-bit x86 targets, this attribute changes the calling convention of a
+function to use ECX and EDX as register parameters and clear parameters off of
+the stack on return. This convention does not support variadic calls or
+unprototyped functions in C, and has no effect on x86_64 targets. This calling
+convention is supported primarily for compatibility with existing code. Users
+seeking register parameters should use the `regparm` attribute, which does
+not require callee-cleanup. See the documentation for [`__fastcall`][__fastcall] on MSDN.
+
+[__fastcall]: http://msdn.microsoft.com/en-us/library/6xa169sk.aspx
+
+
+### m68k_rtd
+
+{clang-attr-syntaxes}`M68kRTDDocs`
+
+On M68k targets, this attribute changes the calling convention of a function
+to clear parameters off the stack on return. In other words, callee is
+responsible for cleaning out the stack space allocated for incoming paramters.
+This convention does not support variadic calls or unprototyped functions in C.
+When targeting M68010 or newer CPUs, this calling convention is implemented
+using the `rtd` instruction.
+
+
+### ms_abi
+
+{clang-attr-syntaxes}`MSABIDocs`
+
+On non-Windows x86_64 and aarch64 targets, this attribute changes the calling convention of
+a function to match the default convention used on Windows. This
+attribute has no effect on Windows targets or non-x86_64, non-aarch64 targets.
+
+
+### pcs
+
+{clang-attr-syntaxes}`PcsDocs`
+
+On ARM targets, this attribute can be used to select calling conventions
+similar to `stdcall` on x86. Valid parameter values are "aapcs" and
+"aapcs-vfp".
+
+
+### preserve_all
+
+{clang-attr-syntaxes}`PreserveAllDocs`
+
+On X86-64 and AArch64 targets, this attribute changes the calling convention of
+a function. The `preserve_all` calling convention attempts to make the code
+in the caller even less intrusive than the `preserve_most` calling convention.
+This calling convention also behaves identical to the `C` calling convention
+on how arguments and return values are passed, but it uses a different set of
+caller/callee-saved registers. This removes the burden of saving and
+recovering a large register set before and after the call in the caller. If
+the arguments are passed in callee-saved registers, then they will be
+preserved by the callee across the call. This doesn't apply for values
+returned in callee-saved registers.
+
+- On X86-64 the callee preserves all general purpose registers, except for
+ R11. R11 can be used as a scratch register. Furthermore it also preserves
+ all floating-point registers (XMMs/YMMs).
+- On AArch64 the callee preserve all general purpose registers, except X0-X8 and
+ X16-X18. Furthermore it also preserves lower 128 bits of V8-V31 SIMD - floating
+ point registers.
+
+The idea behind this convention is to support calls to runtime functions
+that don't need to call out to any other functions.
+
+This calling convention, like the `preserve_most` calling convention, will be
+used by a future version of the Objective-C runtime and should be considered
+experimental at this time.
+
+
+### preserve_most
+
+{clang-attr-syntaxes}`PreserveMostDocs`
+
+On X86-64 and AArch64 targets, this attribute changes the calling convention of
+a function. The `preserve_most` calling convention attempts to make the code
+in the caller as unintrusive as possible. This convention behaves identically
+to the `C` calling convention on how arguments and return values are passed,
+but it uses a different set of caller/callee-saved registers. This alleviates
+the burden of saving and recovering a large register set before and after the
+call in the caller. If the arguments are passed in callee-saved registers,
+then they will be preserved by the callee across the call. This doesn't
+apply for values returned in callee-saved registers.
+
+- On X86-64 the callee preserves all general purpose registers, except for
+ R11. R11 can be used as a scratch register. Floating-point registers
+ (XMMs/YMMs) are not preserved and need to be saved by the caller.
+- On AArch64 the callee preserve all general purpose registers, except X0-X8 and
+ X16-X18.
+
+The idea behind this convention is to support calls to runtime functions
+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
+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
+on the hot path and definitely executed a lot. Furthermore `preserve_most`
+doesn't prevent the inliner from inlining the function call.
+
+This convention was created to optimize certain runtime calls to the
+Objective-C runtime, but it is not limited to that runtime; it is also used by
+other runtimes and libraries, such as the Swift runtime and the Linux kernel.
+The current implementation only supports X86-64 and AArch64, but the intention
+is to support more architectures in the future.
+
+
+### preserve_none
+
+{clang-attr-syntaxes}`PreserveNoneDocs`
+
+On X86-64 and AArch64 targets, this attribute changes the calling convention of a function.
+The `preserve_none` calling convention tries to preserve as few general
+registers as possible. So all general registers are caller saved registers. It
+also uses more general registers to pass arguments. This attribute doesn't
+impact floating-point registers. `preserve_none`'s ABI is still unstable, and
+may be changed in the future.
+
+- On X86-64, only RSP and RBP are preserved by the callee.
+ Registers R12, R13, R14, R15, RDI, RSI, RDX, RCX, R8, R9, R11, and RAX now can
+ be used to pass function arguments. Floating-point registers (XMMs/YMMs) still
+ follow the C calling convention.
+- On AArch64, only LR and FP are preserved by the callee.
+ Registers X20-X28, X0-X7, and X9-X14 are used to pass function arguments.
+ X8, X16-X19, SIMD and floating-point registers follow the AAPCS calling
+ convention. X15 is not available for argument passing on Windows, but is
+ used to pass arguments on other platforms.
+
+
+### regcall
+
+{clang-attr-syntaxes}`RegCallDocs`
+
+On x86 targets, this attribute changes the calling convention to
+[`__regcall`][__regcall] convention. This convention aims to pass as many arguments
+as possible in registers. It also tries to utilize registers for the
+return value whenever it is possible.
+
+[__regcall]: https://www.intel.com/content/www/us/en/docs/dpcpp-cpp-compiler/developer-guide-reference/2023-2/c-c-sycl-calling-conventions.html
+
+
+### regparm
+
+{clang-attr-syntaxes}`RegparmDocs`
+
+On 32-bit x86 targets, the regparm attribute causes the compiler to pass
+the first three integer parameters in EAX, EDX, and ECX instead of on the
+stack. This attribute has no effect on variadic functions, and all parameters
+are passed via the stack as normal.
+
+
+### riscv::vector_cc, riscv_vector_cc, clang::riscv_vector_cc
+
+{clang-attr-syntaxes}`RISCVVectorCCDocs`
+
+The `riscv_vector_cc` attribute can be applied to a function. It preserves 15
+registers namely, v1-v7 and v24-v31 as callee-saved. Callers thus don't need
+to save these registers before function calls, and callees only need to save
+them if they use them.
+
+
+### riscv::vls_cc, riscv_vls_cc, clang::riscv_vls_cc
+
+{clang-attr-syntaxes}`RISCVVLSCCDocs`
+
+The `riscv_vls_cc` attribute can be applied to a function. Functions
+declared with this attribute will utilize the standard fixed-length vector
+calling convention variant instead of the default calling convention defined by
+the ABI. This variant aims to pass fixed-length vectors via vector registers,
+if possible, rather than through general-purpose registers.
+
+
+### stdcall
+
+{clang-attr-syntaxes}`StdCallDocs`
+
+On 32-bit x86 targets, this attribute changes the calling convention of a
+function to clear parameters off of the stack on return. This convention does
+not support variadic calls or unprototyped functions in C, and has no effect on
+x86_64 targets. This calling convention is used widely by the Windows API and
+COM applications. See the documentation for [`__stdcall`][__stdcall] on MSDN.
+
+[__stdcall]: http://msdn.microsoft.com/en-us/library/zxk0tw93.aspx
+
+
+### sysv_abi
+
+{clang-attr-syntaxes}`SysVABIDocs`
+
+On Windows x86_64 targets, this attribute changes the calling convention of a
+function to match the default convention used on Sys V targets such as Linux,
+Mac, and BSD. This attribute has no effect on other targets.
+
+
+### thiscall
+
+{clang-attr-syntaxes}`ThisCallDocs`
+
+On 32-bit x86 targets, this attribute changes the calling convention of a
+function to use ECX for the first parameter (typically the implicit `this`
+parameter of C++ methods) and clear parameters off of the stack on return. This
+convention does not support variadic calls or unprototyped functions in C, and
+has no effect on x86_64 targets. See the documentation for [`__thiscall`][__thiscall] on
+MSDN.
+
+[__thiscall]: http://msdn.microsoft.com/en-us/library/ek8tkfbw.aspx
+
+
+### vectorcall
+
+{clang-attr-syntaxes}`VectorCallDocs`
+
+On 32-bit x86 *and* x86_64 targets, this attribute changes the calling
+convention of a function to pass vector parameters in SSE registers.
+
+On 32-bit x86 targets, this calling convention is similar to `__fastcall`.
+The first two integer parameters are passed in ECX and EDX. Subsequent integer
+parameters are passed in memory, and callee clears the stack. On x86_64
+targets, the callee does *not* clear the stack, and integer parameters are
+passed in RCX, RDX, R8, and R9 as is done for the default Windows x64 calling
+convention.
+
+On both 32-bit x86 and x86_64 targets, vector and floating point arguments are
+passed in XMM0-XMM5. Homogeneous vector aggregates of up to four elements are
+passed in sequential SSE registers if enough are available. If AVX is enabled,
+256 bit vectors are passed in YMM0-YMM5. Any vector or aggregate type that
+cannot be passed in registers for any reason is passed by reference, which
+allows the caller to align the parameter memory.
+
+See the documentation for [`__vectorcall`][__vectorcall] on MSDN for more details.
+
+[__vectorcall]: http://msdn.microsoft.com/en-us/library/dn375768.aspx
+
+
diff --git a/clang/docs/AttributeReference/ConsumedAnnotationChecking.md b/clang/docs/AttributeReference/ConsumedAnnotationChecking.md
new file mode 100644
index 0000000000000..bf308f5d86a9c
--- /dev/null
+++ b/clang/docs/AttributeReference/ConsumedAnnotationChecking.md
@@ -0,0 +1,71 @@
+## Consumed Annotation Checking
+
+Clang supports additional attributes for checking basic resource management
+properties, specifically for unique objects that have a single owning reference.
+The following attributes are currently supported, although **the implementation
+for these annotations is currently in development and are subject to change.**
+
+### callable_when
+
+{clang-attr-syntaxes}`CallableWhenDocs`
+
+Use `__attribute__((callable_when(...)))` to indicate what states a method
+may be called in. Valid states are unconsumed, consumed, or unknown. Each
+argument to this attribute must be a quoted string. E.g.:
+
+`__attribute__((callable_when("unconsumed", "unknown")))`
+
+
+### consumable
+
+{clang-attr-syntaxes}`ConsumableDocs`
+
+Each `class` that uses any of the typestate annotations must first be marked
+using the `consumable` attribute. Failure to do so will result in a warning.
+
+This attribute accepts a single parameter that must be one of the following:
+`unknown`, `consumed`, or `unconsumed`.
+
+
+### param_typestate
+
+{clang-attr-syntaxes}`ParamTypestateDocs`
+
+This attribute specifies expectations about function parameters. Calls to an
+function with annotated parameters will issue a warning if the corresponding
+argument isn't in the expected state. The attribute is also used to set the
+initial state of the parameter when analyzing the function's body.
+
+
+### return_typestate
+
+{clang-attr-syntaxes}`ReturnTypestateDocs`
+
+The `return_typestate` attribute can be applied to functions or parameters.
+When applied to a function the attribute specifies the state of the returned
+value. The function's body is checked to ensure that it always returns a value
+in the specified state. On the caller side, values returned by the annotated
+function are initialized to the given state.
+
+When applied to a function parameter it modifies the state of an argument after
+a call to the function returns. The function's body is checked to ensure that
+the parameter is in the expected state before returning.
+
+
+### set_typestate
+
+{clang-attr-syntaxes}`SetTypestateDocs`
+
+Annotate methods that transition an object into a new state with
+`__attribute__((set_typestate(new_state)))`. The new state must be
+unconsumed, consumed, or unknown.
+
+
+### test_typestate
+
+{clang-attr-syntaxes}`TestTypestateDocs`
+
+Use `__attribute__((test_typestate(tested_state)))` to indicate that a method
+returns true if the object is in the specified state..
+
+
diff --git a/clang/docs/AttributeReference/CustomizingSwiftImport.md b/clang/docs/AttributeReference/CustomizingSwiftImport.md
new file mode 100644
index 0000000000000..e79950599db2b
--- /dev/null
+++ b/clang/docs/AttributeReference/CustomizingSwiftImport.md
@@ -0,0 +1,253 @@
+## Customizing Swift Import
+
+Clang supports additional attributes for customizing how APIs are imported into
+Swift.
+
+### swift_async
+
+{clang-attr-syntaxes}`SwiftAsyncDocs`
+
+The `swift_async` attribute specifies if and how a particular function or
+Objective-C method is imported into a swift async method. For instance:
+
+```objc
+ at interface MyClass : NSObject
+-(void)notActuallyAsync:(int)p1 withCompletionHandler:(void (^)())handler
+ __attribute__((swift_async(none)));
+
+-(void)actuallyAsync:(int)p1 callThisAsync:(void (^)())fun
+ __attribute__((swift_async(swift_private, 1)));
+ at end
+```
+
+Here, `notActuallyAsync:withCompletionHandler` would have been imported as
+`async` (because it's last parameter's selector piece is
+`withCompletionHandler`) if not for the `swift_async(none)` attribute.
+Conversely, `actuallyAsync:callThisAsync` wouldn't have been imported as
+`async` if not for the `swift_async` attribute because it doesn't match the
+naming convention.
+
+When using `swift_async` to enable importing, the first argument to the
+attribute is either `swift_private` or `not_swift_private` to indicate
+whether the function/method is private to the current framework, and the second
+argument is the index of the completion handler parameter.
+
+
+### swift_async_error
+
+{clang-attr-syntaxes}`SwiftAsyncErrorDocs`
+
+The `swift_async_error` attribute specifies how an error state will be
+represented in a swift async method. It's a bit analogous to the `swift_error`
+attribute for the generated async method. The `swift_async_error` attribute
+can indicate a variety of different ways of representing an error.
+
+- `__attribute__((swift_async_error(zero_argument, N)))`, specifies that the
+ async method is considered to have failed if the Nth argument to the
+ completion handler is zero.
+- `__attribute__((swift_async_error(nonzero_argument, N)))`, specifies that
+ the async method is considered to have failed if the Nth argument to the
+ completion handler is non-zero.
+- `__attribute__((swift_async_error(nonnull_error)))`, specifies that the
+ async method is considered to have failed if the `NSError *` argument to the
+ completion handler is non-null.
+- `__attribute__((swift_async_error(none)))`, specifies that the async method
+ cannot fail.
+
+For instance:
+
+```objc
+ at interface MyClass : NSObject
+-(void)asyncMethod:(void (^)(char, int, float))handler
+ __attribute__((swift_async(swift_private, 1)))
+ __attribute__((swift_async_error(zero_argument, 2)));
+ at end
+```
+
+Here, the `swift_async` attribute specifies that `handler` is the completion
+handler for this method, and the `swift_async_error` attribute specifies that
+the `int` parameter is the one that represents the error.
+
+
+### swift_async_name
+
+{clang-attr-syntaxes}`SwiftAsyncNameDocs`
+
+The `swift_async_name` attribute provides the name of the `async` overload for
+the given declaration in Swift. If this attribute is absent, the name is
+transformed according to the algorithm built into the Swift compiler.
+
+The argument is a string literal that contains the Swift name of the function or
+method. The name may be a compound Swift name. The function or method with such
+an attribute must have more than zero parameters, as its last parameter is
+assumed to be a callback that's eliminated in the Swift `async` name.
+
+```objc
+ at interface URL
++ (void) loadContentsFrom:(URL *)url callback:(void (^)(NSData *))data __attribute__((__swift_async_name__("URL.loadContentsFrom(_:)")))
+ at end
+```
+
+
+### swift_attr
+
+{clang-attr-syntaxes}`SwiftAttrDocs`
+
+The `swift_attr` provides a Swift-specific annotation for the declaration
+or type to which the attribute appertains to. It can be used on any declaration
+or type in Clang. This kind of annotation is ignored by Clang as it doesn't have any
+semantic meaning in languages supported by Clang. The Swift compiler can
+interpret these annotations according to its own rules when importing C or
+Objective-C declarations.
+
+
+### swift_bridge
+
+{clang-attr-syntaxes}`SwiftBridgeDocs`
+
+The `swift_bridge` attribute indicates that the declaration to which the
+attribute appertains is bridged to the named Swift type.
+
+```objc
+__attribute__((__objc_root__))
+ at interface Base
+- (instancetype)init;
+ at end
+
+__attribute__((__swift_bridge__("BridgedI")))
+ at interface I : Base
+ at end
+```
+
+In this example, the Objective-C interface `I` will be made available to Swift
+with the name `BridgedI`. It would be possible for the compiler to refer to
+`I` still in order to bridge the type back to Objective-C.
+
+
+### swift_bridged
+
+{clang-attr-syntaxes}`SwiftBridgedTypedefDocs`
+
+The `swift_bridged_typedef` attribute indicates that when the typedef to which
+the attribute appertains is imported into Swift, it should refer to the bridged
+Swift type (e.g. Swift's `String`) rather than the Objective-C type as written
+(e.g. `NSString`).
+
+```objc
+ at interface NSString;
+typedef NSString *AliasedString __attribute__((__swift_bridged_typedef__));
+
+extern void acceptsAliasedString(AliasedString _Nonnull parameter);
+```
+
+In this case, the function `acceptsAliasedString` will be imported into Swift
+as a function which accepts a `String` type parameter.
+
+
+### swift_error
+
+{clang-attr-syntaxes}`SwiftErrorDocs`
+
+The `swift_error` attribute controls whether a particular function (or
+Objective-C method) is imported into Swift as a throwing function, and if so,
+which dynamic convention it uses.
+
+All of these conventions except `none` require the function to have an error
+parameter. Currently, the error parameter is always the last parameter of type
+`NSError**` or `CFErrorRef*`. Swift will remove the error parameter from
+the imported API. When calling the API, Swift will always pass a valid address
+initialized to a null pointer.
+
+- `swift_error(none)` means that the function should not be imported as
+ throwing. The error parameter and result type will be imported normally.
+- `swift_error(null_result)` means that calls to the function should be
+ considered to have thrown if they return a null value. The return type must be
+ a pointer type, and it will be imported into Swift with a non-optional type.
+ This is the default error convention for Objective-C methods that return
+ pointers.
+- `swift_error(zero_result)` means that calls to the function should be
+ considered to have thrown if they return a zero result. The return type must be
+ an integral type. If the return type would have been imported as `Bool`, it
+ is instead imported as `Void`. This is the default error convention for
+ Objective-C methods that return a type that would be imported as `Bool`.
+- `swift_error(nonzero_result)` means that calls to the function should be
+ considered to have thrown if they return a non-zero result. The return type must
+ be an integral type. If the return type would have been imported as `Bool`,
+ it is instead imported as `Void`.
+- `swift_error(nonnull_error)` means that calls to the function should be
+ considered to have thrown if they leave a non-null error in the error parameter.
+ The return type is left unmodified.
+
+
+### swift_name
+
+{clang-attr-syntaxes}`SwiftNameDocs`
+
+The `swift_name` attribute provides the name of the declaration in Swift. If
+this attribute is absent, the name is transformed according to the algorithm
+built into the Swift compiler.
+
+The argument is a string literal that contains the Swift name of the function,
+variable, or type. When renaming a function, the name may be a compound Swift
+name. For a type, enum constant, property, or variable declaration, the name
+must be a simple or qualified identifier.
+
+```objc
+ at interface URL
+- (void) initWithString:(NSString *)s __attribute__((__swift_name__("URL.init(_:)")))
+ at end
+
+void __attribute__((__swift_name__("squareRoot()"))) sqrt(double v) {
+}
+```
+
+
+### swift_newtype
+
+{clang-attr-syntaxes}`SwiftNewTypeDocs`
+
+The `swift_newtype` attribute indicates that the typedef to which the
+attribute appertains is imported as a new Swift type of the typedef's name.
+Previously, the attribute was spelt `swift_wrapper`. While the behaviour of
+the attribute is identical with either spelling, `swift_wrapper` is
+deprecated, only exists for compatibility purposes, and should not be used in
+new code.
+
+- `swift_newtype(struct)` means that a Swift struct will be created for this
+ typedef.
+
+- `swift_newtype(enum)` means that a Swift enum will be created for this
+ typedef.
+
+ ```c
+ // Import UIFontTextStyle as an enum type, with enumerated values being
+ // constants.
+ typedef NSString * UIFontTextStyle __attribute__((__swift_newtype__(enum)));
+
+ // Import UIFontDescriptorFeatureKey as a structure type, with enumerated
+ // values being members of the type structure.
+ typedef NSString * UIFontDescriptorFeatureKey __attribute__((__swift_newtype__(struct)));
+ ```
+
+
+### swift_objc_members
+
+{clang-attr-syntaxes}`SwiftObjCMembersDocs`
+
+This attribute indicates that Swift subclasses and members of Swift extensions
+of this class will be implicitly marked with the `@objcMembers` Swift
+attribute, exposing them back to Objective-C.
+
+
+### swift_private
+
+{clang-attr-syntaxes}`SwiftPrivateDocs`
+
+Declarations marked with the `swift_private` attribute are hidden from the
+framework client but are still made available for use within the framework or
+Swift SDK overlay.
+
+The purpose of this attribute is to permit a more idomatic implementation of
+declarations in Swift while hiding the non-idiomatic one.
+
+
diff --git a/clang/docs/AttributeReference/DeclarationAttributes.md b/clang/docs/AttributeReference/DeclarationAttributes.md
new file mode 100644
index 0000000000000..0db7581182e41
--- /dev/null
+++ b/clang/docs/AttributeReference/DeclarationAttributes.md
@@ -0,0 +1,1287 @@
+## Declaration Attributes
+
+
+
+### Owner
+
+{clang-attr-syntaxes}`LifetimeOwnerDocs`
+
+:::{Note}
+This attribute is experimental and its effect on analysis is subject to change in
+a future version of clang.
+:::
+
+The attribute `[[gsl::Owner(T)]]` applies to structs and classes that own an
+object of type `T`:
+
+```
+class [[gsl::Owner(int)]] IntOwner {
+private:
+ int value;
+public:
+ int *getInt() { return &value; }
+};
+```
+
+The argument `T` is optional and is ignored.
+This attribute may be used by analysis tools and has no effect on code
+generation. A `void` argument means that the class can own any type.
+
+See [Pointer](#pointer) for an example.
+
+
+### Pointer
+
+{clang-attr-syntaxes}`LifetimePointerDocs`
+
+:::{Note}
+This attribute is experimental and its effect on analysis is subject to change in
+a future version of clang.
+:::
+
+The attribute `[[gsl::Pointer(T)]]` applies to structs and classes that behave
+like pointers to an object of type `T`:
+
+```
+class [[gsl::Pointer(int)]] IntPointer {
+private:
+ int *valuePointer;
+public:
+ IntPointer(const IntOwner&);
+ int *getInt() { return valuePointer; }
+};
+```
+
+The argument `T` is optional and is ignored.
+This attribute may be used by analysis tools and has no effect on code
+generation. A `void` argument means that the pointer can point to any type.
+
+Example:
+When constructing an instance of a class annotated like this (a Pointer) from
+an instance of a class annotated with `[[gsl::Owner]]` (an Owner),
+then the analysis will consider the Pointer to point inside the Owner.
+When the Owner's lifetime ends, it will consider the Pointer to be dangling.
+
+```c++
+int f() {
+ IntPointer P(IntOwner{}); // P "points into" a temporary IntOwner object
+ P.getInt(); // P is dangling
+}
+```
+
+**Transparent Member Functions**
+
+The analysis automatically tracks certain member functions of `[[gsl::Pointer]]` types
+that provide transparent access to the pointed-to object. These include:
+
+- Dereference operators: `operator*`, `operator->`
+- Data access methods: `data()`, `c_str()`, `get()`
+- Iterator operations: `begin()`, `end()`, `rbegin()`, `rend()`, `cbegin()`, `cend()`, `crbegin()`, `crend()`, `operator+`, `operator-`, `operator++`, `operator--`
+
+When these methods return pointers, view types, or references, the analysis treats them as
+transparently borrowing from the same object that the pointer itself borrows from,
+enabling detection of use-after-free through these access patterns:
+
+```c++
+// For example, .data() here returns a borrow to 's' instead of 'v'.
+const char* f() {
+ std::string s = "hello";
+ std::string_view v = s; // warning: address of stack memory returned
+ return v.data(); // note: returned here
+}
+
+const MyObj& g(MyObj obj) {
+ View v = obj; // warning: address of stack memory returned
+ return *v; // note: returned here
+}
+```
+
+This tracking also applies to range-based for loops, where the `begin()` and `end()`
+iterators are used to access elements:
+
+```c++
+std::string_view f(std::vector<std::string> vec) {
+ for (const std::string& s : vec) { // warning: address of stack memory returned
+ return s; // note: returned here
+ }
+}
+```
+
+**Container Template Specialization**
+
+If a template class is annotated with `[[gsl::Owner]]`, and the first
+instantiated template argument is a pointer type (raw pointer, or `[[gsl::Pointer]]`),
+the analysis will consider the instantiated class as a container of the pointer.
+When constructing such an object from a GSL owner object, the analysis will
+assume that the container holds a pointer to the owner object. Consequently,
+when the owner object is destroyed, the pointer will be considered dangling.
+
+```c++
+int f() {
+ std::vector<std::string_view> v = {std::string()}; // v holds a dangling pointer.
+ std::optional<std::string_view> o = std::string(); // o holds a dangling pointer.
+}
+```
+
+
+### __single_inheritance, __multiple_inheritance, __virtual_inheritance
+
+{clang-attr-syntaxes}`MSInheritanceDocs`
+
+This collection of keywords is enabled under `-fms-extensions` and controls
+the pointer-to-member representation used on `*-*-win32` targets.
+
+The `*-*-win32` targets utilize a pointer-to-member representation which
+varies in size and alignment depending on the definition of the underlying
+class.
+
+However, this is problematic when a forward declaration is only available and
+no definition has been made yet. In such cases, Clang is forced to utilize the
+most general representation that is available to it.
+
+These keywords make it possible to use a pointer-to-member representation other
+than the most general one regardless of whether or not the definition will ever
+be present in the current translation unit.
+
+This family of keywords belong between the `class-key` and `class-name`:
+
+```c++
+struct __single_inheritance S;
+int S::*i;
+struct S {};
+```
+
+This keyword can be applied to class templates but only has an effect when used
+on full specializations:
+
+```c++
+template <typename T, typename U> struct __single_inheritance A; // warning: inheritance model ignored on primary template
+template <typename T> struct __multiple_inheritance A<T, T>; // warning: inheritance model ignored on partial specialization
+template <> struct __single_inheritance A<int, float>;
+```
+
+Note that choosing an inheritance model less general than strictly necessary is
+an error:
+
+```c++
+struct __multiple_inheritance S; // error: inheritance model does not match definition
+int S::*i;
+struct S {};
+```
+
+
+### annotate
+
+{clang-attr-syntaxes}`AnnotateDocs`
+
+The `annotate` attribute is used to add annotations to declarations or statements,
+typically for use by static analysis tools that are not integrated into the
+core Clang compiler (e.g., Clang-Tidy checks or out-of-tree Clang-based tools).
+It is a counterpart to the `annotate_type` attribute, which serves the same
+purpose, but for types.
+
+The attribute takes a mandatory string literal argument specifying the
+annotation category and an arbitrary number of optional arguments that provide
+additional information specific to the annotation category. The optional
+arguments must be constant expressions of arbitrary type.
+
+For example:
+
+```c++
+[[clang::annotate("category1", "foo", 1)]] void func(int val [[clang::annotate("category2")]]) {
+ [[clang::annotate("category3")]] if (val) {
+
+ }
+}
+```
+
+
+### asm
+
+{clang-attr-syntaxes}`AsmLabelDocs`
+
+This attribute can be used on a function or variable to specify its symbol name.
+
+On some targets, all C symbols are prefixed by default with a single character,
+typically `_`. This was done historically to distinguish them from symbols
+used by other languages. (This prefix is also added to the standard Itanium
+C++ ABI prefix on "mangled" symbol names, so that e.g. on such targets the true
+symbol name for a C++ variable declared as `int cppvar;` would be
+`__Z6cppvar`; note the two underscores.) This prefix is *not* added to the
+symbol names specified by the `__asm` attribute; programmers wishing to match
+a C symbol name must compensate for this.
+
+For example, consider the following C code:
+
+```c
+int var1 __asm("altvar") = 1; // "altvar" in symbol table.
+int var2 = 1; // "_var2" in symbol table.
+
+void func1(void) __asm("altfunc");
+void func1(void) {} // "altfunc" in symbol table.
+void func2(void) {} // "_func2" in symbol table.
+```
+
+Clang's implementation of this attribute is compatible with GCC's, [documented here](https://gcc.gnu.org/onlinedocs/gcc/Asm-Labels.html).
+
+While it is possible to use this attribute to name a special symbol used
+internally by the compiler, such as an LLVM intrinsic, this is neither
+recommended nor supported and may cause the compiler to crash or miscompile.
+Users who wish to gain access to intrinsic behavior are strongly encouraged to
+request new builtin functions.
+
+
+### cluster_dims
+
+{clang-attr-syntaxes}`CUDAClusterDimsAttrDoc`
+
+In CUDA/HIP programming, the `cluster_dims` attribute, conventionally exposed as the
+`__cluster_dims__` macro, can be applied to a kernel function to set the dimensions of a
+thread block cluster, which is an optional level of hierarchy and made up of thread blocks.
+`__cluster_dims__` defines the cluster size as `(X, Y, Z)`, where each value is the number
+of thread blocks in that dimension. The `cluster_dims` and `no_cluster` attributes are
+mutually exclusive.
+
+```
+__global__ __cluster_dims__(2, 1, 1) void kernel(...) {
+ ...
+}
+```
+
+
+### coro_await_elidable
+
+{clang-attr-syntaxes}`CoroAwaitElidableDoc`
+
+The `[[clang::coro_await_elidable]]` is a class attribute which can be
+applied to a coroutine return type. It provides a hint to the compiler to apply
+Heap Allocation Elision more aggressively.
+
+When a coroutine function returns such a type, a direct call expression therein
+that returns a prvalue of a type attributed `[[clang::coro_await_elidable]]`
+is said to be under a safe elide context if one of the following is true:
+
+- it is the immediate right-hand side operand to a co_await expression.
+- it is an argument to a `[[clang::coro_await_elidable_argument]]` parameter
+ or parameter pack of another direct call expression under a safe elide context.
+
+Do note that the safe elide context applies only to the call expression itself,
+and the context does not transitively include any of its subexpressions unless
+exceptional rules of `[[clang::coro_await_elidable_argument]]` apply.
+
+The compiler performs heap allocation elision on call expressions under a safe
+elide context, if the callee is a coroutine.
+
+Example:
+
+```c++
+class [[clang::coro_await_elidable]] Task { ... };
+
+Task foo();
+Task bar() {
+ co_await foo(); // foo()'s coroutine frame on this line is elidable
+ auto t = foo(); // foo()'s coroutine frame on this line is NOT elidable
+ co_await t;
+}
+```
+
+Such elision replaces the heap allocated activation frame of the callee coroutine
+with a local variable within the enclosing braces in the caller's stack frame.
+The local variable, like other variables in coroutines, may be collected into the
+coroutine frame, which may be allocated on the heap. The behavior is undefined
+if the caller coroutine is destroyed earlier than the callee coroutine.
+
+
+### coro_await_elidable_argument
+
+{clang-attr-syntaxes}`CoroAwaitElidableArgumentDoc`
+
+The `[[clang::coro_await_elidable_argument]]` is a function parameter attribute.
+It works in conjunction with `[[clang::coro_await_elidable]]` to propagate a
+safe elide context to a parameter or parameter pack if the function is called
+under a safe elide context.
+
+This is sometimes necessary on utility functions used to compose or modify the
+behavior of a callee coroutine.
+
+Example:
+
+```c++
+template <typename T>
+class [[clang::coro_await_elidable]] Task { ... };
+
+template <typename... T>
+class [[clang::coro_await_elidable]] WhenAll { ... };
+
+// `when_all` is a utility function that composes coroutines. It does not
+// need to be a coroutine to propagate.
+template <typename... T>
+WhenAll<T...> when_all([[clang::coro_await_elidable_argument]] Task<T> tasks...);
+
+Task<int> foo();
+Task<int> bar();
+Task<void> example1() {
+ // `when_all`, `foo`, and `bar` are all elide safe because `when_all` is
+ // under a safe elide context and, thanks to the [[clang::coro_await_elidable_argument]]
+ // attribute, such context is propagated to foo and bar.
+ co_await when_all(foo(), bar());
+}
+
+Task<void> example2() {
+ // `when_all` and `bar` are elide safe. `foo` is not elide safe.
+ auto f = foo();
+ co_await when_all(f, bar());
+}
+
+
+Task<void> example3() {
+ // None of the calls are elide safe.
+ auto t = when_all(foo(), bar());
+ co_await t;
+}
+```
+
+
+### coro_disable_lifetimebound, coro_lifetimebound
+
+{clang-attr-syntaxes}`CoroLifetimeBoundDoc`
+
+The `[[clang::coro_lifetimebound]]` is a class attribute which can be applied
+to a coroutine return type ([coro_return_type, coro_wrapper]) (i.e.
+it should also be annotated with `[[clang::coro_return_type]]`).
+
+All parameters of a function are considered to be lifetime bound if the function returns a
+coroutine return type (CRT) annotated with `[[clang::coro_lifetimebound]]`.
+This lifetime bound analysis can be disabled for a coroutine wrapper or a coroutine by annotating the function
+with `[[clang::coro_disable_lifetimebound]]` function attribute .
+See documentation of [lifetimebound] for details about lifetime bound analysis.
+
+Reference parameters of a coroutine are susceptible to capturing references to temporaries or local variables.
+
+For example,
+
+```c++
+task<int> coro(const int& a) { co_return a + 1; }
+task<int> dangling_refs(int a) {
+ // `coro` captures reference to a temporary. `foo` would now contain a dangling reference to `a`.
+ auto foo = coro(1);
+ // `coro` captures reference to local variable `a` which is destroyed after the return.
+ return coro(a);
+}
+```
+
+Lifetime bound static analysis can be used to detect such instances when coroutines capture references
+which may die earlier than the coroutine frame itself. In the above example, if the CRT `task` is annotated with
+`[[clang::coro_lifetimebound]]`, then lifetime bound analysis would detect capturing reference to
+temporaries or return address of a local variable.
+
+Both coroutines and coroutine wrappers are part of this analysis.
+
+```c++
+template <typename T> struct [[clang::coro_return_type, clang::coro_lifetimebound]] Task {
+ using promise_type = some_promise_type;
+};
+
+Task<int> coro(const int& a) { co_return a + 1; }
+[[clang::coro_wrapper]] Task<int> coro_wrapper(const int& a, const int& b) {
+ return a > b ? coro(a) : coro(b);
+}
+Task<int> temporary_reference() {
+ auto foo = coro(1); // warning: capturing reference to a temporary which would die after the expression.
+
+ int a = 1;
+ auto bar = coro_wrapper(a, 0); // warning: `b` captures reference to a temporary.
+
+ co_return co_await coro(1); // fine.
+}
+[[clang::coro_wrapper]] Task<int> stack_reference(int a) {
+ return coro(a); // warning: returning address of stack variable `a`.
+}
+```
+
+This analysis can be disabled for all calls to a particular function by annotating the function
+with function attribute `[[clang::coro_disable_lifetimebound]]`.
+For example, this could be useful for coroutine wrappers which accept reference parameters
+but do not pass them to the underlying coroutine or pass them by value.
+
+```c++
+Task<int> coro(int a) { co_return a + 1; }
+[[clang::coro_wrapper, clang::coro_disable_lifetimebound]] Task<int> coro_wrapper(const int& a) {
+ return coro(a + 1);
+}
+void use() {
+ auto task = coro_wrapper(1); // use of temporary is fine as the argument is not lifetime bound.
+}
+```
+
+
+### coro_only_destroy_when_complete
+
+{clang-attr-syntaxes}`CoroOnlyDestroyWhenCompleteDocs`
+
+The `coro_only_destroy_when_complete` attribute should be marked on a C++ class. The coroutines
+whose return type is marked with the attribute are assumed to be destroyed only after the coroutine has
+reached the final suspend point.
+
+This is helpful for the optimizers to reduce the size of the destroy function for the coroutines.
+
+For example,
+
+```c++
+A foo() {
+ dtor d;
+ co_await something();
+ dtor d1;
+ co_await something();
+ dtor d2;
+ co_return 43;
+}
+```
+
+The compiler may generate the following pseudocode:
+
+```c++
+void foo.destroy(foo.Frame *frame) {
+ switch(frame->suspend_index()) {
+ case 1:
+ frame->d.~dtor();
+ break;
+ case 2:
+ frame->d.~dtor();
+ frame->d1.~dtor();
+ break;
+ case 3:
+ frame->d.~dtor();
+ frame->d1.~dtor();
+ frame->d2.~dtor();
+ break;
+ default: // coroutine completed or haven't started
+ break;
+ }
+
+ frame->promise.~promise_type();
+ delete frame;
+}
+```
+
+The `foo.destroy()` function's purpose is to release all of the resources
+initialized for the coroutine when it is destroyed in a suspended state.
+However, if the coroutine is only ever destroyed at the final suspend state,
+the rest of the conditions are superfluous.
+
+The user can use the `coro_only_destroy_when_complete` attributo suppress
+generation of the other destruction cases, optimizing the above `foo.destroy` to:
+
+```c++
+void foo.destroy(foo.Frame *frame) {
+ frame->promise.~promise_type();
+ delete frame;
+}
+```
+
+
+### coro_return_type, coro_wrapper
+
+{clang-attr-syntaxes}`CoroReturnTypeAndWrapperDoc`
+
+The `[[clang::coro_return_type]]` attribute is used to help static analyzers to recognize
+coroutines from the function signatures.
+
+The `coro_return_type` attribute should be marked on a C++ class to mark it as
+a **coroutine return type (CRT)**.
+
+A function `R func(P1, .., PN)` has a coroutine return type (CRT) `R` if `R`
+is marked by `[[clang::coro_return_type]]` and `R` has a promise type associated to it
+(i.e., `std::coroutine_traits<R, P1, .., PN>::promise_type` is a valid promise type).
+
+If the return type of a function is a `CRT` then the function must be a coroutine.
+Otherwise the program is invalid. It is allowed for a non-coroutine to return a `CRT`
+if the function is marked with `[[clang::coro_wrapper]]`.
+
+The `[[clang::coro_wrapper]]` attribute should be marked on a C++ function to mark it as
+a **coroutine wrapper**. A coroutine wrapper is a function which returns a `CRT`,
+is not a coroutine itself and is marked with `[[clang::coro_wrapper]]`.
+
+Clang will enforce that all functions that return a `CRT` are either coroutines or marked
+with `[[clang::coro_wrapper]]`. Clang will enforce this with an error.
+
+From a language perspective, it is not possible to differentiate between a coroutine and a
+function returning a CRT by merely looking at the function signature.
+
+Coroutine wrappers, in particular, are susceptible to capturing
+references to temporaries and other lifetime issues. This allows to avoid such lifetime
+issues with coroutine wrappers.
+
+For example,
+
+```c++
+// This is a CRT.
+template <typename T> struct [[clang::coro_return_type]] Task {
+ using promise_type = some_promise_type;
+};
+
+Task<int> increment(int a) { co_return a + 1; } // Fine. This is a coroutine.
+Task<int> foo() { return increment(1); } // Error. foo is not a coroutine.
+
+// Fine for a coroutine wrapper to return a CRT.
+[[clang::coro_wrapper]] Task<int> foo() { return increment(1); }
+
+void bar() {
+ // Invalid. This intantiates a function which returns a CRT but is not marked as
+ // a coroutine wrapper.
+ std::function<Task<int>(int)> f = increment;
+}
+```
+
+Note: `a_promise_type::get_return_object` is exempted from this analysis as it is a necessary
+implementation detail of any coroutine library.
+
+
+### deprecated
+
+{clang-attr-syntaxes}`DeprecatedDocs`
+
+The `deprecated` attribute can be applied to a function, a variable, or a
+type. This is useful when identifying functions, variables, or types that are
+expected to be removed in a future version of a program.
+
+Consider the function declaration for a hypothetical function `f`:
+
+```c++
+void f(void) __attribute__((deprecated("message", "replacement")));
+```
+
+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
+string argument which is the message to display when emitting the warning.
+
+
+### empty_bases
+
+{clang-attr-syntaxes}`EmptyBasesDocs`
+
+The empty_bases attribute permits the compiler to utilize the
+empty-base-optimization more frequently.
+This attribute only applies to struct, class, and union types.
+It is only supported when using the Microsoft C++ ABI.
+
+
+### enum_extensibility
+
+{clang-attr-syntaxes}`EnumExtensibilityDocs`
+
+Attribute `enum_extensibility` is used to distinguish between enum definitions
+that are extensible and those that are not. The attribute can take either
+`closed` or `open` as an argument. `closed` indicates a variable of the
+enum type takes a value that corresponds to one of the enumerators listed in the
+enum definition or, when the enum is annotated with `flag_enum`, a value that
+can be constructed using values corresponding to the enumerators. `open`
+indicates a variable of the enum type can take any values allowed by the
+standard and instructs clang to be more lenient when issuing warnings.
+
+```c
+enum __attribute__((enum_extensibility(closed))) ClosedEnum {
+ A0, A1
+};
+
+enum __attribute__((enum_extensibility(open))) OpenEnum {
+ B0, B1
+};
+
+enum __attribute__((enum_extensibility(closed),flag_enum)) ClosedFlagEnum {
+ C0 = 1 << 0, C1 = 1 << 1
+};
+
+enum __attribute__((enum_extensibility(open),flag_enum)) OpenFlagEnum {
+ D0 = 1 << 0, D1 = 1 << 1
+};
+
+void foo1() {
+ enum ClosedEnum ce;
+ enum OpenEnum oe;
+ enum ClosedFlagEnum cfe;
+ enum OpenFlagEnum ofe;
+
+ ce = A1; // no warnings
+ ce = 100; // warning issued
+ oe = B1; // no warnings
+ oe = 100; // no warnings
+ cfe = C0 | C1; // no warnings
+ cfe = C0 | C1 | 4; // warning issued
+ ofe = D0 | D1; // no warnings
+ ofe = D0 | D1 | 4; // no warnings
+}
+```
+
+
+### external_source_symbol
+
+{clang-attr-syntaxes}`ExternalSourceSymbolDocs`
+
+The `external_source_symbol` attribute specifies that a declaration originates
+from an external source and describes the nature of that source.
+
+The fact that Clang is capable of recognizing declarations that were defined
+externally can be used to provide better tooling support for mixed-language
+projects or projects that rely on auto-generated code. For instance, an IDE that
+uses Clang and that supports mixed-language projects can use this attribute to
+provide a correct "jump-to-definition" feature. For a concrete example,
+consider a protocol that's defined in a Swift file:
+
+```swift
+ at objc public protocol SwiftProtocol {
+ func method()
+}
+```
+
+This protocol can be used from Objective-C code by including a header file that
+was generated by the Swift compiler. The declarations in that header can use
+the `external_source_symbol` attribute to make Clang aware of the fact
+that `SwiftProtocol` actually originates from a Swift module:
+
+```objc
+__attribute__((external_source_symbol(language="Swift",defined_in="module")))
+ at protocol SwiftProtocol
+ at required
+- (void) method;
+ at end
+```
+
+Consequently, when "jump-to-definition" is performed at a location that
+references `SwiftProtocol`, the IDE can jump to the original definition in
+the Swift source file rather than jumping to the Objective-C declaration in the
+auto-generated header file.
+
+The `external_source_symbol` attribute is a comma-separated list that includes
+clauses that describe the origin and the nature of the particular declaration.
+Those clauses can be:
+
+language=*string-literal*
+
+: The name of the source language in which this declaration was defined.
+
+defined_in=*string-literal*
+
+: The name of the source container in which the declaration was defined. The
+ exact definition of source container is language-specific, e.g. Swift's
+ source containers are modules, so `defined_in` should specify the Swift
+ module name.
+
+USR=*string-literal*
+
+: String that specifies a unified symbol resolution (USR) value for this
+ declaration. USR string uniquely identifies this particular declaration, and
+ is typically used when constructing an index of a codebase.
+ The USR value in this attribute is expected to be generated by an external
+ compiler that compiled the native declaration using its original source
+ language. The exact format of the USR string and its other attributes
+ are determined by the specification of this declaration's source language.
+ When not specified, Clang's indexer will use the Clang USR for this symbol.
+ User can query to see if Clang supports the use of the `USR` clause in
+ the `external_source_symbol` attribute with
+ `__has_attribute(external_source_symbol) >= 20230206`.
+
+generated_declaration
+
+: This declaration was automatically generated by some tool.
+
+The clauses can be specified in any order. The clauses that are listed above are
+all optional, but the attribute has to have at least one clause.
+
+
+### flag_enum
+
+{clang-attr-syntaxes}`FlagEnumDocs`
+
+This attribute can be added to an enumerator to signal to the compiler that it
+is intended to be used as a flag type. This will cause the compiler to assume
+that the range of the type includes all of the values that you can get by
+manipulating bits of the enumerator when issuing warnings.
+
+
+### gcc_struct, ms_struct
+
+{clang-attr-syntaxes}`MSStructDocs`
+
+The `ms_struct` and `gcc_struct` attributes request the compiler to enter a
+special record layout compatibility mode which mimics the layout of Microsoft or
+Itanium C++ ABI respectively. Obviously, if the current C++ ABI matches the
+requested ABI, the attribute does nothing. However, if it does not, annotated
+structure or class is laid out in a special compatibility mode, which slightly
+changes offsets for fields and bit-fields. The intention is to match the layout
+of the requested ABI for structures which only use C features.
+
+Note that the default behavior can be controlled by `-mms-bitfields` and
+`-mno-ms-bitfields` switches and via `#pragma ms_struct`.
+
+The primary difference is for bitfields, where the MS variant only packs
+adjacent fields into the same allocation unit if they have integral types
+of the same size, while the GCC/Itanium variant packs all fields in a bitfield
+tightly.
+
+
+### grid_constant
+
+{clang-attr-syntaxes}`CUDAGridConstantAttrDocs`
+
+The `__grid_constant__` attribute can be applied to a `const`-qualified kernel
+function argument and allows compiler to take the address of that argument without
+making a copy. The argument applies to sm_70 or newer GPUs, during compilation
+with CUDA-11.7(PTX 7.7) or newer, and is ignored otherwise.
+
+
+### layout_version
+
+{clang-attr-syntaxes}`LayoutVersionDocs`
+
+The layout_version attribute requests that the compiler utilize the class
+layout rules of a particular compiler version.
+This attribute only applies to struct, class, and union types.
+It is only supported when using the Microsoft C++ ABI.
+
+
+### lto_visibility_public
+
+{clang-attr-syntaxes}`LTOVisibilityDocs`
+
+See {doc}`LTOVisibility`.
+
+
+### managed
+
+{clang-attr-syntaxes}`HIPManagedAttrDocs`
+
+The `__managed__` attribute can be applied to a global variable declaration in HIP.
+A managed variable is emitted as an undefined global symbol in the device binary and is
+registered by `__hipRegisterManagedVar` in init functions. The HIP runtime allocates
+managed memory and uses it to define the symbol when loading the device binary.
+A managed variable can be accessed in both device and host code.
+
+
+### no_cluster
+
+{clang-attr-syntaxes}`CUDANoClusterAttrDoc`
+
+In CUDA/HIP programming, a kernel function can still be launched with the cluster feature enabled
+at runtime, even without being annotated with `__cluster_dims__`. The LLVM/Clang-exclusive
+`no_cluster` attribute, conventionally exposed as the `__no_cluster__` macro, can be applied to
+a kernel function to explicitly indicate that the cluster feature will not be enabled either at
+compile time or at kernel launch time. This allows the compiler to apply certain optimizations
+without assuming that clustering could be enabled at runtime. It is undefined behavior to launch a
+kernel annotated with `__no_cluster__` if the cluster feature is enabled at runtime.
+The `cluster_dims` and `no_cluster` attributes are mutually exclusive.
+
+```
+__global__ __no_cluster__ void kernel(...) {
+ ...
+}
+```
+
+
+### no_init_all
+
+{clang-attr-syntaxes}`NoTrivialAutoVarInitDocs`
+
+The `__declspec(no_init_all)` attribute disables the automatic initialization
+that the {option}`-ftrivial-auto-var-init` flag would have applied to locals in
+a marked function, or instances of a marked type. Note that this attribute has
+no effect for locals that are automatically initialized without the
+{option}`-ftrivial-auto-var-init` flag.
+
+
+### no_specializations
+
+{clang-attr-syntaxes}`NoSpecializationsDocs`
+
+`[[clang::no_specializations]]` can be applied to function, class, or variable
+templates for which neither an explicit specialization nor a partial specialization should be declared by users. This is primarily
+used to diagnose user specializations of standard library type traits.
+
+
+### nonstring
+
+{clang-attr-syntaxes}`NonStringDocs`
+
+The `nonstring` attribute can be applied to the declaration of a variable or
+a field whose type is a character pointer or character array to specify that
+the buffer is not intended to behave like a null-terminated string. This will
+silence diagnostics with code like:
+
+```c
+char BadStr[3] = "foo"; // No space for the null terminator, diagnosed
+__attribute__((nonstring)) char NotAStr[3] = "foo"; // Not diagnosed
+```
+
+
+### novtable
+
+{clang-attr-syntaxes}`MSNoVTableDocs`
+
+This attribute can be added to a class declaration or definition to signal to
+the compiler that constructors and destructors will not reference the virtual
+function table. It is only supported when using the Microsoft C++ ABI.
+
+
+### ns_error_domain
+
+{clang-attr-syntaxes}`NSErrorDomainDocs`
+
+In Cocoa frameworks in Objective-C, one can group related error codes in enums
+and categorize these enums with error domains.
+
+The `ns_error_domain` attribute indicates a global `NSString` or
+`CFString` constant representing the error domain that an error code belongs
+to. For pointer uniqueness and code size this is a constant symbol, not a
+literal.
+
+The domain and error code need to be used together. The `ns_error_domain`
+attribute links error codes to their domain at the source level.
+
+This metadata is useful for documentation purposes, for static analysis, and for
+improving interoperability between Objective-C and Swift. It is not used for
+code generation in Objective-C.
+
+For example:
+
+```objc
+#define NS_ERROR_ENUM(_type, _name, _domain) \
+ enum _name : _type _name; enum __attribute__((ns_error_domain(_domain))) _name : _type
+
+extern NSString *const MyErrorDomain;
+typedef NS_ERROR_ENUM(unsigned char, MyErrorEnum, MyErrorDomain) {
+ MyErrFirst,
+ MyErrSecond,
+};
+```
+
+
+### objc_boxable
+
+{clang-attr-syntaxes}`ObjCBoxableDocs`
+
+Structs and unions marked with the `objc_boxable` attribute can be used
+with the Objective-C boxed expression syntax, `@(...)`.
+
+**Usage**: `__attribute__((objc_boxable))`. This attribute
+can only be placed on a declaration of a trivially-copyable struct or union:
+
+```objc
+struct __attribute__((objc_boxable)) some_struct {
+ int i;
+};
+union __attribute__((objc_boxable)) some_union {
+ int i;
+ float f;
+};
+typedef struct __attribute__((objc_boxable)) _some_struct some_struct;
+
+// ...
+
+some_struct ss;
+NSValue *boxed = @(ss);
+```
+
+
+### objc_direct
+
+{clang-attr-syntaxes}`ObjCDirectDocs`
+
+The `objc_direct` attribute can be used to mark an Objective-C method as
+being *direct*. A direct method is treated statically like an ordinary method,
+but dynamically it behaves more like a C function. This lowers some of the costs
+associated with the method but also sacrifices some of the ordinary capabilities
+of Objective-C methods.
+
+A message send of a direct method calls the implementation directly, as if it
+were a C function, rather than using ordinary Objective-C method dispatch. This
+is substantially faster and potentially allows the implementation to be inlined,
+but it also means the method cannot be overridden in subclasses or replaced
+dynamically, as ordinary Objective-C methods can.
+
+Furthermore, a direct method is not listed in the class's method lists. This
+substantially reduces the code-size overhead of the method but also means it
+cannot be called dynamically using ordinary Objective-C method dispatch at all;
+in particular, this means that it cannot override a superclass method or satisfy
+a protocol requirement.
+
+Because a direct method cannot be overridden, it is an error to perform
+a `super` message send of one.
+
+Although a message send of a direct method causes the method to be called
+directly as if it were a C function, it still obeys Objective-C semantics in other
+ways:
+
+- If the receiver is `nil`, the message send does nothing and returns the zero value
+ for the return type.
+- A message send of a direct class method will cause the class to be initialized,
+ 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.
+
+Symbols for direct method implementations are implicitly given hidden
+visibility, meaning that they can only be called within the same linkage unit.
+
+It is an error to do any of the following:
+
+- declare a direct method in a protocol,
+- declare an override of a direct method with a method in a subclass,
+- declare an override of a non-direct method with a direct method in a subclass,
+- declare a method with different directness in different class interfaces, or
+- implement a non-direct method (as declared in any class interface) with a direct method.
+
+If any of these rules would be violated if every method defined in an
+`@implementation` within a single linkage unit were declared in an
+appropriate class interface, the program is ill-formed with no diagnostic
+required. If a violation of this rule is not diagnosed, behavior remains
+well-defined; this paragraph is simply reserving the right to diagnose such
+conflicts in the future, not to treat them as undefined behavior.
+
+Additionally, Clang will warn about any `@selector` expression that
+names a selector that is only known to be used for direct methods.
+
+For the purpose of these rules, a "class interface" includes a class's primary
+`@interface` block, its class extensions, its categories, its declared protocols,
+and all the class interfaces of its superclasses.
+
+An Objective-C property can be declared with the `direct` property
+attribute. If a direct property declaration causes an implicit declaration of
+a getter or setter method (that is, if the given method is not explicitly
+declared elsewhere), the method is declared to be direct.
+
+Some programmers may wish to make many methods direct at once. In order
+to simplify this, the `objc_direct_members` attribute is provided; see its
+documentation for more information.
+
+
+### objc_direct_members
+
+{clang-attr-syntaxes}`ObjCDirectMembersDocs`
+
+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.
+
+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.
+
+When `objc_direct_members` is placed on an `@implementation` block,
+methods defined in the block are considered to be declared as direct unless
+they have been previously declared as non-direct in any interface of the class.
+This includes the implicit method definitions introduced by synthesized
+properties, including auto-synthesized properties.
+
+
+### objc_non_runtime_protocol
+
+{clang-attr-syntaxes}`ObjCNonRuntimeProtocolDocs`
+
+The `objc_non_runtime_protocol` attribute can be used to mark that an
+Objective-C protocol is only used during static type-checking and doesn't need
+to be represented dynamically. This avoids several small code-size and run-time
+overheads associated with handling the protocol's metadata. A non-runtime
+protocol cannot be used as the operand of a `@protocol` expression, and
+dynamic attempts to find it with `objc_getProtocol` will fail.
+
+If a non-runtime protocol inherits from any ordinary protocols, classes and
+derived protocols that declare conformance to the non-runtime protocol will
+dynamically list their conformance to those bare protocols.
+
+
+### objc_nonlazy_class
+
+{clang-attr-syntaxes}`ObjCNonLazyClassDocs`
+
+This attribute can be added to an Objective-C `@interface` or
+`@implementation` declaration to add the class to the list of non-lazily
+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
+overheads associated with defining and calling such a method.
+
+
+### objc_runtime_name
+
+{clang-attr-syntaxes}`ObjCRuntimeNameDocs`
+
+By default, the Objective-C interface or protocol identifier is used
+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.
+
+**Usage**: `__attribute__((objc_runtime_name("MyLocalName")))`. This attribute
+can only be placed before an @protocol or @interface declaration:
+
+```objc
+__attribute__((objc_runtime_name("MyLocalName")))
+ at interface Message
+ at end
+```
+
+
+### objc_runtime_visible
+
+{clang-attr-syntaxes}`ObjCRuntimeVisibleDocs`
+
+This attribute specifies that the Objective-C class to which it applies is
+visible to the Objective-C runtime but not to the linker. Classes annotated
+with this attribute cannot be subclassed and cannot have categories defined for
+them.
+
+
+### objc_subclassing_restricted
+
+{clang-attr-syntaxes}`ObjCSubclassingRestrictedDocs`
+
+This attribute can be added to an Objective-C `@interface` declaration to
+ensure that this class cannot be subclassed.
+
+
+### preferred_name
+
+{clang-attr-syntaxes}`PreferredNameDocs`
+
+The `preferred_name` attribute can be applied to a class template, and
+specifies a preferred way of naming a specialization of the template. The
+preferred name will be used whenever the corresponding template specialization
+would otherwise be printed in a diagnostic or similar context.
+
+The preferred name must be a typedef or type alias declaration that refers to a
+specialization of the class template (not including any type qualifiers). In
+general this requires the template to be declared at least twice. For example:
+
+```c++
+template<typename T> struct basic_string;
+using string = basic_string<char>;
+using wstring = basic_string<wchar_t>;
+template<typename T> struct [[clang::preferred_name(string),
+ clang::preferred_name(wstring)]] basic_string {
+ // ...
+};
+```
+
+Note that the `preferred_name` attribute will be ignored when the compiler
+writes a C++20 Module interface now. This is due to a compiler issue
+(<https://github.com/llvm/llvm-project/issues/56490>) that blocks users to modularize
+declarations with `preferred_name`. This is intended to be fixed in the future.
+
+
+### randomize_layout, no_randomize_layout
+
+{clang-attr-syntaxes}`ClangRandomizeLayoutDocs`
+
+The attribute `randomize_layout`, when attached to a C structure, selects it
+for structure layout field randomization; a compile-time hardening technique. A
+"seed" value, is specified via the `-frandomize-layout-seed=` command line flag.
+For example:
+
+```bash
+SEED=`od -A n -t x8 -N 32 /dev/urandom | tr -d ' \n'`
+make ... CFLAGS="-frandomize-layout-seed=$SEED" ...
+```
+
+You can also supply the seed in a file with `-frandomize-layout-seed-file=`.
+For example:
+
+```bash
+od -A n -t x8 -N 32 /dev/urandom | tr -d ' \n' > /tmp/seed_file.txt
+make ... CFLAGS="-frandomize-layout-seed-file=/tmp/seed_file.txt" ...
+```
+
+The randomization is deterministic based for a given seed, so the entire
+program should be compiled with the same seed, but keep the seed safe
+otherwise.
+
+The attribute `no_randomize_layout`, when attached to a C structure,
+instructs the compiler that this structure should not have its field layout
+randomized.
+
+
+### selectany
+
+{clang-attr-syntaxes}`SelectAnyDocs`
+
+This attribute appertains to a global symbol, causing it to have a weak
+definition ([linkonce](https://llvm.org/docs/LangRef.html#linkage-types)),
+allowing the linker to select any definition.
+
+For more information see
+[gcc documentation](https://gcc.gnu.org/onlinedocs/gcc-7.2.0/gcc/Microsoft-Windows-Variable-Attributes.html)
+or [msvc documentation](https://docs.microsoft.com/pl-pl/cpp/cpp/selectany).
+
+
+### transparent_union
+
+{clang-attr-syntaxes}`TransparentUnionDocs`
+
+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
+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.
+- The argument is passed to the function using the calling convention of the
+ first member of the transparent union. Consequently, all the members of the
+ transparent union should have the same calling convention as its first member.
+
+Transparent unions are not supported in C++.
+
+
+### trivial_abi
+
+{clang-attr-syntaxes}`TrivialABIDocs`
+
+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:
+
+```c++
+// A is trivial for the purposes of calls because `trivial_abi` makes the
+// user-provided special functions trivial.
+struct __attribute__((trivial_abi)) A {
+ ~A();
+ A(const A &);
+ A(A &&);
+ int x;
+};
+
+// B's destructor and copy/move constructor are considered trivial for the
+// purpose of calls because A is trivial.
+struct B {
+ A a;
+};
+```
+
+If a type is trivial for the purposes of calls, has a non-trivial destructor,
+and is passed as an argument by value, the convention is that the callee will
+destroy the object before returning. The lifetime of the copy of the parameter
+in the caller ends without a destructor call when the call begins.
+
+If a type is trivial for the purpose of calls, it is assumed to be trivially
+relocatable for the purpose of `__is_trivially_relocatable` and
+`__builtin_is_cpp_trivially_relocatable`.
+When a type marked with `[[trivial_abi]]` is used as a function argument,
+the compiler may omit the call to the copy constructor.
+Thus, side effects of the copy constructor are potentially not performed.
+For example, objects that contain pointers to themselves or otherwise depend
+on their address (or the address or their subobjects) should not be declared
+`[[trivial_abi]]`.
+
+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:
+
+ - classes that are non-trivial for the purposes of calls
+ - `__weak`-qualified types in Objective-C++
+ - arrays of any of the above
+
+
+### using_if_exists
+
+{clang-attr-syntaxes}`UsingIfExistsDocs`
+
+The `using_if_exists` attribute applies to a using-declaration. It allows
+programmers to import a declaration that potentially does not exist, instead
+deferring any errors to the point of use. For instance:
+
+```c++
+namespace empty_namespace {};
+__attribute__((using_if_exists))
+using empty_namespace::does_not_exist; // no error!
+
+does_not_exist x; // error: use of unresolved 'using_if_exists'
+```
+
+The C++ spelling of the attribute (`[[clang::using_if_exists]]`) is also
+supported as a clang extension, since ISO C++ doesn't support attributes in this
+position. If the entity referred to by the using-declaration is found by name
+lookup, the attribute has no effect. This attribute is useful for libraries
+(primarily, libc++) that wish to redeclare a set of declarations in another
+namespace, when the availability of those declarations is difficult or
+impossible to detect at compile time with the preprocessor.
+
+
+### weak
+
+{clang-attr-syntaxes}`WeakDocs`
+
+In supported output formats the `weak` attribute can be used to
+specify that a variable or function should be emitted as a symbol with
+`weak` (if a definition) or `extern_weak` (if a declaration of an
+external symbol) [linkage](https://llvm.org/docs/LangRef.html#linkage-types).
+
+If there is a non-weak definition of the symbol the linker will select
+that over the weak. They must have same type and alignment (variables
+must also have the same size), but may have a different value.
+
+If there are multiple weak definitions of same symbol, but no non-weak
+definition, they should have same type, size, alignment and value, the
+linker will select one of them (see also [selectany] attribute).
+
+If the `weak` attribute is applied to a `const` qualified variable
+definition that variable is no longer consider a compiletime constant
+as its value can change during linking (or dynamic linking). This
+means that it can e.g no longer be part of an initializer expression.
+
+```c
+const int ANSWER __attribute__ ((weak)) = 42;
+
+/* This function may be replaced link-time */
+__attribute__ ((weak)) void debug_log(const char *msg)
+{
+ fprintf(stderr, "DEBUG: %s\n", msg);
+}
+
+int main(int argc, const char **argv)
+{
+ debug_log ("Starting up...");
+
+ /* This may print something else than "6 * 7 = 42",
+ if there is a non-weak definition of "ANSWER" in
+ an object linked in */
+ printf("6 * 7 = %d\n", ANSWER);
+
+ return 0;
+ }
+```
+
+If an external declaration is marked weak and that symbol does not
+exist during linking (possibly dynamic) the address of the symbol will
+evaluate to NULL.
+
+```c
+void may_not_exist(void) __attribute__ ((weak));
+
+int main(int argc, const char **argv)
+{
+ if (may_not_exist) {
+ may_not_exist();
+ } else {
+ printf("Function did not exist\n");
+ }
+ return 0;
+}
+```
+
+
diff --git a/clang/docs/AttributeReference/FieldAttributes.md b/clang/docs/AttributeReference/FieldAttributes.md
new file mode 100644
index 0000000000000..86446b9a2e537
--- /dev/null
+++ b/clang/docs/AttributeReference/FieldAttributes.md
@@ -0,0 +1,436 @@
+## Field Attributes
+
+
+
+### counted_by
+
+{clang-attr-syntaxes}`CountedByDocs`
+
+The `counted_by` attribute is applied to a pointer or flexible array member to
+indicate that the pointer points to (or the flexible array member contains) at
+least the number of *elements* given by the attribute's argument.
+
+This attribute is used by {doc}`-fbounds-safety <BoundsSafety>` to propagate
+bounds information on API surfaces without any ABI changes. This attribute is
+also used to improve the results of the array bound sanitizer and the
+`__builtin_dynamic_object_size` builtin.
+
+Because the size of the pointee type must be known to compute the pointer's
+bounds, such a pointer must not be used while its pointee type is incomplete; a
+pointer to a forward-declared type is accepted on fields annotated with
+`counted_by`, but the type must be completed before the pointer is used. If
+the pointee type can never be completed, `counted_by` is rejected and
+`sized_by` should be used instead. `void *` is a special case: as a GNU
+extension (diagnosed by `-Wgnu-pointer-arith`), `counted_by` is accepted on
+it, where it behaves like `sized_by` (the argument is treated as a byte count,
+`void` having an assumed size of one byte).
+
+A pointer annotated with `counted_by` must have a count of zero when it is
+null. This requirement is currently only enforced when compiling with
+{doc}`-fbounds-safety <BoundsSafety>` (see {ref}`Current status of
+-fbounds-safety support in upstream Clang <bounds-safety-current-upstream-status>`). Use
+`counted_by_or_null` for a pointer that may be null while carrying a nonzero
+count.
+
+#### Keeping pointer and count in sync
+
+The `counted_by` attribute establishes a relationship between the annotated
+pointer and its count: the pointer must point to at least `count` elements.
+Assigning to only one of them can break this relationship.
+Without {doc}`-fbounds-safety <BoundsSafety>`, it is the programmer's
+responsibility to ensure the pointer and count remain in sync. With
+`-fbounds-safety` it is automatically enforced. For example:
+
+```c
+struct buffer {
+ int *buf __attribute__((counted_by(count)));
+ size_t count;
+};
+
+void grow(struct buffer *b, size_t new_count) {
+ // b->buf isn't updated. The underlying memory pointed to by b->buf might be
+ // smaller than new_count which would contradict the counted_by attribute.
+ // Compile error with -fbounds-safety but allowed without -fbounds-safety.
+ b->count = new_count;
+}
+```
+
+Updating both together - so that `buf` points to `count` elements - keeps
+the attribute true. For example:
+
+```c
+void grow(struct buffer *b, size_t new_count) {
+ // Allowed by -fbounds-safety
+ int *new_buf = malloc(new_count * sizeof(int));
+ // -fbounds-safety enforces that the `new_buf` points to at least `new_count`
+ // integers at runtime. Without -fbounds-safety nothing enforces this.
+ b->buf = new_buf;
+ b->count = new_count;
+}
+```
+
+#### Flexible array members
+
+The `counted_by` attribute may also be applied to the flexible array member of
+a structure in C. In this case the argument names the field member holding the
+count of elements in the flexible array; that field must be within the same
+non-anonymous, enclosing struct as the flexible array member.
+
+This example specifies that the flexible array member `array` has the number
+of elements allocated for it in `count`:
+
+```c
+struct bar;
+
+struct foo {
+ size_t count;
+ char other;
+ struct bar *array[] __attribute__((counted_by(count)));
+};
+```
+
+This establishes a relationship between `array` and `count`. Specifically,
+`array` must have at least `count` number of elements available. It's the
+user's responsibility to ensure that this relationship is maintained through
+changes to the structure.
+
+In the following example, the allocated array erroneously has fewer elements
+than what's specified by `p->count`. This would result in an out-of-bounds
+access not being detected.
+
+```c
+#define SIZE_INCR 42
+
+struct foo *p;
+
+void foo_alloc(size_t count) {
+ p = malloc(MAX(sizeof(struct foo),
+ offsetof(struct foo, array[0]) + count * sizeof(struct bar *)));
+ p->count = count + SIZE_INCR;
+}
+```
+
+The next example updates `p->count`, but breaks the relationship requirement
+that `p->array` must have at least `p->count` number of elements available:
+
+```c
+#define SIZE_INCR 42
+
+struct foo *p;
+
+void foo_alloc(size_t count) {
+ p = malloc(MAX(sizeof(struct foo),
+ offsetof(struct foo, array[0]) + count * sizeof(struct bar *)));
+ p->count = count;
+}
+
+void use_foo(int index, int val) {
+ p->count += SIZE_INCR + 1; /* 'count' is now larger than the number of elements of 'array'. */
+ p->array[index] = val; /* The sanitizer can't properly check this access. */
+}
+```
+
+In this example, an update to `p->count` maintains the relationship
+requirement:
+
+```c
+void use_foo(int index, int val) {
+ if (p->count == 0)
+ return;
+ --p->count;
+ p->array[index] = val;
+}
+```
+
+
+### counted_by_or_null
+
+{clang-attr-syntaxes}`CountedByOrNullDocs`
+
+The `counted_by_or_null` attribute is applied to a pointer to indicate that,
+if the pointer is non-null, it points to memory containing at least the number
+of *elements* given by the attribute's argument. If the pointer is null, the
+value of the argument is ignored and the pointer points to zero elements.
+
+The `counted_by_or_null` attribute is identical to `counted_by` except that
+it treats null pointers differently and cannot be applied to a flexible array
+member. Whereas `counted_by` requires a null pointer to have a count of zero,
+`counted_by_or_null` allows the pointer to be null regardless of the value of
+the count. This supports the common idiom where a pointer is either null or
+points to memory containing at least the given number of elements.
+
+Currently only {doc}`-fbounds-safety <BoundsSafety>` makes use of the
+distinction between `counted_by_or_null` and `counted_by` (see
+{ref}`Current status of -fbounds-safety support in upstream Clang
+<bounds-safety-current-upstream-status>`).
+
+
+### no_unique_address
+
+{clang-attr-syntaxes}`NoUniqueAddressDocs`
+
+The `no_unique_address` attribute allows tail padding in a non-static data
+member to overlap other members of the enclosing class (and in the special
+case when the type is empty, permits it to fully overlap other members).
+The field is laid out as if a base class were encountered at the corresponding
+point within the class (except that it does not share a vptr with the enclosing
+object).
+
+Example usage:
+
+```c++
+template<typename T, typename Alloc> struct my_vector {
+ T *p;
+ [[no_unique_address]] Alloc alloc;
+ // ...
+};
+static_assert(sizeof(my_vector<int, std::allocator<int>>) == sizeof(int*));
+```
+
+`[[no_unique_address]]` is a standard C++20 attribute. Clang supports its use
+in C++11 onwards.
+
+On MSVC targets, `[[no_unique_address]]` is ignored; use
+`[[msvc::no_unique_address]]` instead. Currently there is no guarantee of ABI
+compatibility or stability with MSVC.
+
+
+(langext-preferred_type_documentation)=
+
+### preferred_type
+
+{clang-attr-syntaxes}`PreferredTypeDocumentation`
+
+This attribute allows adjusting the type of a bit-field in debug information.
+This can be helpful when a bit-field is intended to store an enumeration value,
+but has to be specified as having the enumeration's underlying type in order to
+facilitate compiler optimizations or bit-field packing behavior. Normally, the
+underlying type is what is emitted in debug information, which can make it hard
+for debuggers to know to map a bit-field's value back to a particular enumeration.
+
+```c++
+enum Colors { Red, Green, Blue };
+
+struct S {
+ [[clang::preferred_type(Colors)]] unsigned ColorVal : 2;
+ [[clang::preferred_type(bool)]] unsigned UseAlternateColorSpace : 1;
+} s = { Green, false };
+```
+
+Without the attribute, a debugger is likely to display the value `1` for `ColorVal`
+and `0` for `UseAlternateColorSpace`. With the attribute, the debugger may now
+display `Green` and `false` instead.
+
+This can be used to map a bit-field to an arbitrary type that isn't integral
+or an enumeration type. For example:
+
+```c++
+struct A {
+ short a1;
+ short a2;
+};
+
+struct B {
+ [[clang::preferred_type(A)]] unsigned b1 : 32 = 0x000F'000C;
+};
+```
+
+will associate the type `A` with the `b1` bit-field and is intended to display
+something like this in the debugger:
+
+```text
+Process 2755547 stopped
+* thread #1, name = 'test-preferred-', stop reason = step in
+ frame #0: 0x0000555555555148 test-preferred-type`main at test.cxx:13:14
+ 10 int main()
+ 11 {
+ 12 B b;
+-> 13 return b.b1;
+ 14 }
+(lldb) v -T
+(B) b = {
+ (A:32) b1 = {
+ (short) a1 = 12
+ (short) a2 = 15
+ }
+}
+```
+
+Note that debuggers may not be able to handle more complex mappings, and so
+this usage is debugger-dependent.
+
+
+### require_explicit_initialization
+
+{clang-attr-syntaxes}`ExplicitInitDocs`
+
+The `clang::require_explicit_initialization` attribute indicates that a
+field of an aggregate must be initialized explicitly by the user when an object
+of the aggregate type is constructed. The attribute supports both C and C++,
+but its usage is invalid on non-aggregates.
+
+Note that this attribute is *not* a memory safety feature, and is *not* intended
+to guard against use of uninitialized memory.
+
+Rather, it is intended for use in "parameter-objects", used to simulate,
+for example, the passing of named parameters.
+Except inside unevaluated contexts, the attribute generates a warning when
+explicit initializers for such variables are not provided (this occurs
+regardless of whether any in-class field initializers exist):
+
+```c++
+struct Buffer {
+ void *address [[clang::require_explicit_initialization]];
+ size_t length [[clang::require_explicit_initialization]] = 0;
+};
+
+struct ArrayIOParams {
+ size_t count [[clang::require_explicit_initialization]];
+ size_t element_size [[clang::require_explicit_initialization]];
+ int flags = 0;
+};
+
+size_t ReadArray(FILE *file, struct Buffer buffer,
+ struct ArrayIOParams params);
+
+int main() {
+ unsigned int buf[512];
+ ReadArray(stdin, {
+ buf
+ // warning: field 'length' is not explicitly initialized
+ }, {
+ .count = sizeof(buf) / sizeof(*buf),
+ // warning: field 'element_size' is not explicitly initialized
+ // (Note that a missing initializer for 'flags' is not diagnosed, because
+ // the field is not marked as requiring explicit initialization.)
+ });
+}
+```
+
+
+### sized_by
+
+{clang-attr-syntaxes}`SizedByDocs`
+
+The `sized_by` attribute is applied to a pointer to indicate that the pointer
+points to memory containing at least the number of *bytes* given by the
+attribute's argument. It is closely related to `counted_by`; the difference is
+that `counted_by` counts the number of *elements* of the pointee type, whereas
+`sized_by` counts the number of *bytes*. This makes `sized_by` the natural
+choice for `void *` and other byte buffers.
+
+This attribute is used by {doc}`-fbounds-safety <BoundsSafety>` to propagate
+bounds information on API surfaces without any ABI changes. This attribute is
+also used to improve the results of the array bound sanitizer and the
+`__builtin_dynamic_object_size` builtin.
+
+The argument is an expression of integer type, following the same rules as the
+argument of `counted_by`. Unlike `counted_by`, `sized_by` cannot be
+applied to a C99 flexible array member; it applies to pointers only. For
+example:
+
+```c
+struct object {
+ unsigned long size;
+ void *data __attribute__((sized_by(size)));
+};
+```
+
+A pointer annotated with `sized_by` must have a size of zero when it is null.
+This requirement is currently only enforced when compiling with
+{doc}`-fbounds-safety <BoundsSafety>` (see {ref}`Current status of
+-fbounds-safety support in upstream Clang <bounds-safety-current-upstream-status>`). Use
+`sized_by_or_null` for a pointer that may be null while carrying a nonzero
+size.
+
+#### Keeping pointer and size in sync
+
+The `sized_by` attribute establishes a relationship between the annotated
+pointer and its size: the pointer must point to at least `size` bytes.
+Assigning to only one of them can break this relationship.
+Without {doc}`-fbounds-safety <BoundsSafety>`, it is the programmer's
+responsibility to ensure the pointer and size remain in sync. With
+`-fbounds-safety` it is automatically enforced. For example:
+
+```c
+struct buffer {
+ uint8_t *buf __attribute__((sized_by(size)));
+ size_t size;
+};
+
+void grow(struct buffer *b, size_t new_size) {
+ // b->buf isn't updated. The underlying memory pointed to by b->buf might be
+ // smaller than new_size which would contradict the sized_by attribute.
+ // Compile error with -fbounds-safety but allowed without -fbounds-safety.
+ b->size = new_size;
+}
+```
+
+Updating both together - so that `buf` points to `size` bytes - keeps
+the attribute true. For example:
+
+```c
+void grow(struct buffer *b, size_t new_size) {
+ // Allowed by -fbounds-safety
+ uint8_t *new_buf = malloc(new_size);
+ // -fbounds-safety enforces that the `new_buf` points to at least `new_size`
+ // bytes at runtime. Without -fbounds-safety nothing enforces this.
+ b->buf = new_buf;
+ b->size = new_size;
+}
+```
+
+#### Incomplete and variable-length pointees
+
+`sized_by` is typically applied to `void *` or a pointer to a byte-sized
+type, but it may be used with any pointee type. Two situations call for this,
+both of which rule out counting fixed-size elements:
+
+First, the pointee type may be incomplete, such as an opaque type. Its element
+size is then unavailable, so `counted_by` cannot be used, whereas `sized_by`
+bounds the memory in bytes and imposes no completeness requirement.
+
+Second, the buffer may hold variable-length elements, so there is no fixed
+element size to count, even though the total byte size is well defined. For
+example, a buffer might pack together several structures that each end in a
+flexible array member of differing length:
+
+```c
+struct var_len {
+ int fam_size;
+ char data[] __attribute__((counted_by(fam_size)));
+};
+
+struct buffer_view {
+ int byte_size;
+ struct var_len *buf __attribute__((sized_by(byte_size)));
+};
+```
+
+Here `counted_by` cannot be applied to `buf` because its pointee is a
+variable-length structure, but `sized_by` bounds the whole region in bytes;
+the region is traversed by advancing a byte offset rather than by indexing
+elements.
+
+
+### sized_by_or_null
+
+{clang-attr-syntaxes}`SizedByOrNullDocs`
+
+The `sized_by_or_null` attribute is applied to a pointer to indicate that, if
+the pointer is non-null, it points to memory containing at least the number of
+*bytes* given by the attribute's argument. If the pointer is null, the value of
+the argument is ignored and the pointer points to zero bytes.
+
+The `sized_by_or_null` attribute is identical to `sized_by` except in how
+it treats null pointers. Whereas `sized_by` requires a null pointer to have a
+size of zero, `sized_by_or_null` allows the pointer to be null regardless of
+the value of the size. This supports the common idiom where a pointer is either
+null or points to memory containing at least the given number of bytes.
+
+Currently only {doc}`-fbounds-safety <BoundsSafety>` makes use of the
+distinction between `sized_by_or_null` and `sized_by` (see
+{ref}`Current status of -fbounds-safety support in upstream Clang
+<bounds-safety-current-upstream-status>`).
+
+
diff --git a/clang/docs/AttributeReference/FunctionAttributes.md b/clang/docs/AttributeReference/FunctionAttributes.md
new file mode 100644
index 0000000000000..a07120330a5a5
--- /dev/null
+++ b/clang/docs/AttributeReference/FunctionAttributes.md
@@ -0,0 +1,4534 @@
+## Function Attributes
+
+
+
+### #pragma omp declare simd
+
+{clang-attr-syntaxes}`OMPDeclareSimdDocs`
+
+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
+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:
+
+```none
+#pragma omp declare simd [clause[[,] clause] ...] new-line
+[#pragma omp declare simd [clause[[,] clause] ...] new-line]
+[...]
+function definition or declaration
+```
+
+where clause is one of the following:
+
+```none
+simdlen(length)
+linear(argument-list[:constant-linear-step])
+aligned(argument-list[:alignment])
+uniform(argument-list)
+inbranch
+notinbranch
+```
+
+
+### #pragma omp declare target
+
+{clang-attr-syntaxes}`OMPDeclareTargetDocs`
+
+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:
+
+```c
+#pragma omp declare target new-line
+declarations-definition-seq
+#pragma omp end declare target new-line
+```
+
+or
+
+```c
+#pragma omp declare target (extended-list) new-line
+```
+
+or
+
+```c
+#pragma omp declare target clause[ [,] clause ... ] new-line
+```
+
+where clause is one of the following:
+
+```c
+to(extended-list)
+link(list)
+device_type(host | nohost | any)
+```
+
+
+### #pragma omp declare variant
+
+{clang-attr-syntaxes}`OMPDeclareVariantDocs`
+
+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:
+
+```none
+#pragma omp declare variant(variant-func-id) clause new-line
+[#pragma omp declare variant(variant-func-id) clause new-line]
+[...]
+function definition or declaration
+```
+
+where clause is one of the following:
+
+```none
+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.
+
+Clang provides the following context selector extensions, used via
+`implementation={extension(EXTENSION)}`:
+
+```none
+match_all
+match_any
+match_none
+disable_implicit_base
+allow_templates
+bind_to_declaration
+```
+
+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.
+The disable extensions remove default effects of the `begin declare variant`
+applied to a definition. If `disable_implicit_base` is given, we will not
+introduce an implicit base function for a variant if no base function was
+found. The variant is still generated but will never be called, due to the
+absence of a base function and consequently calls to a base function.
+The allow extensions change when the `begin declare variant` effect is
+applied to a definition. If `allow_templates` is given, template function
+definitions are considered as specializations of existing or assumed template
+declarations with the same name. The template parameters for the base functions
+are used to instantiate the specialization. If `bind_to_declaration` is given,
+apply the same variant rules to function declarations. This allows the user to
+override declarations with only a function declaration.
+
+
+### RootSignature
+
+{clang-attr-syntaxes}`RootSignatureDocs`
+
+The `RootSignature` attribute applies to HLSL entry functions to define what
+types of resources are bound to the graphics pipeline.
+
+For details about the use and specification of Root Signatures please see here:
+<https://learn.microsoft.com/en-us/windows/win32/direct3d12/root-signatures>
+
+
+### WaveSize
+
+{clang-attr-syntaxes}`WaveSizeDocs`
+
+The `WaveSize` attribute specifies a wave size on a shader entry point in order
+to indicate either that a shader depends on or strongly prefers a specific wave
+size.
+There're 2 versions of the attribute: `WaveSize` and `RangedWaveSize`.
+The syntax for `WaveSize` is:
+
+```text
+[WaveSize(<numLanes>)]
+```
+
+The allowed wave sizes that an HLSL shader may specify are the powers of 2
+between 4 and 128, inclusive.
+In other words, the set: [4, 8, 16, 32, 64, 128].
+
+The syntax for `RangedWaveSize` is:
+
+```text
+[WaveSize(<minWaveSize>, <maxWaveSize>, [prefWaveSize])]
+```
+
+Where minWaveSize is the minimum wave size supported by the shader representing
+the beginning of the allowed range, maxWaveSize is the maximum wave size
+supported by the shader representing the end of the allowed range, and
+prefWaveSize is the optional preferred wave size representing the size expected
+to be the most optimal for this shader.
+
+`WaveSize` is available for HLSL shader model 6.6 and later.
+`RangedWaveSize` available for HLSL shader model 6.8 and later.
+
+The full documentation is available here: <https://microsoft.github.io/DirectX-Specs/d3d/HLSL_SM_6_6_WaveSize.html>
+and <https://microsoft.github.io/hlsl-specs/proposals/0013-wave-size-range.html>
+
+
+### _Noreturn
+
+{clang-attr-syntaxes}`C11NoReturnDocs`
+
+A function declared as `_Noreturn` shall not return to its caller. The
+compiler will generate a diagnostic for a function declared as `_Noreturn`
+that appears to be capable of returning to its caller. Despite being a type
+specifier, the `_Noreturn` attribute cannot be specified on a function
+pointer type.
+
+
+### abi_tag
+
+{clang-attr-syntaxes}`AbiTagsDocs`
+
+The `abi_tag` attribute can be applied to a function, variable, class or
+inline namespace declaration to modify the mangled name of the entity. It gives
+the ability to distinguish between different versions of the same entity but
+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 mangled name and the new code will use the new mangled name with tags.
+
+
+### acquire_capability, acquire_shared_capability
+
+{clang-attr-syntaxes}`AcquireCapabilityDocs`
+
+Marks a function as acquiring a capability.
+
+
+### alloc_align
+
+{clang-attr-syntaxes}`AllocAlignDocs`
+
+Use `__attribute__((alloc_align(<parameter-index>)))` on a declaration with a
+function prototype to specify that the prototype's return value (which must be a
+pointer type) is at least as aligned as the value of the indicated parameter.
+This includes functions, Objective-C methods, blocks, and declarations of
+function pointer, member function pointer, function reference, and block pointer
+types. The attribute can also be applied to typedef or type alias declarations
+whose underlying type has a function prototype.
+
+The parameter is given by its index in the list of formal parameters; the first
+parameter has index 1 unless the function is a C++ non-static member function,
+in which case the first parameter has index 2 to account for the implicit `this`
+parameter.
+
+```c++
+// The returned pointer has the alignment specified by the first parameter.
+void *a(size_t align) __attribute__((alloc_align(1)));
+
+// The function pointer's returned pointer has the alignment specified by
+// the first parameter of the pointed-to function.
+void *(*allocator)(size_t align) __attribute__((alloc_align(1)));
+
+// The returned pointer has the alignment specified by the second parameter.
+void *b(void *v, size_t align) __attribute__((alloc_align(2)));
+
+// The returned pointer has the alignment specified by the second visible
+// parameter, however it must be adjusted for the implicit 'this' parameter.
+void *Foo::b(void *v, size_t align) __attribute__((alloc_align(3)));
+```
+
+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
+pointer is not sufficiently aligned.
+
+
+### alloc_size
+
+{clang-attr-syntaxes}`AllocSizeDocs`
+
+The `alloc_size` attribute can be placed on functions that return pointers in
+order to hint to the compiler how many bytes of memory will be available at the
+returned pointer. `alloc_size` takes one or two arguments.
+
+- `alloc_size(N)` implies that argument number N equals the number of
+ available bytes at the returned pointer.
+- `alloc_size(N, M)` implies that the product of argument number N and
+ argument number M equals the number of available bytes at the returned
+ pointer.
+
+Argument numbers are 1-based.
+
+An example of how to use `alloc_size`
+
+```c
+void *my_malloc(int a) __attribute__((alloc_size(1)));
+void *my_calloc(int a, int b) __attribute__((alloc_size(1, 2)));
+
+int main() {
+ void *const p = my_malloc(100);
+ assert(__builtin_object_size(p, 0) == 100);
+ void *const a = my_calloc(20, 5);
+ assert(__builtin_object_size(a, 0) == 100);
+}
+```
+
+When `-Walloc-size` is enabled, this attribute allows the compiler to
+diagnose cases when the allocated memory is insufficient for the size of the
+type the returned pointer is cast to.
+
+```c
+void *my_malloc(int a) __attribute__((alloc_size(1)));
+void consumer_func(int *);
+
+int main() {
+ int *ptr = my_malloc(sizeof(int)); // no warning
+ int *w = my_malloc(1); // warning: allocation of insufficient size '1' for type 'int' with size '4'
+ consumer_func(my_malloc(1)); // warning: allocation of insufficient size '1' for type 'int' with size '4'
+}
+```
+
+:::{Note}
+This attribute works differently in clang than it does in GCC.
+Specifically, clang will only trace `const` pointers (as above); we give up
+on pointers that are not marked as `const`. In the vast majority of cases,
+this is unimportant, because LLVM has support for the `alloc_size`
+attribute. However, this may cause mildly unintuitive behavior when used with
+other attributes, such as `enable_if`.
+:::
+
+
+### allocator
+
+{clang-attr-syntaxes}`MSAllocatorDocs`
+
+The `__declspec(allocator)` attribute is applied to functions that allocate
+memory, such as operator new in C++. When CodeView debug information is emitted
+(enabled by `clang -gcodeview` or `clang-cl /Z7`), Clang will attempt to
+record the code offset of heap allocation call sites in the debug info. It will
+also record the type being allocated using some local heuristics. The Visual
+Studio debugger uses this information to [profile memory usage][profile memory usage].
+
+This attribute does not affect optimizations in any way, unlike GCC's
+`__attribute__((malloc))`.
+
+[profile memory usage]: https://docs.microsoft.com/en-us/visualstudio/profiling/memory-usage
+
+
+### always_inline, __force_inline
+
+{clang-attr-syntaxes}`AlwaysInlineDocs`
+
+Inlining heuristics are disabled and inlining is always attempted regardless of
+optimization level.
+
+`[[clang::always_inline]]` spelling can be used as a statement attribute; other
+spellings of the attribute are not supported on statements. If a statement is
+marked `[[clang::always_inline]]` and contains calls, the compiler attempts
+to inline those calls.
+
+```c
+int example(void) {
+ int i;
+ [[clang::always_inline]] foo(); // attempts to inline foo
+ [[clang::always_inline]] i = bar(); // attempts to inline bar
+ [[clang::always_inline]] return f(42, baz(bar())); // attempts to inline everything
+}
+```
+
+A declaration statement, which is a statement, is not a statement that can have an
+attribute associated with it (the attribute applies to the declaration, not the
+statement in that case). So this use case will not work:
+
+```c
+int example(void) {
+ [[clang::always_inline]] int i = bar();
+ return i;
+}
+```
+
+This attribute does not guarantee that inline substitution actually occurs.
+
+:::{Note}
+Note: applying this attribute to a coroutine at the `-O0` optimization level
+has no effect; other optimization levels may only partially inline and result in a
+diagnostic.
+:::
+
+See also [the Microsoft Docs on Inline Functions][the microsoft docs on inline functions], [the GCC Common Function
+Attribute docs][the gcc common function attribute docs], and [the GCC Inline docs][the gcc inline docs].
+
+[the gcc common function attribute docs]: https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html
+[the gcc inline docs]: https://gcc.gnu.org/onlinedocs/gcc/Inline.html
+[the microsoft docs on inline functions]: https://docs.microsoft.com/en-us/cpp/cpp/inline-functions-cpp
+
+
+### artificial
+
+{clang-attr-syntaxes}`ArtificialDocs`
+
+The `artificial` attribute can be applied to an inline function. If such a
+function is inlined, the attribute indicates that debuggers should associate
+the resulting instructions with the call site, rather than with the
+corresponding line within the inlined callee.
+
+
+### assert_capability, assert_shared_capability
+
+{clang-attr-syntaxes}`AssertCapabilityDocs`
+
+Marks a function that dynamically tests whether a capability is held, and halts
+the program if it is not held.
+
+
+### assume
+
+{clang-attr-syntaxes}`OMPAssumeDocs`
+
+Clang supports the `[[omp::assume("assumption")]]` attribute to
+provide additional information to the optimizer. The string-literal, here
+"assumption", will be attached to the function declaration such that later
+analysis and optimization passes can assume the "assumption" to hold.
+This is similar to {ref}`__builtin_assume <langext-__builtin_assume>` but
+instead of an expression that can be assumed to be non-zero, the assumption is
+expressed as a string and it holds for the entire function.
+
+A function can have multiple assume attributes and they propagate from prior
+declarations to later definitions. Multiple assumptions are aggregated into a
+single comma separated string. Thus, one can provide multiple assumptions via
+a comma separated string, i.a.,
+`[[omp::assume("assumption1,assumption2")]]`.
+
+While LLVM plugins might provide more assumption strings, the default LLVM
+optimization passes are aware of the following assumptions:
+
+```none
+"omp_no_openmp"
+"omp_no_openmp_routines"
+"omp_no_parallelism"
+"omp_no_openmp_constructs"
+```
+
+The OpenMP standard defines the meaning of OpenMP assumptions ("omp_XYZ" is
+spelled "XYZ" in the [OpenMP 5.1 Standard][openmp 5.1 standard]).
+
+[openmp 5.1 standard]: https://www.openmp.org/spec-html/5.1/openmpsu37.html#x56-560002.5.2
+
+
+### assume_aligned
+
+{clang-attr-syntaxes}`AssumeAlignedDocs`
+
+Use `__attribute__((assume_aligned(<alignment>[,<offset>]))` on a function
+declaration to specify that the return value of the function (which must be a
+pointer type) has the specified offset, in bytes, from an address with the
+specified alignment. The offset is taken to be zero if omitted.
+
+```c++
+// The returned pointer value has 32-byte alignment.
+void *a() __attribute__((assume_aligned (32)));
+
+// The returned pointer value is 4 bytes greater than an address having
+// 32-byte alignment.
+void *b() __attribute__((assume_aligned (32, 4)));
+```
+
+Note that this attribute provides information to the compiler regarding a
+condition that the code already ensures is true. It does not cause the compiler
+to enforce the provided alignment assumption.
+
+
+### availability
+
+{clang-attr-syntaxes}`AvailabilityDocs`
+
+The `availability` attribute can be placed on declarations to describe the
+lifecycle of that declaration relative to operating system versions. Consider
+the function declaration for a hypothetical function `f`:
+
+```c++
+void f(void) __attribute__((availability(macos,introduced=10.4,deprecated=10.6,obsoleted=10.7)));
+```
+
+The availability attribute states that `f` was introduced in macOS 10.4,
+deprecated in macOS 10.6, and obsoleted in macOS 10.7. This information
+is used by Clang to determine when it is safe to use `f`: for example, if
+Clang is instructed to compile code for macOS 10.5, a call to `f()`
+succeeds. If Clang is instructed to compile code for macOS 10.6, the call
+succeeds but Clang emits a warning specifying that the function is deprecated.
+Finally, if Clang is instructed to compile code for macOS 10.7, the call
+fails because `f()` is no longer available.
+
+Clang is instructed to compile code for a minimum deployment version using
+the `-target` or `-mtargetos` command line arguments. For example,
+macOS 10.7 would be specified as `-target x86_64-apple-macos10.7` or
+`-mtargetos=macos10.7`. Variants like Mac Catalyst are specified as
+`-target arm64-apple-ios15.0-macabi` or `-mtargetos=ios15.0-macabi`
+
+The availability attribute is a comma-separated list starting with the
+platform name and then including clauses specifying important milestones in the
+declaration's lifetime (in any order) along with additional information. Those
+clauses can be:
+
+introduced=*version*
+
+: The first version in which this declaration was introduced.
+
+deprecated=*version*
+
+: The first version in which this declaration was deprecated, meaning that
+ users should migrate away from this API.
+
+obsoleted=*version*
+
+: The first version in which this declaration was obsoleted, meaning that it
+ was removed completely and can no longer be used.
+
+unavailable
+
+: This declaration is never available on this platform.
+
+message=*string-literal*
+
+: Additional message text that Clang will provide when emitting a warning or
+ error about use of a deprecated or obsoleted declaration. Useful to direct
+ users to replacement APIs.
+
+replacement=*string-literal*
+
+: Additional message text that Clang will use to provide Fix-It when emitting
+ a warning about use of a deprecated declaration. The Fix-It will replace
+ the deprecated declaration with the new declaration specified.
+
+environment=*identifier*
+
+: Target environment in which this declaration is available. If present,
+ the availability attribute applies only to targets with the same platform
+ and environment. The parameter is currently supported only in HLSL.
+
+Multiple availability attributes can be placed on a declaration, which may
+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 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:
+
+`iOS`
+`macOS`
+`tvOS`
+`watchOS`
+`iOSApplicationExtension`
+`macOSApplicationExtension`
+`tvOSApplicationExtension`
+`watchOSApplicationExtension`
+`macCatalyst`
+`macCatalystApplicationExtension`
+`visionOS`
+`visionOSApplicationExtension`
+`driverkit`
+`anyAppleOS`
+`swift`
+`android`
+`fuchsia`
+`ohos`
+`zos`
+`ShaderModel`
+
+Some platforms have alias names:
+
+`ios`
+`macos`
+`macosx (deprecated)`
+`tvos`
+`watchos`
+`ios_app_extension`
+`macos_app_extension`
+`macosx_app_extension (deprecated)`
+`tvos_app_extension`
+`watchos_app_extension`
+`maccatalyst`
+`maccatalyst_app_extension`
+`visionos`
+`visionos_app_extension`
+`anyappleos`
+`shadermodel`
+
+Supported environment names for the ShaderModel platform:
+
+`pixel`
+`vertex`
+`geometry`
+`hull`
+`domain`
+`compute`
+`raygeneration`
+`intersection`
+`anyhit`
+`closesthit`
+`miss`
+`callable`
+`mesh`
+`amplification`
+`library`
+
+The special platform `anyAppleOS` (alias: `anyappleos`) is a shorthand that
+applies the availability attribute to all Apple Darwin platforms. An explicit
+platform-specific availability attribute takes precedence over an `anyAppleOS`
+attribute for that platform. Versions specified with `anyAppleOS` must be at
+least 26.0, which is the first OS release where all supported Apple platforms
+share a unified version number.
+
+A declaration can typically be used even when deploying back to a platform
+version prior to when the declaration was introduced. When this happens, the
+declaration is [weakly linked](https://developer.apple.com/library/mac/#documentation/MacOSX/Conceptual/BPFrameworks/Concepts/WeakLinking.html),
+as if the `weak_import` attribute were added to the declaration. A
+weakly-linked declaration may or may not be present a run-time, and a program
+can determine whether the declaration is present by checking whether the
+address of that declaration is non-NULL.
+
+The flag `strict` disallows using API when deploying back to a
+platform version prior to when the declaration was introduced. An
+attempt to use such API before its introduction causes a hard error.
+Weakly-linking is almost always a better API choice, since it allows
+users to query availability at runtime.
+
+If there are multiple declarations of the same entity, the availability
+attributes must either match on a per-platform basis or later
+declarations must not have availability attributes for that
+platform. For example:
+
+```c
+void g(void) __attribute__((availability(macos,introduced=10.4)));
+void g(void) __attribute__((availability(macos,introduced=10.4))); // okay, matches
+void g(void) __attribute__((availability(ios,introduced=4.0))); // okay, adds a new platform
+void g(void); // okay, inherits both macos and ios availability from above.
+void g(void) __attribute__((availability(macos,introduced=10.5))); // error: mismatch
+```
+
+When one method overrides another, the overriding method can be more widely available than the overridden method, e.g.,:
+
+```objc
+ at interface A
+- (id)method __attribute__((availability(macos,introduced=10.4)));
+- (id)method2 __attribute__((availability(macos,introduced=10.4)));
+ at end
+
+ at interface B : A
+- (id)method __attribute__((availability(macos,introduced=10.3))); // okay: method moved into base class later
+- (id)method __attribute__((availability(macos,introduced=10.5))); // error: this method was available via the base class in 10.4
+ at end
+```
+
+Starting with the macOS 10.12 SDK, the `API_AVAILABLE` macro from
+`<os/availability.h>` can simplify the spelling:
+
+```objc
+ at interface A
+- (id)method API_AVAILABLE(macos(10.11)));
+- (id)otherMethod API_AVAILABLE(macos(10.11), ios(11.0));
+ at end
+```
+
+Availability attributes can also be applied using a `#pragma clang attribute`.
+Any explicit availability attribute whose platform corresponds to the target
+platform is applied to a declaration regardless of the availability attributes
+specified in the pragma. For example, in the code below,
+`hasExplicitAvailabilityAttribute` will use the `macOS` availability
+attribute that is specified with the declaration, whereas
+`getsThePragmaAvailabilityAttribute` will use the `macOS` availability
+attribute that is applied by the pragma.
+
+```c
+#pragma clang attribute push (__attribute__((availability(macOS, introduced=10.12))), apply_to=function)
+void getsThePragmaAvailabilityAttribute(void);
+void hasExplicitAvailabilityAttribute(void) __attribute__((availability(macos,introduced=10.4)));
+#pragma clang attribute pop
+```
+
+For platforms like `watchOS` and `tvOS`, whose availability attributes can
+be implicitly inferred from an `iOS` availability attribute, the logic is
+slightly more complex. The explicit and the pragma-applied availability
+attributes whose platform corresponds to the target platform are applied as
+described in the previous paragraph. However, the implicitly inferred attributes
+are applied to a declaration only when there is no explicit or pragma-applied
+availability attribute whose platform corresponds to the target platform. For
+example, the function below will receive the `tvOS` availability from the
+pragma rather than using the inferred `iOS` availability from the declaration:
+
+```c
+#pragma clang attribute push (__attribute__((availability(tvOS, introduced=12.0))), apply_to=function)
+void getsThePragmaTVOSAvailabilityAttribute(void) __attribute__((availability(iOS,introduced=11.0)));
+#pragma clang attribute pop
+```
+
+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:
+
+```c
+#pragma clang attribute push (__attribute__((availability(iOS, introduced=12.0))), apply_to=function)
+void infersTVOSAvailabilityFromPragma(void);
+#pragma clang attribute pop
+```
+
+The implicit attributes that are inferred from explicitly specified attributes
+whose platform corresponds to the target platform are applied to the declaration
+even if there is an availability attribute that can be inferred from a pragma.
+For example, the function below will receive the `tvOS, introduced=11.0`
+availability that is inferred from the attribute on the declaration rather than
+inferring availability from the pragma:
+
+```c
+#pragma clang attribute push (__attribute__((availability(iOS, unavailable))), apply_to=function)
+void infersTVOSAvailabilityFromAttributeNextToDeclaration(void)
+ __attribute__((availability(iOS,introduced=11.0)));
+#pragma clang attribute pop
+```
+
+Also see the documentation for
+{ref}`@available <langext-objective-c-available>`
+
+
+### btf_decl_tag
+
+{clang-attr-syntaxes}`BTFDeclTagDocs`
+
+Clang supports the `__attribute__((btf_decl_tag("ARGUMENT")))` attribute for
+all targets. This attribute may be attached to a struct/union, struct/union
+field, function, function parameter, variable or typedef declaration. If -g is
+specified, the `ARGUMENT` info will be preserved in IR and be emitted to
+dwarf. For BPF targets, the `ARGUMENT` info will be emitted to .BTF ELF
+section too.
+
+
+### callback
+
+{clang-attr-syntaxes}`CallbackDocs`
+
+The `callback` attribute specifies that the annotated function may invoke the
+specified callback zero or more times. The callback, as well as the passed
+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
+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
+not present in the declared parameter list, or one that is, but is potentially
+inspected, captured, or modified. Parameter names and indices can be mixed in
+the callback attribute.
+
+The `callback` attribute, which is directly translated to `callback`
+metadata (<http://llvm.org/docs/LangRef.html#callback-metadata>), make the
+connection between the call to the annotated function and the callback callee.
+This can enable interprocedural optimizations which were otherwise impossible.
+If a function parameter is mentioned in the `callback` attribute, through its
+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
+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
+automatically recognized as broker functions. Further functions might be added
+in the future.
+
+```c
+__attribute__((callback (start_routine, arg)))
+int pthread_create(pthread_t *thread, const pthread_attr_t *attr,
+ void *(*start_routine) (void *), void *arg);
+
+__attribute__((callback (3, 4)))
+int pthread_create(pthread_t *thread, const pthread_attr_t *attr,
+ void *(*start_routine) (void *), void *arg);
+```
+
+
+### cf_consumed, cf_returns_not_retained, cf_returns_retained, ns_consumed, ns_consumes_self, ns_returns_autoreleased, ns_returns_not_retained, ns_returns_retained, os_consumed, os_consumes_this, os_returns_not_retained, os_returns_retained, os_returns_retained_on_non_zero, os_returns_retained_on_zero
+
+{clang-attr-syntaxes}`RetainBehaviorDocs`
+
+The behavior of a function with respect to reference counting for Foundation
+(Objective-C), CoreFoundation (C) and OSObject (C++) is determined by a naming
+convention (e.g. functions starting with "get" are assumed to return at
+`+0`).
+
+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.
+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
+the Objective-C method call consumes the reference to `self`, e.g. by
+attaching it to a supplied parameter.
+Additionally, parameters can have an annotation
+`__attribute__((ns_consumed))`, which specifies that passing an owned object
+as that parameter effectively transfers the ownership, and the caller is no
+longer responsible for it.
+These attributes affect code generation when interacting with ARC code, and
+they are used by the Clang Static Analyzer.
+
+In C programs using CoreFoundation, a similar set of attributes:
+`__attribute__((cf_returns_not_retained))`,
+`__attribute__((cf_returns_retained))` and `__attribute__((cf_consumed))`
+have the same respective semantics when applied to CoreFoundation objects.
+These attributes affect code generation when interacting with ARC code, and
+they are used by the Clang Static Analyzer.
+
+(os-retained-attr-family)=
+
+Finally, in C++ interacting with XNU kernel (objects inheriting from OSObject),
+the same attribute family is present:
+`__attribute__((os_returns_not_retained))`,
+`__attribute__((os_returns_retained))` and `__attribute__((os_consumed))`,
+with the same respective semantics.
+Similar to `__attribute__((ns_consumes_self))`,
+`__attribute__((os_consumes_this))` specifies that the method call consumes
+the reference to "this" (e.g., when attaching it to a different object supplied
+as a parameter).
+Out parameters (parameters the function is meant to write into,
+either via pointers-to-pointers or references-to-pointers)
+may be annotated with `__attribute__((os_returns_retained))`
+or `__attribute__((os_returns_not_retained))` which specifies that the object
+written into the out parameter should (or respectively should not) be released
+after use.
+Since often out parameters may or may not be written depending on the exit
+code of the function,
+annotations `__attribute__((os_returns_retained_on_zero))`
+and `__attribute__((os_returns_retained_on_non_zero))` specify that
+an out parameter at `+1` is written if and only if the function returns a zero
+(respectively non-zero) error code.
+Observe that return-code-dependent out parameter annotations are only
+available for retained out parameters, as non-retained object do not have to be
+released by the callee.
+These attributes are only used by the Clang Static Analyzer.
+
+The family of attributes `X_returns_X_retained` can be added to functions,
+C++ methods, and Objective-C methods and properties.
+Attributes `X_consumed` can be added to parameters of methods, functions,
+and Objective-C methods.
+
+
+(langext-cfi_canonical_jump_table)=
+
+### cfi_canonical_jump_table
+
+{clang-attr-syntaxes}`CFICanonicalJumpTableDocs`
+
+Use `__attribute__((cfi_canonical_jump_table))` on a function declaration to
+make the function's CFI jump table canonical. See {ref}`the CFI documentation
+<cfi-canonical-jump-tables>` for more details.
+
+
+(langext-cfi_salt)=
+
+### cfi_salt
+
+{clang-attr-syntaxes}`CFISaltDocs`
+
+The `cfi_salt` attribute specifies a string literal that is used as a salt
+for Control-Flow Integrity (CFI) checks to distinguish between functions with
+the same type signature. This attribute can be applied to function declarations,
+function definitions, and function pointer typedefs.
+
+The attribute prevents function pointers from being replaced with pointers to
+functions that have a compatible type, which can be a CFI bypass vector.
+
+**Syntax:**
+
+- GNU-style: `__attribute__((cfi_salt("<salt_string>")))`
+- C++11-style: `[[clang::cfi_salt("<salt_string>")]]`
+
+**Usage:**
+
+The attribute takes a single string literal argument that serves as the salt.
+Functions or function types with different salt values will have different CFI
+hashes, even if they have identical type signatures.
+
+**Motivation:**
+
+In large codebases like the Linux kernel, there are often hundreds of functions
+with identical type signatures that are called indirectly:
+
+```
+1662 functions with void (*)(void)
+1179 functions with int (*)(void)
+ ...
+```
+
+By salting the CFI hashes, you can make CFI more robust by ensuring that
+functions intended for different purposes have distinct CFI identities.
+
+**Type Compatibility:**
+
+- Functions with different salt values are considered to have incompatible types
+- Function pointers with different salt values cannot be assigned to each other
+- All declarations of the same function must use the same salt value
+
+**Example:**
+
+```c
+// Header file - define convenience macros
+#define __cfi_salt(s) __attribute__((cfi_salt(s)))
+
+// Typedef for regular function pointers
+typedef int (*fptr_t)(void);
+
+// Typedef for salted function pointers
+typedef int (*fptr_salted_t)(void) __cfi_salt("pepper");
+
+struct widget_ops {
+ fptr_t init; // Regular CFI
+ fptr_salted_t exec; // Salted CFI
+ fptr_t cleanup; // Regular CFI
+};
+
+// Function implementations
+static int widget_init(void) { return 0; }
+static int widget_exec(void) __cfi_salt("pepper") { return 1; }
+static int widget_cleanup(void) { return 0; }
+
+static struct widget_ops ops = {
+ .init = widget_init, // OK - compatible types
+ .exec = widget_exec, // OK - both use "pepper" salt
+ .cleanup = widget_cleanup // OK - compatible types
+};
+
+// Using C++11 attribute syntax
+void secure_callback(void) [[clang::cfi_salt("secure")]];
+
+// This would cause a compilation error:
+// fptr_t bad_ptr = widget_exec; // Error: incompatible types
+```
+
+**Notes:**
+
+- The salt string can contain non-NULL ASCII characters, including spaces and
+ quotes
+- This attribute only applies to function types; using it on non-function
+ types will generate a warning
+- All declarations and definitions of the same function must use identical
+ salt values
+- The attribute affects type compatibility during compilation and CFI hash
+ generation during code generation
+
+
+### clang::builtin_alias, clang_builtin_alias
+
+{clang-attr-syntaxes}`BuiltinAliasDocs`
+
+This attribute is used in the implementation of the C intrinsics.
+It allows the C intrinsic functions to be declared using the names defined
+in target builtins, and still be recognized as clang builtins equivalent to the
+underlying name. For example, `riscv_vector.h` declares the function `vadd`
+with `__attribute__((clang_builtin_alias(__builtin_rvv_vadd_vv_i8m1)))`.
+This ensures that both functions are 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 certain ARM/RISC-V
+C intrinsic functions; it is intended for use only inside `arm_*.h` and
+`riscv_*.h` and is not a general mechanism for declaring arbitrary aliases
+for clang builtin functions.
+
+
+### clang_arm_builtin_alias
+
+{clang-attr-syntaxes}`ArmBuiltinAliasDocs`
+
+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
+`__attribute__((__clang_arm_mve_alias(__builtin_arm_mve_vaddq_u32)))`,
+and similarly, one of the type-overloaded declarations of `vaddq`
+will have the same attribute. This ensures that both functions are
+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 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.
+
+In order to avoid duplicating the attribute definitions for similar
+purpose for other architecture, there is a general form for the
+attribute `clang_builtin_alias`.
+
+
+### clspv_libclc_builtin
+
+{clang-attr-syntaxes}`ClspvLibclcBuiltinDoc`
+
+Attribute used by [clspv][clspv] (OpenCL-C to Vulkan SPIR-V compiler) to identify functions coming from [libclc][libclc] (OpenCL-C builtin library).
+
+```c
+void __attribute__((clspv_libclc_builtin)) libclc_builtin() {}
+```
+
+[clspv]: https://github.com/google/clspv
+[libclc]: https://libclc.llvm.org
+
+
+### cmse_nonsecure_entry
+
+{clang-attr-syntaxes}`ArmCmseNSEntryDocs`
+
+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.
+
+
+### code_seg
+
+{clang-attr-syntaxes}`CodeSegDocs`
+
+The `__declspec(code_seg)` attribute enables the placement of code into separate
+named segments that can be paged or locked in memory individually. This attribute
+is used to control the placement of instantiated templates and compiler-generated
+code. See the documentation for [`__declspec(code_seg)`][__declspec(code_seg)] on MSDN.
+
+[__declspec(code_seg)]: http://msdn.microsoft.com/en-us/library/dn636922.aspx
+
+
+### cold
+
+{clang-attr-syntaxes}`ColdFunctionEntryDocs`
+
+`__attribute__((cold))` marks a function as cold, as a manual alternative to PGO hotness data.
+If PGO data is available, the profile count based hotness overrides the `__attribute__((cold))` annotation (unlike `__attribute__((hot))`).
+
+
+### constant_id
+
+{clang-attr-syntaxes}`VkConstantIdDocs`
+
+The `vk::constant_id` attribute specifies the id for a SPIR-V specialization
+constant. The attribute applies to const global scalar variables. The variable must be initialized with a C++11 constexpr.
+In SPIR-V, the
+variable will be replaced with an `OpSpecConstant` with the given id.
+The syntax is:
+
+```text
+[[vk::constant_id(<Id>)]] const T Name = <Init>
+```
+
+
+### constructor, destructor
+
+{clang-attr-syntaxes}`CtorDtorDocs`
+
+The `constructor` attribute causes the function to be called before entering
+`main()`, and the `destructor` attribute causes the function to be called
+after returning from `main()` or when the `exit()` function has been
+called. Note, `quick_exit()`, `_Exit()`, and `abort()` prevent a function
+marked `destructor` from being called.
+
+The constructor or destructor function should not accept any arguments and its
+return type should be `void`.
+
+The attributes accept an optional argument used to specify the priority order
+in which to execute constructor and destructor functions. The priority is
+given as an integer constant expression between 101 and 65535 (inclusive).
+Priorities outside of that range are reserved for use by the implementation. A
+lower value indicates a higher priority of initialization. Note that only the
+relative ordering of values is important. For example:
+
+```c++
+__attribute__((constructor(200))) void foo(void);
+__attribute__((constructor(101))) void bar(void);
+```
+
+`bar()` will be called before `foo()`, and both will be called before
+`main()`. If no argument is given to the `constructor` or `destructor`
+attribute, they default to the value `65535`.
+
+
+### convergent
+
+{clang-attr-syntaxes}`ConvergentDocs`
+
+The `convergent` attribute can be placed on a function declaration. It is
+translated into the LLVM `convergent` attribute, which indicates that the call
+instructions of a function with this attribute cannot be made control-dependent
+on any additional values.
+
+This attribute is different from `noduplicate` because it allows duplicating
+function calls if it can be proved that the duplicated function calls are
+not made control-dependent on any additional values, e.g., unrolling a loop
+executed by all work items.
+
+Sample usage:
+
+```c
+void convfunc(void) __attribute__((convergent));
+// Setting it as a C++11 attribute is also valid in a C++ program.
+// void convfunc(void) [[clang::convergent]];
+```
+
+
+### cpu_dispatch, cpu_specific
+
+{clang-attr-syntaxes}`CPUSpecificCPUDispatchDocs`
+
+The `cpu_specific` and `cpu_dispatch` attributes are used to define and
+resolve multiversioned functions. This form of multiversioning provides a
+mechanism for declaring versions across translation units and manually
+specifying the resolved function list. A specified CPU defines a set of minimum
+features that are required for the function to be called. The result of this is
+that future processors execute the most restrictive version of the function the
+new processor can execute.
+
+In addition, unlike the ICC implementation of this feature, the selection of the
+version does not consider the manufacturer or microarchitecture of the processor.
+It tests solely the list of features that are both supported by the specified
+processor and present in the compiler-rt library. This can be surprising at times,
+as the runtime processor may be from a completely different manufacturer, as long
+as it supports the same feature set.
+
+This can additionally be surprising, as some processors are indistringuishable from
+others based on the list of testable features. When this happens, the variant
+is selected in an unspecified manner.
+
+Function versions are defined with `cpu_specific`, which takes one or more CPU
+names as a parameter. For example:
+
+```c
+// Declares and defines the ivybridge version of single_cpu.
+__attribute__((cpu_specific(ivybridge)))
+void single_cpu(void){}
+
+// Declares and defines the atom version of single_cpu.
+__attribute__((cpu_specific(atom)))
+void single_cpu(void){}
+
+// Declares and defines both the ivybridge and atom version of multi_cpu.
+__attribute__((cpu_specific(ivybridge, atom)))
+void multi_cpu(void){}
+```
+
+A dispatching (or resolving) function can be declared anywhere in a project's
+source code with `cpu_dispatch`. This attribute takes one or more CPU names
+as a parameter (like `cpu_specific`). Functions marked with `cpu_dispatch`
+are not expected to be defined, only declared. If such a marked function has a
+definition, any side effects of the function are ignored; trivial function
+bodies are permissible for ICC compatibility.
+
+```c
+// Creates a resolver for single_cpu above.
+__attribute__((cpu_dispatch(ivybridge, atom)))
+void single_cpu(void){}
+
+// Creates a resolver for multi_cpu, but adds a 3rd version defined in another
+// translation unit.
+__attribute__((cpu_dispatch(ivybridge, atom, sandybridge)))
+void multi_cpu(void){}
+```
+
+Note that it is possible to have a resolving function that dispatches based on
+more or fewer options than are present in the program. Specifying fewer will
+result in the omitted options not being considered during resolution. Specifying
+a version for resolution that isn't defined in the program will result in a
+linking failure.
+
+It is also possible to specify a CPU name of `generic` which will be resolved
+if the executing processor doesn't satisfy the features required in the CPU
+name. The behavior of a program executing on a processor that doesn't satisfy
+any option of a multiversioned function is undefined.
+
+
+### device_kernel, nvptx_kernel, amdgpu_kernel, kernel, __kernel
+
+{clang-attr-syntaxes}`DeviceKernelDocs`
+
+These attributes specify that the function represents a kernel for device offloading.
+The specific semantics depend on the offloading language, target, and attribute spelling.
+Here is a code example using the attribute to mark a function as a kernel:
+
+```c++
+[[clang::device_kernel]] int foo(int x) { return ++x; }
+```
+
+
+### diagnose_as_builtin
+
+{clang-attr-syntaxes}`DiagnoseAsBuiltinDocs`
+
+The `diagnose_as_builtin` attribute indicates that Fortify diagnostics are to
+be applied to the declared function as if it were the function specified by the
+attribute. The builtin function whose diagnostics are to be mimicked should be
+given. In addition, the order in which arguments should be applied must also
+be given.
+
+For example, the attribute can be used as follows.
+
+```c
+__attribute__((diagnose_as_builtin(__builtin_memset, 3, 2, 1)))
+void *mymemset(int n, int c, void *s) {
+ // ...
+}
+```
+
+This indicates that calls to `mymemset` should be diagnosed as if they were
+calls to `__builtin_memset`. The arguments `3, 2, 1` indicate by index the
+order in which arguments of `mymemset` should be applied to
+`__builtin_memset`. The third argument should be applied first, then the
+second, and then the first. Thus (when Fortify warnings are enabled) the call
+`mymemset(n, c, s)` will diagnose overflows as if it were the call
+`__builtin_memset(s, c, n)`.
+
+For variadic functions, the variadic arguments must come in the same order as
+they would to the builtin function, after all normal arguments. For instance,
+to diagnose a new function as if it were `sscanf`, we can use the attribute as
+follows.
+
+```c
+__attribute__((diagnose_as_builtin(sscanf, 1, 2)))
+int mysscanf(const char *str, const char *format, ...) {
+ // ...
+}
+```
+
+Then the call `mysscanf("abc def", "%4s %4s", buf1, buf2)` will be diagnosed as
+if it were the call `sscanf("abc def", "%4s %4s", buf1, buf2)`.
+
+This attribute cannot be applied to non-static member functions.
+
+
+### diagnose_if
+
+{clang-attr-syntaxes}`DiagnoseIfDocs`
+
+The `diagnose_if` attribute can be placed on function declarations to emit
+warnings or errors at compile-time if calls to the attributed function meet
+certain user-defined criteria. For example:
+
+```c
+int abs(int a)
+ __attribute__((diagnose_if(a >= 0, "Redundant abs call", "warning")));
+int must_abs(int a)
+ __attribute__((diagnose_if(a >= 0, "Redundant abs call", "error")));
+
+int val = abs(1); // warning: Redundant abs call
+int val2 = must_abs(1); // error: Redundant abs call
+int val3 = abs(val);
+int val4 = must_abs(val); // Because run-time checks are not emitted for
+ // diagnose_if attributes, this executes without
+ // issue.
+```
+
+`diagnose_if` is closely related to `enable_if`, with a few key differences:
+
+- Overload resolution is not aware of `diagnose_if` attributes: they're
+ considered only after we select the best candidate from a given candidate set.
+- Function declarations that differ only in their `diagnose_if` attributes are
+ considered to be redeclarations of the same function (not overloads).
+- If the condition provided to `diagnose_if` cannot be evaluated, no
+ diagnostic will be emitted.
+
+Otherwise, `diagnose_if` is essentially the logical negation of `enable_if`.
+
+As a result of bullet number two, `diagnose_if` attributes will stack on the
+same function. For example:
+
+```c
+int foo() __attribute__((diagnose_if(1, "diag1", "warning")));
+int foo() __attribute__((diagnose_if(1, "diag2", "warning")));
+
+int bar = foo(); // warning: diag1
+ // warning: diag2
+int (*fooptr)(void) = foo; // warning: diag1
+ // warning: diag2
+
+constexpr int supportsAPILevel(int N) { return N < 5; }
+int baz(int a)
+ __attribute__((diagnose_if(!supportsAPILevel(10),
+ "Upgrade to API level 10 to use baz", "error")));
+int baz(int a)
+ __attribute__((diagnose_if(!a, "0 is not recommended.", "warning")));
+
+int (*bazptr)(int) = baz; // error: Upgrade to API level 10 to use baz
+int v = baz(0); // error: Upgrade to API level 10 to use baz
+```
+
+Query for this feature with `__has_attribute(diagnose_if)`.
+
+
+### disable_sanitizer_instrumentation
+
+{clang-attr-syntaxes}`DisableSanitizerInstrumentationDocs`
+
+Use the `disable_sanitizer_instrumentation` attribute on a function,
+Objective-C method, or global variable, to specify that no sanitizer
+instrumentation should be applied.
+
+This is not the same as `__attribute__((no_sanitize(...)))`, which depending
+on the tool may still insert instrumentation to prevent false positive reports.
+
+
+### disable_tail_calls
+
+{clang-attr-syntaxes}`DisableTailCallsDocs`
+
+The `disable_tail_calls` attribute instructs the backend to not perform tail
+call optimization inside the marked function.
+
+For example:
+
+```c
+int callee(int);
+
+int foo(int a) __attribute__((disable_tail_calls)) {
+ return callee(a); // This call is not tail-call optimized.
+}
+```
+
+Marking virtual functions as `disable_tail_calls` is legal.
+
+```c++
+int callee(int);
+
+class Base {
+public:
+ [[clang::disable_tail_calls]] virtual int foo1() {
+ return callee(); // This call is not tail-call optimized.
+ }
+};
+
+class Derived1 : public Base {
+public:
+ int foo1() override {
+ return callee(); // This call is tail-call optimized.
+ }
+};
+```
+
+
+### enable_if
+
+{clang-attr-syntaxes}`EnableIfDocs`
+
+:::{Note}
+Some features of this attribute are experimental. The meaning of
+multiple enable_if attributes on a single declaration is subject to change in
+a future version of clang. Also, the ABI is not standardized and the name
+mangling may change in future versions. To avoid that, use asm labels.
+:::
+
+The `enable_if` attribute can be placed on function declarations to control
+which overload is selected based on the values of the function's arguments.
+When combined with the `overloadable` attribute, this feature is also
+available in C.
+
+```c++
+int isdigit(int c);
+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")));
+
+void foo(char c) {
+ isdigit(c);
+ isdigit(10);
+ isdigit(-10); // results in a compile-time error.
+}
+```
+
+The enable_if attribute takes two arguments, the first is an expression written
+in terms of the function parameters, the second is a string explaining why this
+overload candidate could not be selected to be displayed in diagnostics. The
+expression is part of the function signature for the purposes of determining
+whether it is a redeclaration (following the rules used when determining
+whether a C++ template specialization is ODR-equivalent), but is not part of
+the type.
+
+The enable_if expression is evaluated as if it were the body of a
+bool-returning constexpr function declared with the arguments of the function
+it is being applied to, then called with the parameters at the call site. If the
+result is false or could not be determined through constant expression
+evaluation, then this overload will not be chosen and the provided string may
+be used in a diagnostic if the compile fails as a result.
+
+Because the enable_if expression is an unevaluated context, there are no global
+state changes, nor the ability to pass information from the enable_if
+expression to the function body. For example, suppose we want calls to
+strnlen(strbuf, maxlen) to resolve to strnlen_chk(strbuf, maxlen, size of
+strbuf) only if the size of strbuf can be determined:
+
+```c++
+__attribute__((always_inline))
+static inline size_t strnlen(const char *s, size_t maxlen)
+ __attribute__((overloadable))
+ __attribute__((enable_if(__builtin_object_size(s, 0) != -1))),
+ "chosen when the buffer size is known but 'maxlen' is not")))
+{
+ return strnlen_chk(s, maxlen, __builtin_object_size(s, 0));
+}
+```
+
+Multiple enable_if attributes may be applied to a single declaration. In this
+case, the enable_if expressions are evaluated from left to right in the
+following manner. First, the candidates whose enable_if expressions evaluate to
+false or cannot be evaluated are discarded. If the remaining candidates do not
+share ODR-equivalent enable_if expressions, the overload resolution is
+ambiguous. Otherwise, enable_if overload resolution continues with the next
+enable_if attribute on the candidates that have not been discarded and have
+remaining enable_if attributes. In this way, we pick the most specific
+overload out of a number of viable overloads using enable_if.
+
+```c++
+void f() __attribute__((enable_if(true, ""))); // #1
+void f() __attribute__((enable_if(true, ""))) __attribute__((enable_if(true, ""))); // #2
+
+void g(int i, int j) __attribute__((enable_if(i, ""))); // #1
+void g(int i, int j) __attribute__((enable_if(j, ""))) __attribute__((enable_if(true))); // #2
+```
+
+In this example, a call to f() is always resolved to #2, as the first enable_if
+expression is ODR-equivalent for both declarations, but #1 does not have another
+enable_if expression to continue evaluating, so the next round of evaluation has
+only a single candidate. In a call to g(1, 1), the call is ambiguous even though
+#2 has more enable_if attributes, because the first enable_if expressions are
+not ODR-equivalent.
+
+Query for this feature with `__has_attribute(enable_if)`.
+
+Note that functions with one or more `enable_if` attributes may not have
+their address taken, unless all of the conditions specified by said
+`enable_if` are constants that evaluate to `true`. For example:
+
+```c
+const int TrueConstant = 1;
+const int FalseConstant = 0;
+int f(int a) __attribute__((enable_if(a > 0, "")));
+int g(int a) __attribute__((enable_if(a == 0 || a != 0, "")));
+int h(int a) __attribute__((enable_if(1, "")));
+int i(int a) __attribute__((enable_if(TrueConstant, "")));
+int j(int a) __attribute__((enable_if(FalseConstant, "")));
+
+void fn() {
+ int (*ptr)(int);
+ ptr = &f; // error: 'a > 0' is not always true
+ ptr = &g; // error: 'a == 0 || a != 0' is not a truthy constant
+ ptr = &h; // OK: 1 is a truthy constant
+ ptr = &i; // OK: 'TrueConstant' is a truthy constant
+ ptr = &j; // error: 'FalseConstant' is a constant, but not truthy
+}
+```
+
+Because `enable_if` evaluation happens during overload resolution,
+`enable_if` may give unintuitive results when used with templates, depending
+on when overloads are resolved. In the example below, clang will emit a
+diagnostic about no viable overloads for `foo` in `bar`, but not in `baz`:
+
+```c++
+double foo(int i) __attribute__((enable_if(i > 0, "")));
+void *foo(int i) __attribute__((enable_if(i <= 0, "")));
+template <int I>
+auto bar() { return foo(I); }
+
+template <typename T>
+auto baz() { return foo(T::number); }
+
+struct WithNumber { constexpr static int number = 1; };
+void callThem() {
+ bar<sizeof(WithNumber)>();
+ baz<WithNumber>();
+}
+```
+
+This is because, in `bar`, `foo` is resolved prior to template
+instantiation, so the value for `I` isn't known (thus, both `enable_if`
+conditions for `foo` fail). However, in `baz`, `foo` is resolved during
+template instantiation, so the value for `T::number` is known.
+
+
+### enforce_tcb
+
+{clang-attr-syntaxes}`EnforceTCBDocs`
+
+The `enforce_tcb` attribute can be placed on functions to enforce that a
+trusted compute base (TCB) does not call out of the TCB. This generates a
+warning every time a function not marked with an `enforce_tcb` attribute is
+called from a function with the `enforce_tcb` attribute. A function may be a
+part of multiple TCBs. Invocations through function pointers are currently
+not checked. Builtins are considered to a part of every TCB.
+
+- `enforce_tcb(Name)` indicates that this function is a part of the TCB named `Name`
+
+
+### enforce_tcb_leaf
+
+{clang-attr-syntaxes}`EnforceTCBLeafDocs`
+
+The `enforce_tcb_leaf` attribute satisfies the requirement enforced by
+`enforce_tcb` for the marked function to be in the named TCB but does not
+continue to check the functions called from within the leaf function.
+
+- `enforce_tcb_leaf(Name)` indicates that this function is a part of the TCB named `Name`
+
+
+### error, warning
+
+{clang-attr-syntaxes}`ErrorAttrDocs`
+
+The `error` and `warning` function attributes can be used to specify a
+custom diagnostic to be emitted when a call to such a function is not
+eliminated via optimizations. This can be used to create compile time
+assertions that depend on optimizations, while providing diagnostics
+pointing to precise locations of the call site in the source.
+
+```c++
+__attribute__((warning("oh no"))) void dontcall();
+void foo() {
+ if (someCompileTimeAssertionThatsTrue)
+ dontcall(); // Warning
+
+ dontcall(); // Warning
+
+ if (someCompileTimeAssertionThatsFalse)
+ dontcall(); // No Warning
+ sizeof(dontcall()); // No Warning
+}
+```
+
+When the call occurs through inlined functions, the
+`-fdiagnostics-show-inlining-chain` option can be used to show the
+inlining chain that led to the call. This helps identify which call site
+triggered the diagnostic when the attributed function is called from
+multiple locations through inline functions.
+
+When enabled, this option automatically uses debug info for accurate source
+locations if available (`-gline-directives-only` (implicitly enabled at
+`-g1`) or higher), or falls back to a heuristic based on metadata tracking.
+When falling back, a note is emitted suggesting `-gline-directives-only` for
+more accurate locations.
+
+
+### exclude_from_explicit_instantiation
+
+{clang-attr-syntaxes}`ExcludeFromExplicitInstantiationDocs`
+
+The `exclude_from_explicit_instantiation` attribute opts-out a member of a
+class template from being part of explicit template instantiations of that
+class template. This means that an explicit instantiation will not instantiate
+members of the class template marked with the attribute, but also that code
+where an extern template declaration of the enclosing class template is visible
+will not take for granted that an external instantiation of the class template
+would provide those members (which would otherwise be a link error, since the
+explicit instantiation won't provide those members). For example, let's say we
+don't want the `data()` method to be part of libc++'s ABI. To make sure it
+is not exported from the dylib, we give it hidden visibility:
+
+```c++
+// in <string>
+template <class CharT>
+class basic_string {
+public:
+ __attribute__((__visibility__("hidden")))
+ const value_type* data() const noexcept { ... }
+};
+
+template class basic_string<char>;
+```
+
+Since an explicit template instantiation declaration for `basic_string<char>`
+is provided, the compiler is free to assume that `basic_string<char>::data()`
+will be provided by another translation unit, and it is free to produce an
+external call to this function. However, since `data()` has hidden visibility
+and the explicit template instantiation is provided in a shared library (as
+opposed to simply another translation unit), `basic_string<char>::data()`
+won't be found and a link error will ensue. This happens because the compiler
+assumes that `basic_string<char>::data()` is part of the explicit template
+instantiation declaration, when it really isn't. To tell the compiler that
+`data()` is not part of the explicit template instantiation declaration, the
+`exclude_from_explicit_instantiation` attribute can be used:
+
+```c++
+// in <string>
+template <class CharT>
+class basic_string {
+public:
+ __attribute__((__visibility__("hidden")))
+ __attribute__((exclude_from_explicit_instantiation))
+ const value_type* data() const noexcept { ... }
+};
+
+template class basic_string<char>;
+```
+
+Now, the compiler won't assume that `basic_string<char>::data()` is provided
+externally despite there being an explicit template instantiation declaration:
+the compiler will implicitly instantiate `basic_string<char>::data()` in the
+TUs where it is used.
+
+This attribute can be used on static and non-static member functions of class
+templates, static data members of class templates and member classes of class
+templates.
+
+**Interaction with `__declspec(dllexport)` and `__declspec(dllimport)`**
+
+For a DLL platform (i.e., Windows), this attribute also means "this member will
+never be exported or imported". Despite its name, this semantics applies to
+implicit instantiations and non-template entities as well.
+
+```c++
+// in <exception>
+class __declspec(dllimport) nested_exception {
+ ...
+public:
+ __attribute__((exclude_from_explicit_instantiation))
+ exception_ptr nested_ptr() const noexcept { ... }
+};
+```
+
+In this case, `nested_exception::nested_ptr` will never be attempted to be
+imported.
+
+
+### export_name, __funcref
+
+{clang-attr-syntaxes}`WebAssemblyExportNameDocs`
+
+Clang supports the `__attribute__((export_name(<name>)))`
+attribute for the WebAssembly target. This attribute may be attached to a
+function declaration, where it modifies how the symbol is to be exported
+from the linked WebAssembly.
+
+WebAssembly functions are exported via string name. By default when a symbol
+is exported, the export name for C/C++ symbols are the same as their C/C++
+symbol names. This attribute can be used to override the default behavior, and
+request a specific string name be used instead.
+
+
+### ext_vector_type
+
+{clang-attr-syntaxes}`ExtVectorTypeDocs`
+
+The `ext_vector_type(N)` attribute specifies that a type is a vector with N
+elements, directly mapping to an LLVM vector type. Originally from OpenCL, it
+allows element access the array subscript operator `[]`, `sN` where N is
+a hexadecimal value, or `x, y, z, w` for graphics-style indexing.
+This attribute enables efficient SIMD operations and is usable in
+general-purpose code.
+
+```c++
+template <typename T, uint32_t N>
+constexpr T simd_reduce(T [[clang::ext_vector_type(N)]] v) {
+ static_assert((N & (N - 1)) == 0, "N must be a power of two");
+ if constexpr (N == 1)
+ return v[0];
+ else
+ return simd_reduce<T, N / 2>(v.hi + v.lo);
+}
+```
+
+The vector type also supports swizzling up to sixteen elements. This can be done
+using the object accessors. The OpenCL documentation lists all of the accepted
+values.
+
+```c++
+using f16_x16 = _Float16 __attribute__((ext_vector_type(16)));
+
+f16_x16 reverse(f16_x16 v) { return v.sfedcba9876543210; }
+```
+
+See the OpenCL documentation for some more complete examples.
+
+
+### flatten
+
+{clang-attr-syntaxes}`FlattenDocs`
+
+The `flatten` attribute causes calls within the attributed function to
+be inlined unless it is impossible to do so, for example if the body of the
+callee is unavailable or if the callee has the `noinline` attribute.
+
+
+### force_align_arg_pointer
+
+{clang-attr-syntaxes}`X86ForceAlignArgPointerDocs`
+
+Use this attribute to force stack alignment.
+
+Legacy x86 code uses 4-byte stack alignment. Newer aligned SSE instructions
+(like 'movaps') that work with the stack require operands to be 16-byte aligned.
+This attribute realigns the stack in the function prologue to make sure the
+stack can be used with SSE instructions.
+
+Note that the x86_64 ABI forces 16-byte stack alignment at the call site.
+Because of this, 'force_align_arg_pointer' is not needed on x86_64, except in
+rare cases where the caller does not align the stack properly (e.g. flow
+jumps from i386 arch code).
+
+```c
+__attribute__ ((force_align_arg_pointer))
+void f () {
+ ...
+}
+```
+
+
+### format
+
+{clang-attr-syntaxes}`FormatDocs`
+
+Clang supports the `format` attribute, which indicates that the function
+accepts (among other possibilities) a `printf` or `scanf`-like format string
+and corresponding arguments or a `va_list` that contains these arguments.
+
+Please see [GCC documentation about format attribute](http://gcc.gnu.org/onlinedocs/gcc/Function-Attributes.html) to find details
+about attribute syntax.
+
+Clang implements two kinds of checks with this attribute.
+
+1. Clang checks that the function with the `format` attribute is called with
+ a format string that uses format specifiers that are allowed, and that
+ arguments match the format string. This is the `-Wformat` warning, it is
+ on by default.
+
+2. Clang checks that the format string argument is a literal string. This is
+ the `-Wformat-nonliteral` warning, it is off by default.
+
+ Clang implements this mostly the same way as GCC, but there is a difference
+ for functions that accept a `va_list` argument (for example, `vprintf`).
+ GCC does not emit `-Wformat-nonliteral` warning for calls to such
+ functions. Clang does not warn if the format string comes from a function
+ parameter, where the function is annotated with a compatible attribute,
+ otherwise it warns. For example:
+
+ ```c
+ __attribute__((__format__ (__scanf__, 1, 3)))
+ void foo(const char* s, char *buf, ...) {
+ va_list ap;
+ va_start(ap, buf);
+
+ vprintf(s, ap); // warning: format string is not a string literal
+ }
+ ```
+
+ In this case we warn because `s` contains a format string for a
+ `scanf`-like function, but it is passed to a `printf`-like function.
+
+ If the attribute is removed, clang still warns, because the format string is
+ not a string literal.
+
+ Another example:
+
+ ```c
+ __attribute__((__format__ (__printf__, 1, 3)))
+ void foo(const char* s, char *buf, ...) {
+ va_list ap;
+ va_start(ap, buf);
+
+ vprintf(s, ap); // warning
+ }
+ ```
+
+ In this case Clang does not warn because the format string `s` and
+ the corresponding arguments are annotated. If the arguments are
+ incorrect, the caller of `foo` will receive a warning.
+
+As an extension to GCC's behavior, Clang accepts the `format` attribute on
+non-variadic functions. Clang checks non-variadic format functions for the same
+classes of issues that can be found on variadic functions, as controlled by the
+same warning flags, except that the types of formatted arguments is forced by
+the function signature. For example:
+
+```c
+__attribute__((__format__(__printf__, 1, 2)))
+void fmt(const char *s, const char *a, int b);
+
+void bar(void) {
+ fmt("%s %i", "hello", 123); // OK
+ fmt("%i %g", "hello", 123); // warning: arguments don't match format
+ extern const char *fmt;
+ fmt(fmt, "hello", 123); // warning: format string is not a string literal
+}
+```
+
+When using the format attribute on a variadic function, the first data parameter
+must be the index of the ellipsis in the parameter list. Clang will generate
+a diagnostic otherwise, as it wouldn't be possible to forward that argument list
+to `printf`-family functions. For instance, this is an error:
+
+```c
+__attribute__((__format__(__printf__, 1, 2)))
+void fmt(const char *s, int b, ...);
+// ^ error: format attribute parameter 3 is out of bounds
+// (must be __printf__, 1, 3)
+```
+
+Using the `format` attribute on a non-variadic function emits a GCC
+compatibility diagnostic.
+
+
+### format_matches
+
+{clang-attr-syntaxes}`FormatMatchesDocs`
+
+The `format` attribute is the basis for the enforcement of diagnostics in the
+`-Wformat` family, but it only handles the case where the format string is
+passed along with the arguments it is going to format. It cannot handle the case
+where the format string and the format arguments are passed separately from each
+other. For instance:
+
+```c
+static const char *first_name;
+static double todays_temperature;
+static int wind_speed;
+
+void say_hi(const char *fmt) {
+ printf(fmt, first_name, todays_temperature);
+ // ^ warning: format string is not a string literal
+ printf(fmt, first_name, wind_speed);
+ // ^ warning: format string is not a string literal
+}
+
+int main() {
+ say_hi("hello %s, it is %g degrees outside");
+ say_hi("hello %s, it is %d degrees outside!");
+ // ^ no diagnostic, but %d cannot format doubles
+}
+```
+
+In this example, `fmt` is expected to format a `const char *` and a
+`double`, but these values are not passed to `say_hi`. Without the
+`format` attribute (which cannot apply in this case), the -Wformat-nonliteral
+diagnostic unnecessarily triggers in the body of `say_hi`, and incorrect
+`say_hi` call sites do not trigger a diagnostic.
+
+To complement the `format` attribute, Clang also defines the
+`format_matches` attribute. Its syntax is similar to the `format`
+attribute's, but instead of taking the index of the first formatted value
+argument, it takes a C string literal with the expected specifiers:
+
+```c
+static const char *first_name;
+static double todays_temperature;
+static int wind_speed;
+
+__attribute__((__format_matches__(printf, 1, "%s %g")))
+void say_hi(const char *fmt) {
+ printf(fmt, first_name, todays_temperature); // no dignostic
+ printf(fmt, first_name, wind_speed); // warning: format specifies type 'int' but the argument has type 'double'
+}
+
+int main() {
+ say_hi("hello %s, it is %g degrees outside");
+ say_hi("it is %g degrees outside, have a good day %s!");
+ // warning: format specifies 'double' where 'const char *' is required
+ // warning: format specifies 'const char *' where 'double' is required
+}
+```
+
+The third argument to `format_matches` is expected to evaluate to a **C string
+literal** even when the format string would normally be a different type for the
+given flavor, like a `CFStringRef` or a `NSString *`.
+
+The only requirement on the format string literal is that it has specifiers
+that are compatible with the arguments that will be used. It can contain
+arbitrary non-format characters. For instance, for the purposes of compile-time
+validation, `"%s scored %g%% on her test"` and `"%s%g"` are interchangeable
+as the format string argument. As a means of self-documentation, users may
+prefer the former when it provides a useful example of an expected format
+string.
+
+In the implementation of a function with the `format_matches` attribute,
+format verification works as if the format string was identical to the one
+specified in the attribute.
+
+```c
+__attribute__((__format_matches__(printf, 1, "%s %g")))
+void say_hi(const char *fmt) {
+ printf(fmt, "person", 546);
+ // ^ warning: format specifies type 'double' but the
+ // argument has type 'int'
+ // note: format string is defined here:
+ // __attribute__((__format_matches__(printf, 1, "%s %g")))
+ // ^~
+}
+```
+
+At the call sites of functions with the `format_matches` attribute, format
+verification instead compares the two format strings to evaluate their
+equivalence. Each format flavor defines equivalence between format specifiers.
+Generally speaking, two specifiers are equivalent if they format the same type.
+For instance, in the `printf` flavor, `%2i` and `%-0.5d` are compatible.
+When `-Wformat-signedness` is disabled, `%d` and `%u` are compatible. For
+a negative example, `%ld` is incompatible with `%d`.
+
+Do note the following un-obvious cases:
+
+- Passing `NULL` as the format string does not trigger format diagnostics.
+- When the format string is not NULL, it cannot miss specifiers, even in
+ trailing positions. For instance, `%d` is not accepted when the required
+ format is `%d %d %d`.
+- While checks for the `format` attribute tolerate sone size mismatches
+ that standard argument promotion renders immaterial (such as formatting an
+ `int` with `%hhd`, which specifies a `char`-sized integer), checks for
+ `format_matches` require specified argument sizes to match exactly.
+- Format strings expecting a variable modifier (such as `%*s`) are
+ incompatible with format strings that would itemize the variable modifiers
+ (such as `%i %s`), even if the two specify ABI-compatible argument lists.
+- All pointer specifiers, modifiers aside, are mutually incompatible. For
+ instance, `%s` is not compatible with `%p`, and `%p` is not compatible
+ with `%n`, and `%hhn` is incompatible with `%s`, even if the pointers
+ are ABI-compatible or identical on the selected platform. However, `%0.5s`
+ is compatible with `%s`, since the difference only exists in modifier flags.
+ This is not overridable with `-Wformat-pedantic` or its inverse, which
+ control similar behavior in `-Wformat`.
+
+At this time, clang implements `format_matches` only for format types in the
+`printf` family. This includes variants such as Apple's NSString format and
+the FreeBSD `kprintf`, but excludes `scanf`. Using a known but unsupported
+format silently fails in order to be compatible with other implementations that
+would support these formats.
+
+
+### function_return
+
+{clang-attr-syntaxes}`FunctionReturnThunksDocs`
+
+The attribute `function_return` can replace return instructions with jumps to
+target-specific symbols. This attribute supports 2 possible values,
+corresponding to the values supported by the `-mfunction-return=` command
+line flag:
+
+- `__attribute__((function_return("keep")))` to disable related transforms.
+ This is useful for undoing global setting from `-mfunction-return=` locally
+ for individual functions.
+- `__attribute__((function_return("thunk-extern")))` to replace returns with
+ jumps, while NOT emitting the thunk.
+
+The values `thunk` and `thunk-inline` from GCC are not supported.
+
+The symbol used for `thunk-extern` is target specific:
+
+- X86: `__x86_return_thunk`
+
+As such, this function attribute is currently only supported on X86 targets.
+
+
+### gnu_inline
+
+{clang-attr-syntaxes}`GnuInlineDocs`
+
+The `gnu_inline` changes the meaning of `extern inline` to use GNU inline
+semantics, meaning:
+
+- If any declaration that is declared `inline` is not declared `extern`,
+ then the `inline` keyword is just a hint. In particular, an out-of-line
+ definition is still emitted for a function with external linkage, even if all
+ call sites are inlined, unlike in C99 and C++ inline semantics.
+- If all declarations that are declared `inline` are also declared
+ `extern`, then the function body is present only for inlining and no
+ out-of-line version is emitted.
+
+Some important consequences: `static inline` emits an out-of-line
+version if needed, a plain `inline` definition emits an out-of-line version
+always, and an `extern inline` definition (in a header) followed by a
+(non-`extern`) `inline` declaration in a source file emits an out-of-line
+version of the function in that source file but provides the function body for
+inlining to all includers of the header.
+
+Either `__GNUC_GNU_INLINE__` (GNU inline semantics) or
+`__GNUC_STDC_INLINE__` (C99 semantics) will be defined (they are mutually
+exclusive). If `__GNUC_STDC_INLINE__` is defined, then the `gnu_inline`
+function attribute can be used to get GNU inline semantics on a per function
+basis. If `__GNUC_GNU_INLINE__` is defined, then the translation unit is
+already being compiled with GNU inline semantics as the implied default. It is
+unspecified which macro is defined in a C++ compilation.
+
+GNU inline semantics are the default behavior with `-std=gnu89`,
+`-std=c89`, `-fgnu89-inline`, or `-std=iso9899:199409`.
+
+
+### guard
+
+{clang-attr-syntaxes}`CFGuardDocs`
+
+Code can indicate CFG checks are not wanted with the `__declspec(guard(nocf))`
+attribute. This directs the compiler to not insert any CFG checks for the entire
+function. This approach is typically used only sparingly in specific situations
+where the programmer has manually inserted "CFG-equivalent" protection. The
+programmer knows that they are calling through some read-only function table
+whose address is obtained through read-only memory references and for which the
+index is masked to the function table limit. This approach may also be applied
+to small wrapper functions that are not inlined and that do nothing more than
+make a call through a function pointer. Since incorrect usage of this directive
+can compromise the security of CFG, the programmer must be very careful using
+the directive. Typically, this usage is limited to very small functions that
+only call one function.
+
+Control Flow Guard documentation is available here:
+<https://docs.microsoft.com/en-us/windows/win32/secbp/pe-metadata>
+
+
+### hot
+
+{clang-attr-syntaxes}`HotFunctionEntryDocs`
+
+`__attribute__((hot))` marks a function as hot, as a manual alternative to PGO hotness data.
+If PGO data is available, the annotation `__attribute__((hot))` overrides the profile count based hotness (unlike `__attribute__((cold))`).
+
+
+### hybrid_patchable
+
+{clang-attr-syntaxes}`HybridPatchableDocs`
+
+The `hybrid_patchable` attribute declares an ARM64EC function with an additional
+x86-64 thunk, which may be patched at runtime.
+
+For more information see
+[ARM64EC ABI documentation](https://learn.microsoft.com/en-us/windows/arm/arm64ec-abi).
+
+
+### ifunc
+
+{clang-attr-syntaxes}`IFuncDocs`
+
+`__attribute__((ifunc("resolver")))` is used to mark that the address of a
+declaration should be resolved at runtime by calling a resolver function.
+
+The symbol name of the resolver function is given in quotes. A function with
+this name (after mangling) must be defined in the current translation unit; it
+may be `static`. The resolver function should return a pointer.
+
+The `ifunc` attribute may only be used on a function declaration. A function
+declaration with an `ifunc` attribute is considered to be a definition of the
+declared entity. The entity must not have weak linkage; for example, in C++,
+it cannot be applied to a declaration if a definition at that location would be
+considered inline.
+
+Not all targets support this attribute:
+
+- ELF target support depends on both the linker and runtime linker, and is
+ available in at least lld 4.0 and later, binutils 2.20.1 and later, glibc
+ v2.11.1 and later, and FreeBSD 9.1 and later.
+- Mach-O targets support it, but with slightly different semantics: the resolver
+ is run at first call, instead of at load time by the runtime linker.
+- Windows target supports it on AArch64, but with different semantics: the
+ `ifunc` is replaced with a global function pointer, and the call is replaced
+ with an indirect call. The function pointer is initialized by a constructor
+ that calls the resolver.
+- Baremetal target supports it on AVR.
+- AIX/XCOFF supports it via a compiler-only solution. An ifunc appears as a
+ regular function (has an entry point `.foo[PR]` and a function descriptor
+ `foo[DS]`). The entry point is a stub that branches to the function address
+ in the descriptor, and the descriptor is initialized via a constructor
+ function (`__init_ifuncs`) that is linked into every shared object and
+ executable. `__init_ifuncs` calls the resolver of each ifunc and stores the
+ result in the corresponding descriptor.
+- Other targets currently do not support this attribute.
+
+
+### import_module
+
+{clang-attr-syntaxes}`WebAssemblyImportModuleDocs`
+
+Clang supports the `__attribute__((import_module(<module_name>)))`
+attribute for the WebAssembly target. This attribute may be attached to a
+function declaration, where it modifies how the symbol is to be imported
+within the WebAssembly linking environment.
+
+WebAssembly imports use a two-level namespace scheme, consisting of a module
+name, which typically identifies a module from which to import, and a field
+name, which typically identifies a field from that module to import. By
+default, module names for C/C++ symbols are assigned automatically by the
+linker. This attribute can be used to override the default behavior, and
+request a specific module name be used instead.
+
+
+### import_name
+
+{clang-attr-syntaxes}`WebAssemblyImportNameDocs`
+
+Clang supports the `__attribute__((import_name(<name>)))`
+attribute for the WebAssembly target. This attribute may be attached to a
+function declaration, where it modifies how the symbol is to be imported
+within the WebAssembly linking environment.
+
+WebAssembly imports use a two-level namespace scheme, consisting of a module
+name, which typically identifies a module from which to import, and a field
+name, which typically identifies a field from that module to import. By
+default, field names for C/C++ symbols are the same as their C/C++ symbol
+names. This attribute can be used to override the default behavior, and
+request a specific field name be used instead.
+
+
+### internal_linkage
+
+{clang-attr-syntaxes}`InternalLinkageDocs`
+
+The `internal_linkage` attribute changes the linkage type of the declaration
+to internal. This is similar to C-style `static`, but can be used on classes
+and class methods. When applied to a class definition, this attribute affects
+all methods and static data members of that class. This can be used to contain
+the ABI of a C++ library by excluding unwanted class methods from the export
+tables.
+
+
+### interrupt (ARM)
+
+{clang-attr-syntaxes}`ARMInterruptDocs`
+
+Clang supports the GNU style `__attribute__((interrupt("TYPE")))` attribute on
+ARM targets. This attribute may be attached to a function definition and
+instructs the backend to generate appropriate function entry/exit code so that
+it can be used directly as an interrupt service routine.
+
+The parameter passed to the interrupt attribute is optional, but if
+provided it must be a string literal with one of the following values: "IRQ",
+"FIQ", "SWI", "ABORT", "UNDEF".
+
+The semantics are as follows:
+
+- If the function is AAPCS, Clang instructs the backend to realign the stack to
+ 8 bytes on entry. This is a general requirement of the AAPCS at public
+ interfaces, but may not hold when an exception is taken. Doing this allows
+ other AAPCS functions to be called.
+
+- If the CPU is M-class this is all that needs to be done since the architecture
+ itself is designed in such a way that functions obeying the normal AAPCS ABI
+ constraints are valid exception handlers.
+
+- If the CPU is not M-class, the prologue and epilogue are modified to save all
+ non-banked registers that are used, so that upon return the user-mode state
+ will not be corrupted. Note that to avoid unnecessary overhead, only
+ general-purpose (integer) registers are saved in this way. If VFP operations
+ are needed, that state must be saved manually.
+
+ Specifically, interrupt kinds other than "FIQ" will save all core registers
+ except "lr" and "sp". "FIQ" interrupts will save r0-r7.
+
+- If the CPU is not M-class, the return instruction is changed to one of the
+ canonical sequences permitted by the architecture for exception return. Where
+ possible the function itself will make the necessary "lr" adjustments so that
+ the "preferred return address" is selected.
+
+ Unfortunately the compiler is unable to make this guarantee for an "UNDEF"
+ handler, where the offset from "lr" to the preferred return address depends on
+ the execution state of the code which generated the exception. In this case
+ a sequence equivalent to "movs pc, lr" will be used.
+
+
+### interrupt (AVR)
+
+{clang-attr-syntaxes}`AVRInterruptDocs`
+
+Clang supports the GNU style `__attribute__((interrupt))` attribute on
+AVR targets. This attribute may be attached to a function definition and instructs
+the backend to generate appropriate function entry/exit code so that it can be used
+directly as an interrupt service routine.
+
+On the AVR, the hardware globally disables interrupts when an interrupt is executed.
+The first instruction of an interrupt handler declared with this attribute is a SEI
+instruction to re-enable interrupts. See also the signal attribute that
+does not insert a SEI instruction.
+
+
+### interrupt (MIPS)
+
+{clang-attr-syntaxes}`MipsInterruptDocs`
+
+Clang supports the GNU style `__attribute__((interrupt("ARGUMENT")))` attribute on
+MIPS targets. This attribute may be attached to a function definition and instructs
+the backend to generate appropriate function entry/exit code so that it can be used
+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 behavior can be explicitly requested with the "eic"
+argument.
+
+Otherwise, for use with vectored interrupt mode, the argument passed should be
+of the form "vector=LEVEL" where LEVEL is one of the following values:
+"sw0", "sw1", "hw0", "hw1", "hw2", "hw3", "hw4", "hw5". The compiler will
+then set the interrupt mask to the corresponding level which will mask all
+interrupts up to and including the argument.
+
+The semantics are as follows:
+
+- The prologue is modified so that the Exception Program Counter (EPC) and
+ Status coprocessor registers are saved to the stack. The interrupt mask is
+ set so that the function can only be interrupted by a higher priority
+ interrupt. The epilogue will restore the previous values of EPC and Status.
+- The prologue and epilogue are modified to save and restore all non-kernel
+ registers as necessary.
+- The FPU is disabled in the prologue, as the floating pointer registers are not
+ spilled to the stack.
+- The function return sequence is changed to use an exception return instruction.
+- The parameter sets the interrupt mask for the function corresponding to the
+ interrupt level specified. If no mask is specified the interrupt mask
+ defaults to "eic".
+
+
+### interrupt (RISC-V)
+
+{clang-attr-syntaxes}`RISCVInterruptDocs`
+
+Clang supports the GNU style `__attribute__((interrupt))` attribute on RISCV
+targets. This attribute may be attached to a function definition and instructs
+the backend to generate appropriate function entry/exit code so that it can be
+used directly as an interrupt service routine.
+
+Permissible values for this parameter are `machine`, `supervisor`,
+`rnmi`, `qci-nest`, `qci-nonest`, `SiFive-CLIC-preemptible`, and
+`SiFive-CLIC-stack-swap`. If there is no parameter, then it defaults to
+`machine`.
+
+The `rnmi` value is used for resumable non-maskable interrupts. It requires the
+standard Smrnmi extension.
+
+The `qci-nest` and `qci-nonest` values require Qualcomm's Xqciint extension
+and are used for Machine-mode Interrupts and Machine-mode Non-maskable
+interrupts. These use the following instructions from Xqciint to save and
+restore interrupt state to the stack -- the `qci-nest` value will use
+`qc.c.mienter.nest` and the `qci-nonest` value will use `qc.c.mienter` to
+begin the interrupt handler. Both of these will use `qc.c.mileaveret` to
+restore the state and return to the previous context.
+
+The `SiFive-CLIC-preemptible` and `SiFive-CLIC-stack-swap` values are used
+for machine-mode interrupts. For `SiFive-CLIC-preemptible` interrupts, the
+values of `mcause` and `mepc` are saved onto the stack, and interrupts are
+re-enabled. For `SiFive-CLIC-stack-swap` interrupts, the stack pointer is
+swapped with `mscratch` before its first use and after its last use.
+
+The SiFive CLIC values may be combined with each other and with the `machine`
+attribute value. Any other combination of different values is not allowed.
+
+Repeated interrupt attribute on the same declaration will cause a warning
+to be emitted. In case of repeated declarations, the last one prevails.
+
+References:
+- [GCC RISC-V Attributes](https://gcc.gnu.org/onlinedocs/gcc/RISC-V-Function-Attributes.html)
+- [The RISC-V Instruction Set Manual Volume II: Privileged Architecture Version 1.10](https://docs.riscv.org/reference/isa/v1.10/_attachments/riscv-privileged.pdf)
+- [Xqci extension v0.13](https://github.com/quic/riscv-unified-db/releases/tag/Xqci-0.13.0)
+- [SiFive Interrupt Cookbook Version 1.2](https://sifive.cdn.prismic.io/sifive/d1984d2b-c9b9-4c91-8de0-d68a5e64fa0f_sifive-interrupt-cookbook-v1p2.pdf)
+
+
+### interrupt (X86)
+
+{clang-attr-syntaxes}`AnyX86InterruptDocs`
+
+Clang supports the GNU style `__attribute__((interrupt))` attribute on X86
+targets. This attribute may be attached to a function definition and instructs
+the backend to generate appropriate function entry/exit code so that it can be
+used directly as an interrupt service routine.
+
+Interrupt handlers have access to the stack frame pushed onto the stack by the processor,
+and return using the `IRET` instruction. All registers in an interrupt handler are callee-saved.
+Exception handlers also have access to the error code pushed onto the stack by the processor,
+when applicable.
+
+An interrupt handler must take the following arguments:
+
+```c
+__attribute__ ((interrupt))
+void f (struct stack_frame *frame) {
+ ...
+}
+```
+
+Where `struct stack_frame` is a suitable struct matching the stack frame pushed
+by the processor.
+
+An exception handler must take the following arguments:
+
+```c
+__attribute__ ((interrupt))
+void g (struct stack_frame *frame, unsigned long code) {
+ ...
+}
+```
+
+On 32-bit targets, the `code` argument should be of type `unsigned int`.
+
+Exception handlers should only be used when an error code is pushed by the processor.
+Using the incorrect handler type will crash the system.
+
+Interrupt and exception handlers cannot be called by other functions and must have return type `void`.
+
+Interrupt and exception handlers should only call functions with the `no_caller_saved_registers`
+attribute, or should be compiled with the `-mgeneral-regs-only` flag to avoid saving unused
+non-GPR registers.
+
+
+### interrupt_save_fp (ARM)
+
+{clang-attr-syntaxes}`ARMInterruptSaveFPDocs`
+
+Clang supports the GNU style `__attribute__((interrupt_save_fp("TYPE")))`
+on ARM targets. This attribute behaves the same way as the ARM interrupt
+attribute, except the general purpose floating point registers are also saved,
+along with FPEXC and FPSCR. Note, even on M-class CPUs, where the floating
+point context can be automatically saved depending on the FPCCR, the general
+purpose floating point registers will be saved.
+
+
+### launch_bounds
+
+{clang-attr-syntaxes}`LaunchBoundsDocs`
+
+The `__launch_bounds__` attribute (also spelled `launch_bounds`) originates
+in CUDA. It informs the compiler of the launch configuration a kernel will be
+dispatched with, allowing it to optimize the kernel accordingly. It takes the
+form `__launch_bounds__(<max-threads-per-block>[,
+<min-blocks-per-multiprocessor>[, <max-blocks-per-cluster>]])`. All arguments
+are constant expressions.
+
+The attribute only takes effect on `__global__` (kernel) functions; like
+NVCC, Clang ignores it on any other function.
+
+`<max-threads-per-block>` specifies the maximum number of threads per block
+the kernel will be launched with. `<min-blocks-per-multiprocessor>` specifies
+the desired minimum number of blocks resident per multiprocessor, and
+`<max-blocks-per-cluster>` the maximum number of blocks per cluster.
+
+For the NVPTX target, `<max-threads-per-block>` and
+`<min-blocks-per-multiprocessor>` map to the `.maxntid` and `.minnctapersm`
+PTX directives, respectively, and `<max-blocks-per-cluster>` (which requires
+`sm_90` or newer) maps to `.maxclusterrank`.
+
+For the AMDGPU target, the attribute is translated into the equivalent AMDGPU
+kernel attributes:
+
+ - `<max-threads-per-block>` sets the maximum
+ `amdgpu_flat_work_group_size` (as `1, <max-threads-per-block>`).
+ - `<min-blocks-per-multiprocessor>` sets the minimum
+ `amdgpu_waves_per_eu`. Note that HIP reinterprets this CUDA argument as a
+ minimum number of waves per execution unit, so its meaning differs from the
+ NVPTX interpretation.
+ - `<max-blocks-per-cluster>` is currently ignored.
+
+An explicit `amdgpu_flat_work_group_size` or `amdgpu_waves_per_eu` attribute
+takes precedence over the value derived from `__launch_bounds__`.
+
+When the same kernel is declared multiple times, the launch bounds from the most
+recent declaration that specifies them are used; a definition without
+`__launch_bounds__` inherits the bounds from an earlier declaration.
+
+
+### lifetime_capture_by, lifetime_capture_by_this, lifetime_capture_by_global, lifetime_capture_by_unknown
+
+{clang-attr-syntaxes}`LifetimeCaptureByDocs`
+
+Similar to [lifetimebound], the `lifetime_capture_by` attribute family on a
+function parameter or implicit object parameter indicates that a capturing
+entity may refer to the object referred to by that parameter. The capturing
+entity can be named in `lifetime_capture_by(X)` or selected by one of the
+standalone special forms listed below.
+
+Below is a list of types of the parameters and what they're considered to refer to:
+
+- A reference param (of non-view type) is considered to refer to its referenced object.
+- A pointer param (of non-view type) is considered to refer to its pointee.
+- View type param (type annotated with `[[gsl::Pointer()]]`) is considered to refer
+ to its pointee (gsl owner). This holds true even if the view type appears as a reference
+ in the parameter. For example, both `std::string_view` and
+ `const std::string_view &` are considered to refer to a `std::string`.
+- A `std::initializer_list<T>` is considered to refer to its underlying array.
+- Aggregates (arrays and simple `struct`s) are considered to refer to all
+ objects that their transitive subobjects refer to.
+
+Clang would diagnose when a temporary object is used as an argument to such an
+annotated parameter.
+In this case, the capturing entity `X` could capture a dangling reference to this
+temporary object.
+
+```c++
+void addToSet(std::string_view a [[clang::lifetime_capture_by(s)]], std::set<std::string_view>& s) {
+ s.insert(a);
+}
+void use() {
+ std::set<std::string_view> s;
+ addToSet(std::string(), s); // Warning: object whose reference is captured by 's' will be destroyed at the end of the full-expression.
+ // ^^^^^^^^^^^^^
+ std::string local;
+ addToSet(local, s); // Ok.
+}
+```
+
+The capturing entity can be one of the following:
+
+- Another (named) function parameter.
+
+ ```c++
+ void addToSet(std::string_view a [[clang::lifetime_capture_by(s)]], std::set<std::string_view>& s) {
+ s.insert(a);
+ }
+ ```
+
+- `this` (in case of member functions), written as
+ `lifetime_capture_by_this`.
+
+ ```c++
+ class S {
+ void addToSet(std::string_view a [[clang::lifetime_capture_by_this]]) {
+ s.insert(a);
+ }
+ std::set<std::string_view> s;
+ };
+ ```
+
+ Note: When applied to a constructor parameter, `[[clang::lifetime_capture_by_this]]` is just an alias of `[[clang::lifetimebound]]`.
+
+- `global` and `unknown`, written as `lifetime_capture_by_global` and
+ `lifetime_capture_by_unknown` respectively.
+
+ ```c++
+ std::set<std::string_view> s;
+ void addToSet(std::string_view a [[clang::lifetime_capture_by_global]]) {
+ s.insert(a);
+ }
+ void addSomewhere(std::string_view a [[clang::lifetime_capture_by_unknown]]);
+ ```
+
+The attribute can be applied to the implicit `this` parameter of a member
+function by writing the attribute after the function type:
+
+```c++
+struct S {
+ const char *data(std::set<S*>& s) [[clang::lifetime_capture_by(s)]] {
+ s.insert(this);
+ }
+};
+```
+
+The parameter-list form supports specifying more than one capturing entity:
+
+```c++
+void addToSets(std::string_view a [[clang::lifetime_capture_by(s1, s2)]],
+ std::set<std::string_view>& s1,
+ std::set<std::string_view>& s2) {
+ s1.insert(a);
+ s2.insert(a);
+}
+```
+
+Distinct `lifetime_capture_by` forms can also be combined on the same
+declaration, but each form can appear at most once. For example,
+`[[clang::lifetime_capture_by(s), clang::lifetime_capture_by_this]]` is
+allowed, but two `[[clang::lifetime_capture_by(...)]]` attributes or two
+`[[clang::lifetime_capture_by_this]]` attributes on the same declaration are
+rejected.
+
+Limitation: The capturing entity `X` is not used by the analysis and is
+used for documentation purposes only. This is because the analysis is
+statement-local and only detects use of a temporary as an argument to the
+annotated parameter.
+
+```c++
+void addToSet(std::string_view a [[clang::lifetime_capture_by(s)]], std::set<std::string_view>& s);
+void use() {
+ std::set<std::string_view> s;
+ if (foo()) {
+ std::string str;
+ addToSet(str, s); // Not detected.
+ }
+}
+```
+
+
+### lifetimebound
+
+{clang-attr-syntaxes}`LifetimeBoundDocs`
+
+The `lifetimebound` attribute on a function parameter or implicit object
+parameter indicates that objects that are referred to by that parameter may
+also be referred to by the return value of the annotated function (or, for a
+parameter of a constructor, by the value of the constructed object).
+
+By default, a reference is considered to refer to its referenced object, a
+pointer is considered to refer to its pointee, a `std::initializer_list<T>`
+is considered to refer to its underlying array, and aggregates (arrays and
+simple `struct`s) are considered to refer to all objects that their
+transitive subobjects refer to.
+
+Clang warns if it is able to detect that an object or reference refers to
+another object with a shorter lifetime. For example, Clang will warn if a
+function returns a reference to a local variable, or if a reference is bound to
+a temporary object whose lifetime is not extended. By using the
+`lifetimebound` attribute, this determination can be extended to look through
+user-declared functions. For example:
+
+```c++
+#include <map>
+#include <string>
+
+using namespace std::literals;
+
+// Returns m[key] if key is present, or default_value if not.
+template<typename T, typename U>
+const U &get_or_default(const std::map<T, U> &m [[clang::lifetimebound]],
+ const T &key, /* note, not lifetimebound */
+ const U &default_value [[clang::lifetimebound]]) {
+ if (auto iter = m.find(key); iter != m.end()) return iter->second;
+ else return default_value;
+}
+
+int main() {
+ std::map<std::string, std::string> m;
+ // warning: temporary bound to local reference 'val1' will be destroyed
+ // at the end of the full-expression
+ const std::string &val1 = get_or_default(m, "foo"s, "bar"s);
+
+ // No warning in this case.
+ std::string def_val = "bar"s;
+ const std::string &val2 = get_or_default(m, "foo"s, def_val);
+
+ return 0;
+}
+```
+
+The attribute can be applied to the implicit `this` parameter of a member
+function by writing the attribute after the function type:
+
+```c++
+struct string {
+ // The returned pointer should not outlive '*this'.
+ const char *data() const [[clang::lifetimebound]];
+};
+```
+
+This attribute is inspired by the C++ committee paper [P0936R0](http://wg21.link/p0936r0), but does not affect whether temporary objects
+have their lifetimes extended.
+
+
+### long_call, far
+
+{clang-attr-syntaxes}`MipsLongCallStyleDocs`
+
+Clang supports the `__attribute__((long_call))`, `__attribute__((far))`,
+and `__attribute__((near))` attributes on MIPS targets. These attributes may
+only be added to function declarations and change the code generated
+by the compiler when directly calling the function. The `near` attribute
+allows calls to the function to be made using the `jal` instruction, which
+requires the function to be located in the same naturally aligned 256MB
+segment as the caller. The `long_call` and `far` attributes are synonyms
+and require the use of a different call sequence that works regardless
+of the distance between the functions.
+
+These attributes have no effect for position-independent code.
+
+These attributes take priority over command line switches such
+as `-mlong-calls` and `-mno-long-calls`.
+
+
+### malloc
+
+{clang-attr-syntaxes}`RestrictDocs`
+
+The `malloc` attribute has two forms with different functionality. The first
+is when it is used without arguments, where it marks that a function acts like
+a system memory allocation function, returning a pointer to allocated storage
+that does not alias storage from any other object accessible to the caller.
+
+The second form is when `malloc` takes one or two arguments. The first
+argument names a function that should be associated with this function as its
+deallocation function. When this form is used, it enables the compiler to
+diagnose when the incorrect deallocation function is used with this variable.
+However the associated warning, spelled `-Wmismatched-dealloc` in GCC, is not
+yet implemented in clang.
+
+
+### malloc_span
+
+{clang-attr-syntaxes}`MallocSpanDocs`
+
+The `malloc_span` attribute can be used to mark that a function which acts
+like a system memory allocation function and returns a span-like structure,
+where the returned memory range does not alias storage from any other object
+accessible to the caller.
+
+In this context, a span-like structure is assumed to have two non-static data
+members, one of which is a pointer to the start of the allocated memory and
+the other one is either an integer type containing the size of the actually
+allocated memory or a pointer to the end of the allocated region. Note, static
+data members do not impact whether a type is span-like or not.
+
+In combination with the `alloc_size` attribute, if the begin pointer is
+non-null, the size of the returned span-like object has to be greater or equal
+to the number of bytes guaranteed to be dereferenceable by `alloc_size`. It also
+guarantees that the number of dereferenceable bytes is at least size.
+
+
+### micromips, nomicromips
+
+{clang-attr-syntaxes}`MicroMipsDocs`
+
+Clang supports the GNU style `__attribute__((micromips))` and
+`__attribute__((nomicromips))` attributes on MIPS targets. These attributes
+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
+on the command line.
+
+
+### mig_server_routine
+
+{clang-attr-syntaxes}`MIGConventionDocs`
+
+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 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
+that convention. The attribute would normally appear on the forward declaration
+of the actual server routine in the MIG server header, but it may also be
+added to arbitrary functions that need to follow the same convention - for
+example, a user can add them to auxiliary functions called by the server routine
+that have their return value of type `kern_return_t` unconditionally returned
+from the routine. The attribute can be applied to C++ methods, and in this case
+it will be automatically applied to overrides if the method is virtual. The
+attribute can also be written using C++11 syntax: `[[mig::server_routine]]`.
+
+
+### min_vector_width
+
+{clang-attr-syntaxes}`MinVectorWidthDocs`
+
+Clang supports the `__attribute__((min_vector_width(width)))` attribute. This
+attribute may be attached to a function and informs the backend that this
+function desires vectors of at least this width to be generated. Target-specific
+maximum vector widths still apply. This means even if you ask for something
+larger than the target supports, you will only get what the target supports.
+This attribute is meant to be a hint to control target heuristics that may
+generate narrower vectors than what the target hardware supports.
+
+This is currently used by the X86 target to allow some CPUs that support 512-bit
+vectors to be limited to using 256-bit vectors to avoid frequency penalties.
+This is currently enabled with the `-prefer-vector-width=256` command line
+option. The `min_vector_width` attribute can be used to prevent the backend
+from trying to split vector operations to match the `prefer-vector-width`. All
+X86 vector intrinsics from x86intrin.h already set this attribute. Additionally,
+use of any of the X86-specific vector builtins will implicitly set this
+attribute on the calling function. The intent is that explicitly writing vector
+code using the X86 intrinsics will prevent `prefer-vector-width` from
+affecting the code.
+
+
+### minsize
+
+{clang-attr-syntaxes}`MinSizeDocs`
+
+This function attribute indicates that optimization passes and code generator passes
+make choices that keep the function code size as small as possible. Optimizations may
+also sacrifice runtime performance in order to minimize the size of the generated code.
+
+
+### modular_format
+
+{clang-attr-syntaxes}`ModularFormatDocs`
+
+The `modular_format` attribute can be applied to a function that bears the
+`format` attribute (or standard library functions) to indicate that the
+implementation is "modular", that is, that the implementation is logically
+divided into a number of named aspects. When the compiler can determine that
+not all aspects of the implementation are needed for a given call, the compiler
+may redirect the call to the identifier given as the first argument to the
+attribute (the modular implementation function).
+
+The second argument is an implementation name, and the remaining arguments are
+aspects of the format string for the compiler to report. The implementation
+name is an unevaluated identifier in the C namespace.
+
+The compiler reports that a call requires an aspect by issuing a relocation for
+the symbol `<impl_name>_<aspect>` at the point of the call. This arranges for
+code and data needed to support the aspect of the implementation to be brought
+into the link to satisfy weak references in the modular implemenation function.
+If the compiler does not understand an aspect, it must summarily consider any
+call to require that aspect.
+
+For example, say `printf` is annotated with
+`modular_format(__modular_printf, "__printf", "float")`. Then, a call to
+`printf(var, 42)` would be untouched. A call to `printf("%d", 42)` would
+become a call to `__modular_printf` with the same arguments, as would
+`printf("%f", 42.0)`. The latter would be accompanied with a strong
+relocation against the symbol `__printf_float`, which would bring floating
+point support for `printf` into the link.
+
+If the attribute appears more than once on a declaration, or across a chain of
+redeclarations, it is an error for the attributes to have different arguments,
+excepting that the aspects may be in any order.
+
+The following aspects are currently supported:
+
+- `fixed`: The call has a C ISO 18037 fixed-point argument.
+- `float`: The call has a floating-point argument.
+
+
+### no_builtin
+
+{clang-attr-syntaxes}`NoBuiltinDocs`
+
+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
+applied to a virtual function but has no effect on the behavior of overriding
+functions in a derived class.
+
+It accepts one or more strings corresponding to the specific names of the
+builtins to disable (e.g. "memcpy", "memset").
+If the attribute is used without parameters it will disable all buitins at
+once.
+
+```c++
+// The compiler is not allowed to add any builtin to foo's body.
+void foo(char* data, size_t count) __attribute__((no_builtin)) {
+ // The compiler is not allowed to convert the loop into
+ // `__builtin_memset(data, 0xFE, count);`.
+ for (size_t i = 0; i < count; ++i)
+ data[i] = 0xFE;
+}
+
+// The compiler is not allowed to add the `memcpy` builtin to bar's body.
+void bar(char* data, size_t count) __attribute__((no_builtin("memcpy"))) {
+ // The compiler is allowed to convert the loop into
+ // `__builtin_memset(data, 0xFE, count);` but cannot generate any
+ // `__builtin_memcpy`
+ for (size_t i = 0; i < count; ++i)
+ data[i] = 0xFE;
+}
+```
+
+
+### no_caller_saved_registers
+
+{clang-attr-syntaxes}`AnyX86NoCallerSavedRegistersDocs`
+
+Use this attribute to indicate that the specified function has no
+caller-saved registers. That is, all registers are callee-saved except for
+registers used for passing parameters to the function or returning parameters
+from the function.
+The compiler saves and restores any modified registers that were not used for
+passing or returning arguments to the function.
+
+The user can call functions specified with the `no_caller_saved_registers`
+attribute from an interrupt handler without saving and restoring all
+call-clobbered registers.
+
+Functions specified with the `no_caller_saved_registers` attribute should only
+call other functions with the `no_caller_saved_registers` attribute, or should be
+compiled with the `-mgeneral-regs-only` flag to avoid saving unused non-GPR registers.
+
+Note that `no_caller_saved_registers` attribute is not a calling convention.
+In fact, it only overrides the decision of which registers should be saved by
+the caller, but not how the parameters are passed from the caller to the callee.
+
+For example:
+
+```c
+__attribute__ ((no_caller_saved_registers, fastcall))
+void f (int arg1, int arg2) {
+ ...
+}
+```
+
+In this case parameters `arg1` and `arg2` will be passed in registers.
+In this case, on 32-bit x86 targets, the function `f` will use ECX and EDX as
+register parameters. However, it will not assume any scratch registers and
+should save and restore any modified registers except for ECX and EDX.
+
+
+### no_outline
+
+{clang-attr-syntaxes}`NoOutlineDocs`
+
+This function attribute suppresses outlining from the annotated function.
+
+Outlining is the process where common parts of separate functions are extracted
+into a separate function (or assembly snippet), and calls to that function or
+snippet are inserted in the original functions. In this way, it can be seen as
+the opposite of inlining. It can help to reduce code size.
+
+
+### no_profile_instrument_function
+
+{clang-attr-syntaxes}`NoProfileInstrumentFunctionDocs`
+
+Use the `no_profile_instrument_function` attribute on a function declaration
+to denote that the compiler should not instrument the function with
+profile-related instrumentation, such as via the
+`-fprofile-generate` / `-fprofile-instr-generate` /
+`-fcs-profile-generate` / `-fprofile-arcs` flags.
+
+
+### no_sanitize
+
+{clang-attr-syntaxes}`NoSanitizeDocs`
+
+Use the `no_sanitize` attribute on a function or a global variable
+declaration to specify that a particular instrumentation or set of
+instrumentations should not be applied.
+
+The attribute takes a list of string literals with the following accepted
+values:
+
+- all values accepted by `-fno-sanitize=`;
+- `coverage`, to disable SanitizerCoverage instrumentation.
+
+For example, `__attribute__((no_sanitize("address", "thread")))` specifies
+that AddressSanitizer and ThreadSanitizer should not be applied to the function
+or variable. Using `__attribute__((no_sanitize("coverage")))` specifies that
+SanitizerCoverage should not be applied to the function.
+
+See {ref}`Controlling Code Generation <controlling-code-generation>` for a
+full list of supported sanitizer flags.
+
+
+(langext-address_sanitizer)=
+
+### no_sanitize_address, no_address_safety_analysis
+
+{clang-attr-syntaxes}`NoSanitizeAddressDocs`
+
+Use `__attribute__((no_sanitize_address))` on a function or a global
+variable declaration to specify that address safety instrumentation
+(e.g. AddressSanitizer) should not be applied.
+
+
+(langext-memory_sanitizer)=
+
+### no_sanitize_memory
+
+{clang-attr-syntaxes}`NoSanitizeMemoryDocs`
+
+Use `__attribute__((no_sanitize_memory))` on a function declaration to
+specify that checks for uninitialized memory should not be inserted
+(e.g. by MemorySanitizer). The function may still be instrumented by the tool
+to avoid false positives in other places.
+
+
+(langext-thread_sanitizer)=
+
+### no_sanitize_thread
+
+{clang-attr-syntaxes}`NoSanitizeThreadDocs`
+
+Use `__attribute__((no_sanitize_thread))` on a function declaration to
+specify that checks for data races on plain (non-atomic) memory accesses should
+not be inserted by ThreadSanitizer. The function is still instrumented by the
+tool to avoid false positives and provide meaningful stack traces.
+
+
+### no_speculative_load_hardening
+
+{clang-attr-syntaxes}`NoSpeculativeLoadHardeningDocs`
+
+This attribute can be applied to a function declaration in order to indicate
+that [Speculative Load Hardening][slh] is *not* needed for the function body.
+This can also be applied to a method in Objective C. This attribute will take
+precedence over the command line flag in the case where
+{option}`-mspeculative-load-hardening` is specified.
+
+Warning: This attribute may not prevent Speculative Load Hardening from being
+enabled for a function which inlines a function that has the
+`speculative_load_hardening` attribute. This is intended to provide a
+maximally conservative model where the code that is marked with the
+`speculative_load_hardening` attribute will always (even when inlined)
+be hardened. A user of this attribute may want to mark functions called by
+a function they do not want to be hardened with the `noinline` attribute.
+
+For example:
+
+```c
+__attribute__((speculative_load_hardening))
+int foo(int i) {
+ return i;
+}
+
+// Note: bar() may still have speculative load hardening enabled if
+// foo() is inlined into bar(). Mark foo() with __attribute__((noinline))
+// to avoid this situation.
+__attribute__((no_speculative_load_hardening))
+int bar(int i) {
+ return foo(i);
+}
+```
+
+
+### no_split_stack
+
+{clang-attr-syntaxes}`NoSplitStackDocs`
+
+The `no_split_stack` attribute disables the emission of the split stack
+preamble for a particular function. It has no effect if `-fsplit-stack`
+is not specified.
+
+
+### no_stack_protector, safebuffers
+
+{clang-attr-syntaxes}`NoStackProtectorDocs`
+
+Clang supports the GNU style `__attribute__((no_stack_protector))` and Microsoft
+style `__declspec(safebuffers)` attribute which disables
+the stack protector on the specified function. This attribute is useful for
+selectively disabling the stack protector on some functions when building with
+`-fstack-protector` compiler option.
+
+For example, it disables the stack protector for the function `foo` but function
+`bar` will still be built with the stack protector with the `-fstack-protector`
+option.
+
+```c
+int __attribute__((no_stack_protector))
+foo (int x); // stack protection will be disabled for foo.
+
+int bar(int y); // bar can be built with the stack protector.
+```
+
+
+### noalias
+
+{clang-attr-syntaxes}`NoAliasDocs`
+
+The `noalias` attribute indicates that the only memory accesses inside
+function are loads and stores from objects pointed to by its pointer-typed
+arguments, with arbitrary offsets.
+
+
+### nocf_check
+
+{clang-attr-syntaxes}`AnyX86NoCfCheckDocs`
+
+Jump Oriented Programming attacks rely on tampering with addresses used by
+indirect call / jmp, e.g. redirect control-flow to non-programmer
+intended bytes in the binary.
+X86 Supports Indirect Branch Tracking (IBT) as part of Control-Flow
+Enforcement Technology (CET). IBT instruments ENDBR instructions used to
+specify valid targets of indirect call / jmp.
+The `nocf_check` attribute has two roles:
+1\. Appertains to a function - do not add ENDBR instruction at the beginning of
+the function.
+2\. Appertains to a function pointer - do not track the target function of this
+pointer (by adding nocf_check prefix to the indirect-call instruction).
+
+
+### noconvergent
+
+{clang-attr-syntaxes}`NoConvergentDocs`
+
+This attribute prevents a function from being treated as convergent; when a
+function is marked `noconvergent`, calls to that function are not
+automatically assumed to be convergent, unless such calls are explicitly marked
+as `convergent`. If a statement is marked as `noconvergent`, any calls to
+inline `asm` in that statement are no longer treated as convergent.
+
+In languages following SPMD/SIMT programming model, e.g., CUDA/HIP, function
+declarations and inline asm calls are treated as convergent by default for
+correctness. This `noconvergent` attribute is helpful for developers to
+prevent them from being treated as convergent when it's safe.
+
+```c
+__device__ float bar(float);
+__device__ float foo(float) __attribute__((noconvergent)) {}
+
+__device__ int example(void) {
+ float x;
+ [[clang::noconvergent]] x = bar(x); // no effect on convergence
+ [[clang::noconvergent]] { asm volatile ("nop"); } // the asm call is non-convergent
+}
+```
+
+
+### nodiscard, warn_unused_result
+
+{clang-attr-syntaxes}`WarnUnusedResultsDocs`
+
+Clang supports the ability to diagnose when the results of a function call
+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`.
+
+A string literal may optionally be provided to the attribute, which will be
+reproduced in any resulting diagnostics. Redeclarations using different forms
+of the attribute (with or without the string literal or with different string
+literal contents) are allowed. If there are redeclarations of the entity with
+differing string literals, it is unspecified which one will be used by Clang
+in any resulting diagnostics.
+
+```c++
+struct [[nodiscard]] error_info { /*...*/ };
+error_info enable_missile_safety_mode();
+
+void launch_missiles();
+void test_missiles() {
+ enable_missile_safety_mode(); // diagnoses
+ launch_missiles();
+}
+error_info &foo();
+void f() { foo(); } // Does not diagnose, error_info is a reference.
+```
+
+Additionally, discarded temporaries resulting from a call to a constructor
+marked with `[[nodiscard]]` or a constructor of a type marked
+`[[nodiscard]]` will also diagnose. This also applies to type conversions that
+use the annotated `[[nodiscard]]` constructor or result in an annotated type.
+
+```c++
+struct [[nodiscard]] marked_type {/*..*/ };
+struct marked_ctor {
+ [[nodiscard]] marked_ctor();
+ marked_ctor(int);
+};
+
+struct S {
+ operator marked_type() const;
+ [[nodiscard]] operator int() const;
+};
+
+void usages() {
+ marked_type(); // diagnoses.
+ marked_ctor(); // diagnoses.
+ marked_ctor(3); // Does not diagnose, int constructor isn't marked nodiscard.
+
+ S s;
+ static_cast<marked_type>(s); // diagnoses
+ (int)s; // diagnoses
+}
+```
+
+
+### noduplicate
+
+{clang-attr-syntaxes}`NoDuplicateDocs`
+
+The `noduplicate` attribute can be placed on function declarations to control
+whether function calls to this function can be duplicated or not as a result of
+optimizations. This is required for the implementation of functions with
+certain special requirements, like the OpenCL "barrier" function, that might
+need to be run concurrently by all the threads that are executing in lockstep
+on the hardware. For example this attribute applied on the function
+`nodupfunc` in the code below avoids that:
+
+```c
+void nodupfunc() __attribute__((noduplicate));
+// Setting it as a C++11 attribute is also valid
+// void nodupfunc() [[clang::noduplicate]];
+void foo();
+void bar();
+
+nodupfunc();
+if (a > n) {
+ foo();
+} else {
+ bar();
+}
+```
+
+gets possibly modified by some optimizations into code similar to this:
+
+```c
+if (a > n) {
+ nodupfunc();
+ foo();
+} else {
+ nodupfunc();
+ bar();
+}
+```
+
+where the call to `nodupfunc` is duplicated and sunk into the two branches
+of the condition.
+
+
+### noinline
+
+{clang-attr-syntaxes}`NoInlineDocs`
+
+This function attribute suppresses the inlining of a function at the call sites
+of the function.
+
+`[[clang::noinline]]` spelling can be used as a statement attribute; other
+spellings of the attribute are not supported on statements. If a statement is
+marked `[[clang::noinline]]` and contains calls, those calls inside the
+statement will not be inlined by the compiler.
+
+`__noinline__` can be used as a keyword in CUDA/HIP languages. This is to
+avoid diagnostics due to usage of `__attribute__((__noinline__))`
+with `__noinline__` defined as a macro as `__attribute__((noinline))`.
+
+```c
+int example(void) {
+ int r;
+ [[clang::noinline]] foo();
+ [[clang::noinline]] r = bar();
+ return r;
+}
+```
+
+
+### noreturn, _Noreturn
+
+{clang-attr-syntaxes}`CXX11NoReturnDocs`
+
+A function declared as `[[noreturn]]` shall not return to its caller. The
+compiler will generate a diagnostic for a function declared as `[[noreturn]]`
+that appears to be capable of returning to its caller.
+
+The `[[_Noreturn]]` spelling is deprecated and only exists to ease code
+migration for code using `[[noreturn]]` after including `<stdnoreturn.h>`.
+
+
+### not_tail_called
+
+{clang-attr-syntaxes}`NotTailCalledDocs`
+
+The `not_tail_called` attribute prevents tail-call optimization on statically
+bound calls. Objective-c methods, and functions marked as `always_inline`
+cannot be marked as `not_tail_called`.
+
+For example, it prevents tail-call optimization in the following case:
+
+```c
+int __attribute__((not_tail_called)) foo1(int);
+
+int foo2(int a) {
+ return foo1(a); // No tail-call optimization on direct calls.
+}
+```
+
+However, it doesn't prevent tail-call optimization in this case:
+
+```c
+int __attribute__((not_tail_called)) foo1(int);
+
+int foo2(int a) {
+ int (*fn)(int) = &foo1;
+
+ // not_tail_called has no effect on an indirect call even if the call can
+ // be resolved at compile time.
+ return (*fn)(a);
+}
+```
+
+Generally, marking an overriding virtual function as `not_tail_called` is
+not useful, because this attribute is a property of the static type. Calls
+made through a pointer or reference to the base class type will respect
+the `not_tail_called` attribute of the base class's member function,
+regardless of the runtime destination of the call:
+
+```c++
+struct Foo { virtual void f(); };
+struct Bar : Foo {
+ [[clang::not_tail_called]] void f() override;
+};
+void callera(Bar& bar) {
+ Foo& foo = bar;
+ // not_tail_called has no effect on here, even though the
+ // underlying method is f from Bar.
+ foo.f();
+ bar.f(); // No tail-call optimization on here.
+}
+```
+
+
+### nothrow
+
+{clang-attr-syntaxes}`NoThrowDocs`
+
+Clang supports the GNU style `__attribute__((nothrow))` and Microsoft style
+`__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
+guaranteed to not throw an exception.
+
+
+### nouwtable
+
+{clang-attr-syntaxes}`NoUwtableDocs`
+
+Clang supports the `nouwtable` attribute which skips emitting
+the unwind table entry for the specified function. This attribute is useful for
+selectively emitting the unwind table entry on some functions when building with
+`-funwind-tables` compiler option.
+
+
+### numthreads
+
+{clang-attr-syntaxes}`NumThreadsDocs`
+
+The `numthreads` attribute applies to HLSL shaders where explcit thread counts
+are required. The `X`, `Y`, and `Z` values provided to the attribute
+dictate the thread id. Total number of threads executed is `X * Y * Z`.
+
+The full documentation is available here: <https://docs.microsoft.com/en-us/windows/win32/direct3dhlsl/sm5-attributes-numthreads>
+
+
+### objc_method_family
+
+{clang-attr-syntaxes}`ObjCMethodFamilyDocs`
+
+Many methods in Objective-C have conventional meanings determined by their
+selectors. It is sometimes useful to be able to mark a method as having a
+particular conventional meaning despite not having the right selector, or as
+not having the conventional meaning that its selector would suggest. For these
+use cases, we provide an attribute to specifically describe the "method family"
+that a method belongs to.
+
+**Usage**: `__attribute__((objc_method_family(X)))`, where `X` is one of
+`none`, `alloc`, `copy`, `init`, `mutableCopy`, or `new`. This
+attribute can only be placed at the end of a method declaration:
+
+```objc
+- (NSString *)initMyStringValue __attribute__((objc_method_family(none)));
+```
+
+Users who do not wish to change the conventional meaning of a method, and who
+merely want to document its non-standard retain and release semantics, should
+use the retaining behavior attributes (`ns_returns_retained`,
+`ns_returns_not_retained`, etc).
+
+Query for this feature with `__has_attribute(objc_method_family)`.
+
+
+### objc_requires_super
+
+{clang-attr-syntaxes}`ObjCRequiresSuperDocs`
+
+Some Objective-C classes allow a subclass to override a particular method in a
+parent class but expect that the overriding method also calls the overridden
+method in the parent class. For these cases, we provide an attribute to
+designate that a method requires a "call to `super`" in the overriding
+method in the subclass.
+
+**Usage**: `__attribute__((objc_requires_super))`. This attribute can only
+be placed at the end of a method declaration:
+
+```objc
+- (void)foo __attribute__((objc_requires_super));
+```
+
+This attribute can only be applied the method declarations within a class, and
+not a protocol. Currently this attribute does not enforce any placement of
+where the call occurs in the overriding method (such as in the case of
+`-dealloc` where the call must appear at the end). It checks only that it
+exists.
+
+Note that on both OS X and iOS that the Foundation framework provides a
+convenience macro `NS_REQUIRES_SUPER` that provides syntactic sugar for this
+attribute:
+
+```objc
+- (void)foo NS_REQUIRES_SUPER;
+```
+
+This macro is conditionally defined depending on the compiler's support for
+this attribute. If the compiler does not support the attribute the macro
+expands to nothing.
+
+Operationally, when a method has this annotation the compiler will warn if the
+implementation of an override in a subclass does not call super. For example:
+
+```objc
+warning: method possibly missing a [super AnnotMeth] call
+- (void) AnnotMeth{};
+ ^
+```
+
+
+### optnone
+
+{clang-attr-syntaxes}`OptnoneDocs`
+
+The `optnone` attribute suppresses essentially all optimizations
+on a function or method, regardless of the optimization level applied to
+the compilation unit as a whole. This is particularly useful when you
+need to debug a particular function, but it is infeasible to build the
+entire application without optimization. Avoiding optimization on the
+specified function can improve the quality of the debugging information
+for that function.
+
+This attribute is incompatible with the `always_inline` and `minsize`
+attributes.
+
+Note that this attribute does not apply recursively to nested functions such as
+lambdas or blocks when using declaration-specific attribute syntaxes such as double
+square brackets (`[[]]`) or `__attribute__`. The `#pragma` syntax can be
+used to apply the attribute to all functions, including nested functions, in a
+range of source code.
+
+
+### overloadable
+
+{clang-attr-syntaxes}`OverloadableDocs`
+
+Clang provides support for C++ function overloading in C. Function overloading
+in C is introduced using the `overloadable` attribute. For example, one
+might provide several overloaded versions of a `tgsin` function that invokes
+the appropriate standard function computing the sine of a value with `float`,
+`double`, or `long double` precision:
+
+```c
+#include <math.h>
+float __attribute__((overloadable)) tgsin(float x) { return sinf(x); }
+double __attribute__((overloadable)) tgsin(double x) { return sin(x); }
+long double __attribute__((overloadable)) tgsin(long double x) { return sinl(x); }
+```
+
+Given these declarations, one can call `tgsin` with a `float` value to
+receive a `float` result, with a `double` to receive a `double` result,
+etc. Function overloading in C follows the rules of C++ function overloading
+to pick the best overload given the call arguments, with a few C-specific
+semantics:
+
+- Conversion from `float` or `double` to `long double` is ranked as a
+ floating-point promotion (per C99) rather than as a floating-point conversion
+ (as in C++).
+- A conversion from a pointer of type `T*` to a pointer of type `U*` is
+ considered a pointer conversion (with conversion rank) if `T` and `U` are
+ compatible types.
+- A conversion from type `T` to a value of type `U` is permitted if `T`
+ and `U` are compatible types. This conversion is given "conversion" rank.
+- If no viable candidates are otherwise available, we allow a conversion from a
+ pointer of type `T*` to a pointer of type `U*`, where `T` and `U` are
+ incompatible. This conversion is ranked below all other types of conversions.
+ Please note: `U` lacking qualifiers that are present on `T` is sufficient
+ for `T` and `U` to be incompatible.
+
+The declaration of `overloadable` functions is restricted to function
+declarations and definitions. If a function is marked with the `overloadable`
+attribute, then all declarations and definitions of functions with that name,
+except for at most one (see the note below about unmarked overloads), must have
+the `overloadable` attribute. In addition, redeclarations of a function with
+the `overloadable` attribute must have the `overloadable` attribute, and
+redeclarations of a function without the `overloadable` attribute must *not*
+have the `overloadable` attribute. e.g.,
+
+```c
+int f(int) __attribute__((overloadable));
+float f(float); // error: declaration of "f" must have the "overloadable" attribute
+int f(int); // error: redeclaration of "f" must have the "overloadable" attribute
+
+int g(int) __attribute__((overloadable));
+int g(int) { } // error: redeclaration of "g" must also have the "overloadable" attribute
+
+int h(int);
+int h(int) __attribute__((overloadable)); // error: declaration of "h" must not
+ // have the "overloadable" attribute
+```
+
+Functions marked `overloadable` must have prototypes. Therefore, the
+following code is ill-formed:
+
+```c
+int h() __attribute__((overloadable)); // error: h does not have a prototype
+```
+
+However, `overloadable` functions are allowed to use a ellipsis even if there
+are no named parameters (as is permitted in C++). This feature is particularly
+useful when combined with the `unavailable` attribute:
+
+```c++
+void honeypot(...) __attribute__((overloadable, unavailable)); // calling me is an error
+```
+
+Functions declared with the `overloadable` attribute have their names mangled
+according to the same rules as C++ function names. For example, the three
+`tgsin` functions in our motivating example get the mangled names
+`_Z5tgsinf`, `_Z5tgsind`, and `_Z5tgsine`, respectively. There are two
+caveats to this use of name mangling:
+
+- Future versions of Clang may change the name mangling of functions overloaded
+ in C, so you should not depend on an specific mangling. To be completely
+ safe, we strongly urge the use of `static inline` with `overloadable`
+ functions.
+- The `overloadable` attribute has almost no meaning when used in C++,
+ because names will already be mangled and functions are already overloadable.
+ However, when an `overloadable` function occurs within an `extern "C"`
+ linkage specification, its name *will* be mangled in the same way as it
+ would in C.
+
+For the purpose of backwards compatibility, at most one function with the same
+name as other `overloadable` functions may omit the `overloadable`
+attribute. In this case, the function without the `overloadable` attribute
+will not have its name mangled.
+
+For example:
+
+```c
+// Notes with mangled names assume Itanium mangling.
+int f(int);
+int f(double) __attribute__((overloadable));
+void foo() {
+ f(5); // Emits a call to f (not _Z1fi, as it would with an overload that
+ // was marked with overloadable).
+ f(1.0); // Emits a call to _Z1fd.
+}
+```
+
+Support for unmarked overloads is not present in some versions of clang. You may
+query for it using `__has_extension(overloadable_unmarked)`.
+
+Query for this attribute with `__has_attribute(overloadable)`.
+
+
+(analyzer-ownership-attrs)=
+
+### ownership_holds, ownership_returns, ownership_takes (Clang Static Analyzer)
+
+{clang-attr-syntaxes}`OwnershipDocs`
+
+:::{note}
+In order for the Clang Static Analyzer to acknowledge these attributes, the
+`Optimistic` config needs to be set to true for the checker
+`unix.DynamicMemoryModeling`:
+
+`-Xclang -analyzer-config -Xclang unix.DynamicMemoryModeling:Optimistic=true`
+:::
+
+These attributes are used by the Clang Static Analyzer's dynamic memory modeling
+facilities to mark custom allocating/deallocating functions.
+
+All 3 attributes' first parameter of type string is the type of the allocation:
+`malloc`, `new`, etc. to allow for catching {ref}`mismatched deallocation
+<unix-MismatchedDeallocator>` bugs. The allocation type can be any string, e.g.
+a function annotated with
+returning a piece of memory of type `lasagna` but freed with a function
+annotated to release `cheese` typed memory will result in mismatched
+deallocation warning.
+
+The (currently) only allocation type having special meaning is `malloc` --
+the Clang Static Analyzer makes sure that allocating functions annotated with
+`malloc` are treated like they used the standard `malloc()`, and can be
+safely deallocated with the standard `free()`.
+
+- Use `ownership_returns` to mark a function as an allocating function.
+ It takes 1 or 2 arguments.
+ The first argument is a user-provided identifier representing the "kind" of the allocation.
+ This is basically what is enforced when checking the deallocation. This is mandatory.
+ The second argument is optional.
+ It represents the index of the parameter that represents the allocation size in bytes (counting from 1).
+ The referenced parameter must have some integral type.
+ This attribute may appear at most once per declaration.
+ If this argument is not set, then tooling, such as the Clang Static Analyzer,
+ won't be able to reason about the size of the allocation, thus check potential out-of-bounds accesses.
+ However, such tooling could still warn if the wrong deallocation function
+ was used for the `ownership_returns` attributed resource.
+ If forward declarations have this attribute, those must have the same arguments.
+- Use `ownership_takes` to mark a function as a deallocating function. Takes 2
+ arguments: the allocation type, and the index of the parameter that is being
+ deallocated (counting from 1).
+- Use `ownership_holds` to mark that a function takes over the ownership of a
+ piece of memory and will free it at some unspecified point in the future. Like
+ `ownership_takes`, this takes 2 arguments: the allocation type, and the
+ index of the parameter whose ownership will be taken over (counting from 1).
+
+The annotations `ownership_takes` and `ownership_holds` both prevent memory
+leak reports (concerning the specified parameter); the difference between them
+is that using taken memory is a use-after-free error, while using held memory
+is assumed to be legitimate. However, releasing the held memory or passing it
+to another holding call is reported by the analyzer as an "attempt to release
+non-owned memory".
+
+Example:
+
+```c
+// Denotes that my_malloc will return with a dynamically allocated piece of
+// memory using malloc().
+void __attribute((ownership_returns(malloc))) *my_malloc(size_t sz);
+
+// 'sz' (parameter 1) is the allocation size.
+void __attribute((ownership_returns(malloc, 1))) *my_sized_malloc(size_t sz);
+
+// Denotes that my_free will deallocate its argument using free().
+void __attribute((ownership_takes(malloc, 1))) my_free(void *);
+
+// Denotes that my_hold will take over the ownership of its argument that was
+// allocated via malloc().
+void __attribute((ownership_holds(malloc, 1))) my_hold(void *);
+```
+
+Further reading about dynamic memory modeling in the Clang Static Analyzer is
+found in these checker docs:
+{ref}`unix.Malloc <unix-Malloc>`, {ref}`unix.MallocSizeof <unix-MallocSizeof>`,
+{ref}`unix.MismatchedDeallocator <unix-MismatchedDeallocator>`,
+{ref}`cplusplus.NewDelete <cplusplus-NewDelete>`,
+{ref}`cplusplus.NewDeleteLeaks <cplusplus-NewDeleteLeaks>`,
+{ref}`optin.taint.TaintedAlloc <optin-taint-TaintedAlloc>`.
+Mind that many more checkers are affected by dynamic memory modeling changes to
+some extent.
+
+Further reading for other annotations:
+{doc}`Static Analyzer source annotations <analyzer/user-docs/Annotations>`.
+
+
+### packoffset
+
+{clang-attr-syntaxes}`HLSLPackOffsetDocs`
+
+The packoffset attribute is used to change the layout of a cbuffer.
+Attribute spelling in HLSL is: `packoffset( c[Subcomponent][.component] )`.
+A subcomponent is a register number, which is an integer. A component is in the form of [.xyzw].
+
+Examples:
+
+```hlsl
+cbuffer A {
+ float3 a : packoffset(c0.y);
+ float4 b : packoffset(c4);
+}
+```
+
+The full documentation is available here: <https://learn.microsoft.com/en-us/windows/win32/direct3dhlsl/dx-graphics-hlsl-variable-packoffset>
+
+
+### patchable_function_entry
+
+{clang-attr-syntaxes}`PatchableFunctionEntryDocs`
+
+`__attribute__((patchable_function_entry(N,M,Section)))` is used to generate M
+NOPs before the function entry and N-M NOPs after the function entry, with a record of
+the entry stored in section `Section`. This attribute takes precedence over the
+command line option `-fpatchable-function-entry=N,M,Section`. `M` defaults to 0
+if omitted. `Section` defaults to the `-fpatchable-function-entry` section name if
+set, or to `__patchable_function_entries` otherwise.
+
+This attribute is only supported on
+aarch64/aarch64-be/loongarch32/loongarch64/riscv32/riscv64/i386/x86-64/ppc/ppc64/ppc64le/s390x targets.
+For ppc/ppc64 targets, AIX is still not supported.
+
+
+### personality
+
+{clang-attr-syntaxes}`PersonalityDocs`
+
+`__attribute__((personality(<routine>)))` is used to specify a personality
+routine that is different from the language that is being used to implement the
+function. This is a targeted, low-level feature aimed at language runtime
+implementors who write runtime support code in C/C++ but need that code to
+participate in a foreign language's exception-handling or unwinding model.
+
+A personality routine is a language-specific callback attached to each stack
+frame that the unwinder invokes to determine whether that frame handles a given
+exception and what cleanup actions to perform. It effectively colors the
+language-agnostic unwinding mechanism with language-specific semantics, enabling
+different languages to coexist on the same call stack while each interpreting
+exceptions according to their own rules.
+
+
+### preserve_access_index
+
+{clang-attr-syntaxes}`BPFPreserveAccessIndexDocs`
+
+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 indices of this
+struct or union, similar to clang `__builtin_preserve_access_index()`.
+
+
+### preserve_static_offset
+
+{clang-attr-syntaxes}`BPFPreserveStaticOffsetDocs`
+
+Clang supports the `__attribute__((preserve_static_offset))`
+attribute for the BPF target. This attribute may be attached to a
+struct or union declaration. Reading or writing fields of types having
+such annotation is guaranteed to generate LDX/ST/STX instruction with
+offset corresponding to the field.
+
+For example:
+
+```c
+struct foo {
+ int a;
+ int b;
+};
+
+struct bar {
+ int a;
+ struct foo b;
+} __attribute__((preserve_static_offset));
+
+void buz(struct bar *g) {
+ g->b.a = 42;
+}
+```
+
+The assignment to `g`'s field would produce an ST instruction with
+offset 8: `*(u32)(r1 + 8) = 42;`.
+
+Without this attribute generated instructions might be different,
+depending on optimizations behavior. E.g. the example above could be
+rewritten as `r1 += 8; *(u32)(r1 + 0) = 42;`.
+
+
+### register
+
+{clang-attr-syntaxes}`HLSLResourceBindingDocs`
+
+The resource binding attribute sets the virtual register and logical register space for a resource.
+Attribute spelling in HLSL is: `register(slot [, space])`.
+`slot` takes the format `[type][number]`,
+where `type` is a single character specifying the resource type and `number` is the virtual register number.
+
+Register types are:
+t for shader resource views (SRV),
+s for samplers,
+u for unordered access views (UAV),
+b for constant buffer views (CBV).
+
+Register space is specified in the format `space[number]` and defaults to `space0` if omitted.
+Here're resource binding examples with and without space:
+
+```hlsl
+RWBuffer<float> Uav : register(u3, space1);
+Buffer<float> Buf : register(t1);
+```
+
+The full documentation is available here: <https://docs.microsoft.com/en-us/windows/win32/direct3d12/resource-binding-in-hlsl>
+
+
+### reinitializes
+
+{clang-attr-syntaxes}`ReinitializesDocs`
+
+The `reinitializes` attribute can be applied to a non-static, non-const C++
+member function to indicate that this member function reinitializes the entire
+object to a known state, independent of the previous state of the object.
+
+This attribute can be interpreted by static analyzers that warn about uses of an
+object that has been left in an indeterminate state by a move operation. If a
+member function marked with the `reinitializes` attribute is called on a
+moved-from object, the analyzer can conclude that the object is no longer in an
+indeterminate state.
+
+A typical example where this attribute would be used is on functions that clear
+a container class:
+
+```c++
+template <class T>
+class Container {
+public:
+ ...
+ [[clang::reinitializes]] void Clear();
+ ...
+};
+```
+
+
+### release_capability, release_shared_capability
+
+{clang-attr-syntaxes}`ReleaseCapabilityDocs`
+
+Marks a function as releasing a capability.
+
+
+### retain
+
+{clang-attr-syntaxes}`RetainDocs`
+
+This attribute, when attached to a function or variable definition, prevents
+section garbage collection in the linker. It does not prevent other discard
+mechanisms, such as archive member selection, and COMDAT group resolution.
+
+If the compiler does not emit the definition, e.g. because it was not used in
+the translation unit or the compiler was able to eliminate all of the uses,
+this attribute has no effect. This attribute is typically combined with the
+`used` attribute to force the definition to be emitted and preserved into the
+final linked image.
+
+This attribute is only necessary on ELF targets; other targets prevent section
+garbage collection by the linker when using the `used` attribute alone.
+Using the attributes together should result in consistent behavior across
+targets.
+
+This attribute requires the linker to support the `SHF_GNU_RETAIN` extension.
+This support is available in GNU `ld` and `gold` as of binutils 2.36, as
+well as in `ld.lld` 13.
+
+
+### sentinel
+
+{clang-attr-syntaxes}`SentinelDocs`
+
+The `sentinel` attribute can be applied to variadic functions and pointers to
+variadic functions, to diagnose each function call that does not pass a
+sentinel value (a null pointer constant) as the last argument to the function
+call. The attribute accepts two optional arguments: the first argument is the
+position of the expected sentinel value, starting from the last parameter. The
+second argument describes whether the last fixed parameter is treated as a
+valid sentinel value when set to `1`.
+All arguments described above default to `0` when elided.
+The attribute is also supported with blocks and in Objective-C.
+
+```c
+void foo(const char*, ...) __attribute__((sentinel));
+void bar(int, ...) __attribute__((sentinel(1)));
+void baz(const char*, const char*, ...) __attribute__((sentinel(0, 1)));
+
+void example() {
+ foo("Example", (void*)0);
+ foo("Another", "example", NULL);
+ foo("Missing", "sentinel"); // Not OK
+
+ bar(1, 2, NULL, 3); // OK: sentinel value at the 2nd to last position
+ bar(1, 2, 3, nullptr, 4); // OK: `nullptr` is valid in C23
+ bar(1, 2, 3, 4, NULL); // Not OK
+
+ baz("Test", "with", "multiple", "args", NULL);
+ baz("One", NULL); // OK: last fixed parameter is a valid sentinel
+
+ void (*ptr) (int arg, ...) __attribute__ ((__sentinel__));
+ ptr(1, 2, 3, NULL);
+}
+```
+
+```c++
+struct Ty {
+ int value;
+
+ template<typename T>
+ auto&& foo(T&& val, ...) __attribute__((sentinel(1))) {
+ return std::forward<T>(val);
+ }
+
+ template<class Self>
+ auto&& bar(this Self&& self, ...) __attribute__((sentinel(1))) {
+ return std::forward<Self>(self).value;
+ }
+};
+
+void example2() {
+ auto sty = Ty{};
+ sty.foo(1, nullptr, 3);
+ sty.bar(1, nullptr, 3);
+
+ auto lmbd = [](int a, ...) __attribute__((sentinel)) {};
+ lmbd(1, 2, nullptr);
+}
+```
+
+
+### shader
+
+{clang-attr-syntaxes}`HLSLSV_ShaderTypeAttrDocs`
+
+The `shader` type attribute applies to HLSL shader entry functions to
+identify the shader type for the entry function.
+The syntax is:
+
+```text
+[shader(string-literal)]
+```
+
+where the string literal is one of: "pixel", "vertex", "geometry", "hull",
+"domain", "compute", "raygeneration", "intersection", "anyhit", "closesthit",
+"miss", "callable", "mesh", "amplification". Normally the shader type is set
+by shader target with the `-T` option like `-Tps_6_1`. When compiling to a
+library target like `lib_6_3`, the shader type attribute can help the
+compiler to identify the shader type. It is mostly used by Raytracing shaders
+where shaders must be compiled into a library and linked at runtime.
+
+
+### short_call, near
+
+{clang-attr-syntaxes}`MipsShortCallStyleDocs`
+
+Clang supports the `__attribute__((long_call))`, `__attribute__((far))`,
+`__attribute__((short__call))`, and `__attribute__((near))` attributes
+on MIPS targets. These attributes may only be added to function declarations
+and change the code generated by the compiler when directly calling
+the function. The `short_call` and `near` attributes are synonyms and
+allow calls to the function to be made using the `jal` instruction, which
+requires the function to be located in the same naturally aligned 256MB segment
+as the caller. The `long_call` and `far` attributes are synonyms and
+require the use of a different call sequence that works regardless
+of the distance between the functions.
+
+These attributes have no effect for position-independent code.
+
+These attributes take priority over command line switches such
+as `-mlong-calls` and `-mno-long-calls`.
+
+
+### signal
+
+{clang-attr-syntaxes}`AVRSignalDocs`
+
+Clang supports the GNU style `__attribute__((signal))` attribute on
+AVR targets. This attribute may be attached to a function definition and instructs
+the backend to generate appropriate function entry/exit code so that it can be used
+directly as an interrupt service routine.
+
+Interrupt handler functions defined with the signal attribute do not re-enable interrupts.
+
+
+### speculative_load_hardening
+
+{clang-attr-syntaxes}`SpeculativeLoadHardeningDocs`
+
+This attribute can be applied to a function declaration in order to indicate
+that [Speculative Load Hardening][slh]
+should be enabled for the function body. This can also be applied to a method
+in Objective C. This attribute will take precedence over the command line flag
+in the case where {option}`-mno-speculative-load-hardening` is specified.
+
+[slh]: https://llvm.org/docs/SpeculativeLoadHardening.html
+
+Speculative Load Hardening is a best-effort mitigation against
+information leak attacks that make use of control flow
+miss-speculation - specifically miss-speculation of whether a branch
+is taken or not. Typically vulnerabilities enabling such attacks are
+classified as "Spectre variant #1". Notably, this does not attempt to
+mitigate against miss-speculation of branch target, classified as
+"Spectre variant #2" vulnerabilities.
+
+When inlining, the attribute is sticky. Inlining a function that
+carries this attribute will cause the caller to gain the
+attribute. This is intended to provide a maximally conservative model
+where the code in a function annotated with this attribute will always
+(even after inlining) end up hardened.
+
+
+### stack_protector_ignore
+
+{clang-attr-syntaxes}`StackProtectorIgnoreDocs`
+
+The `stack_protector_ignore` attribute skips analysis of the given local
+variable when determining if a function should use a stack protector.
+
+The `-fstack-protector` option uses a heuristic to only add stack protectors
+to functions which contain variables or buffers over some size threshold. This
+attribute overrides that heuristic for the attached variable, opting
+them out. If this results in no variables or buffers remaining over the stack
+protector threshold, then the function will no longer use a stack protector.
+
+
+### strict_gs_check
+
+{clang-attr-syntaxes}`StrictGuardStackCheckDocs`
+
+Clang supports the Microsoft style `__declspec((strict_gs_check))` attribute
+which upgrades the stack protector check from `-fstack-protector` to
+`-fstack-protector-strong`.
+
+For example, it upgrades the stack protector for the function `foo` to
+`-fstack-protector-strong` but function `bar` will still be built with the
+stack protector with the `-fstack-protector` option.
+
+```c
+__declspec((strict_gs_check))
+int foo(int x); // stack protection will be upgraded for foo.
+
+int bar(int y); // bar can be built with the standard stack protector checks.
+```
+
+
+### sycl_external
+
+{clang-attr-syntaxes}`SYCLExternalDocs`
+
+The `sycl_external` attribute indicates that a function defined in another
+translation unit may be called by a device function defined in the current
+translation unit or, if defined in the current translation unit, the function
+may be called by device functions defined in other translation units.
+The attribute is intended for use in the implementation of the `SYCL_EXTERNAL`
+macro as specified in section 5.10.1, "SYCL functions and member functions
+linkage", of the SYCL 2020 specification.
+
+The attribute only appertains to functions and only those that meet the
+following requirements:
+
+- Has external linkage
+- Is not explicitly defined as deleted (the function may be an explicitly
+ defaulted function that is defined as deleted)
+
+The attribute shall be present on the first declaration of a function and
+may optionally be present on subsequent declarations.
+
+When compiling for a SYCL device target that does not support the generic
+address space, the function shall not specify a raw pointer or reference type
+as the return type or as a parameter type.
+See section 5.10, "SYCL offline linking", of the SYCL 2020 specification.
+The following examples demonstrate the use of this attribute:
+
+```c++
+[[clang::sycl_external]] void Foo(); // Ok.
+
+[[clang::sycl_external]] void Bar() { /* ... */ } // Ok.
+
+[[clang::sycl_external]] extern void Baz(); // Ok.
+
+[[clang::sycl_external]] static void Quux() { /* ... */ } // error: Quux() has internal linkage.
+```
+
+
+### sycl_kernel
+
+{clang-attr-syntaxes}`SYCLKernelDocs`
+
+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:
+
+```c++
+int foo(int x) { return ++x; }
+
+using namespace cl::sycl;
+queue Q;
+buffer<int, 1> a(range<1>{1024});
+Q.submit([&](handler& cgh) {
+ auto A = a.get_access<access::mode::write>(cgh);
+ cgh.parallel_for<init_a>(range<1>{1024}, [=](id<1> index) {
+ A[index] = index[0] + foo(42);
+ });
+}
+```
+
+A C++ function object passed to the `parallel_for` is called a "SYCL kernel".
+A SYCL kernel defines the entry point to the "device part" of the code. The
+compiler will emit all symbols accessible from a "kernel". In this code
+example, the compiler will emit "foo" function. More details about the
+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:
+
+```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
+```
+
+The compiler will also generate an OpenCL kernel using the function marked with
+the `sycl_kernel` attribute.
+Here is the list of SYCL device compiler expectations with regard to the
+function marked with the `sycl_kernel` attribute:
+
+- The function must be a template with at least two type template parameters.
+ The compiler generates an OpenCL kernel and uses the first template parameter
+ as a unique name for the generated OpenCL kernel. The host application uses
+ this unique name to invoke the OpenCL kernel generated for the SYCL kernel
+ specialized by this name and second template parameter `KernelType` (which
+ might be an unnamed function object type).
+- The function must have at least one parameter. The first parameter is
+ required to be a function object type (named or unnamed i.e. lambda). The
+ 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`.
+
+The SYCL kernel in the previous code sample meets these expectations.
+
+
+### sycl_kernel_entry_point
+
+{clang-attr-syntaxes}`SYCLKernelEntryPointDocs`
+
+The `sycl_kernel_entry_point` attribute facilitates the launch of a SYCL
+kernel and the generation of an offload kernel entry point, sometimes called
+a SYCL kernel caller function, suitable for invoking a SYCL kernel on an
+offload device. The attribute is intended for use in the implementation of
+SYCL kernel invocation functions like the `single_task` and `parallel_for`
+member functions of the `sycl::handler` class specified in section 4.9.4,
+"Command group `handler` class", of the SYCL 2020 specification.
+
+The attribute requires a single type argument that meets the requirements for
+a SYCL kernel name as described in section 5.2, "Naming of kernels", of the
+SYCL 2020 specification. A unique kernel name type is required for each
+function declared with the attribute. The attribute may not first appear on a
+declaration that follows a definition of the function.
+
+The attribute only appertains to functions and only those that meet the
+following requirements.
+
+- Has a non-deduced `void` return type.
+- Is not a constructor or destructor.
+- Is not a non-static member function with an explicit object parameter.
+- Is not a C variadic function.
+- Is not a coroutine.
+- Is not defined as deleted or as defaulted.
+- Is not defined with a function try block.
+- Is not declared with the `constexpr` or `consteval` specifiers.
+- Is not declared with the `[[noreturn]]` attribute.
+
+Use in the implementation of a SYCL kernel invocation function might look as
+follows.
+
+```c++
+namespace sycl {
+class handler {
+ template<typename KernelName, typename... Ts>
+ void sycl_kernel_launch(const char* kernelSymbol, Ts&&... kernelArgs) {
+ // This code will run on the host and is responsible for calling functions
+ // appropriate for the desired offload backend (OpenCL, CUDA, HIP,
+ // Level Zero, etc...) to copy the kernel arguments denoted by kernelArgs
+ // to a device and to schedule an invocation of the offload kernel entry
+ // point denoted by kernelSymbol with the copied arguments.
+ }
+
+ template<typename KernelName, typename KernelType>
+ [[ clang::sycl_kernel_entry_point(KernelName) ]]
+ void kernel_entry_point(KernelType kernelFunc) {
+ // This code will run on the device. The call to kernelFunc() invokes
+ // the SYCL kernel.
+ kernelFunc();
+ }
+
+public:
+ template<typename KernelName, typename KernelType>
+ void single_task(const KernelType& kernelFunc) {
+ // This code will run on the host. kernel_entry_point() is called to
+ // trigger generation of an offload kernel entry point and to schedule
+ // an invocation of it on a device with kernelFunc (a SYCL kernel object)
+ // passed as a kernel argument. This call will result in an implicit call
+ // to sycl_kernel_launch() with the symbol name for the generated offload
+ // kernel entry point passed as the first function argument followed by
+ // kernelFunc.
+ kernel_entry_point<KernelName>(kernelFunc);
+ }
+};
+} // namespace sycl
+```
+
+A SYCL kernel object is a callable object of class type that is constructed on
+a host, often via a lambda expression, and then passed to a SYCL kernel
+invocation function to be executed on an offload device. The `kernelFunc`
+parameters in the example code above correspond to SYCL kernel objects.
+
+A SYCL kernel object type is required to satisfy the device copyability
+requirements specified in section 3.13.1, "Device copyable", of the SYCL 2020
+specification. Additionally, any data members of the kernel object type are
+required to satisfy section 4.12.4, "Rules for parameter passing to kernels".
+For most types, these rules require that the type is trivially copyable.
+However, the SYCL specification mandates that certain special SYCL types, such
+as `sycl::accessor` and `sycl::stream`, be device copyable even if they are
+not trivially copyable. These types require special handling because they cannot
+necessarily be copied to device memory as if by `memcpy()`.
+
+The SYCL kernel object and its data members constitute the parameters of an
+offload kernel. An offload kernel consists of an offload entry point function
+and the set of all functions and variables that are directly or indirectly used
+by the entry point function.
+
+A SYCL kernel invocation function is responsible for performing the following
+tasks (likely with the help of an offload backend like OpenCL):
+
+1. Identifying the offload kernel entry point to be used for the SYCL kernel.
+2. Validating that the SYCL kernel object type and its data members meet the
+ SYCL device copyability and kernel parameter requirements noted above.
+3. Copying the SYCL kernel object and any other kernel arguments to device
+ memory including any special handling required for SYCL special types.
+4. Initiating execution of the offload kernel entry point.
+
+The offload kernel entry point for a SYCL kernel performs the following tasks:
+
+1. Calling the `operator()` member function of the SYCL kernel object.
+
+The `sycl_kernel_entry_point` attribute facilitates or automates these tasks
+by providing generation of an offload kernel entry point with a unique symbol
+name, type checking of kernel argument requirements, and initiation of kernel
+execution via synthesized calls to a `sycl_kernel_launch` template.
+
+A function declared with the `sycl_kernel_entry_point` attribute specifies
+the parameters and body of an offload entry point function. Consider the
+following call to the `single_task()` SYCL kernel invocation function assuming
+an implementation similar to the one shown above.
+
+```c++
+struct S { int i; };
+void f(sycl::handler &handler, sycl::stream &sout, S s) {
+ handler.single_task<struct KN>([=] {
+ sout << "The value of s.i is " << s.i << "\n";
+ });
+}
+```
+
+The SYCL kernel object is the result of the lambda expression. The call to
+`kernel_entry_point()` via the call to `single_task()` triggers the
+generation of an offload kernel entry point function that looks approximately
+as follows.
+
+```c++
+void sycl-kernel-caller-for-KN(kernel-type kernelFunc) {
+ kernelFunc();
+}
+```
+
+There are a few items worthy of note:
+
+1. `sycl-kernel-caller-for-KN` is an exposition only name; the actual name
+ generated for an entry point is an implementation detail and subject to
+ change. However, the name will incorporate the SYCL kernel name, `KN`,
+ that was passed as the `KernelName` template parameter to
+ `single_task()` and eventually provided as the argument to the
+ `sycl_kernel_entry_point` attribute in order to ensure that a unique
+ name is generated for each entry point. There is a one-to-one correspondence
+ between SYCL kernel names and offload kernel entry points.
+2. The SYCL kernel is a lambda closure type and therefore has no name;
+ `kernel-type` is substituted above and corresponds to the `KernelType`
+ template parameter deduced in the call to `single_task()`.
+3. The parameter and the call to `kernelFunc()` in the function body
+ correspond to the definition of `kernel_entry_point()` as called by
+ `single_task()`.
+4. The parameter is type checked for conformance with the SYCL device
+ copyability and kernel parameter requirements.
+
+Within `single_task()`, the call to `kernel_entry_point()` is effectively
+replaced with a synthesized call to a `sycl_kernel_launch` template that
+looks approximately as follows.
+
+```c++
+sycl_kernel_launch<KN>("sycl-kernel-caller-for-KN", kernelFunc);
+```
+
+There are a few items worthy of note:
+
+1. Lookup for the `sycl_kernel_launch` template is performed as if from the
+ body of the (possibly instantiated) definition of `kernel_entry_point()`.
+ If name lookup or overload resolution fails, the program is ill-formed.
+ If the selected overload is a non-static member function, then `this` is
+ passed as the implicit object parameter.
+2. Function arguments passed to `sycl_kernel_launch()` are passed
+ as if by `std::move(x)`.
+3. The `sycl_kernel_launch` template is expected to be provided by the SYCL
+ library implementation. It is responsible for copying the kernel arguments
+ to device memory and for scheduling execution of the generated offload
+ kernel entry point identified by the symbol name passed as the first
+ function argument. `sycl-kernel-caller-for-KN` is substituted above for
+ the actual symbol name that would be generated for the offload kernel entry
+ point.
+
+It is not necessary for a function declared with the `sycl_kernel_entry_point`
+attribute to be called for the offload kernel entry point to be emitted. For
+inline functions and function templates, any ODR-use will suffice. For other
+functions, an ODR-use is not required; the offload kernel entry point will be
+emitted if the function is defined. In any case, a call to the function is
+required for the synthesized call to `sycl_kernel_launch()` to occur.
+
+A function declared with the `sycl_kernel_entry_point` attribute may include
+an exception specification. If a non-throwing exception specification is
+present, an exception propagating from the implicit call to the
+`sycl_kernel_launch` template will result in a call to `std::terminate()`.
+Otherwise, such an exception will propagate normally.
+
+Functions declared with the `sycl_kernel_entry_point` attribute are not
+limited to the simple example shown above. They may have additional template
+parameters, declare additional function parameters, and have complex control
+flow in the function body. The function must abide by the language feature
+restrictions described in section 5.4, "Language restrictions for device
+functions" in the SYCL 2020 specification. If the function is a non-static
+member function, `this` shall not be used in a potentially evaluated
+expression.
+
+
+### target
+
+{clang-attr-syntaxes}`TargetDocs`
+
+Clang supports the GNU style `__attribute__((target("OPTIONS")))` attribute.
+This attribute may be attached to a function definition and instructs
+the backend to use different code generation options than were passed on the
+command line.
+
+The current set of options correspond to the existing "subtarget features" for
+the target with or without a "-mno-" in front corresponding to the absence
+of the feature, as well as `arch="CPU"` which will change the default "CPU"
+for the function.
+
+For X86, the attribute also allows `tune="CPU"` to optimize the generated
+code for the given CPU without changing the available instructions.
+
+For AArch64, `arch="Arch"` will set the architecture, similar to the -march
+command line options. `cpu="CPU"` can be used to select a specific cpu,
+as per the `-mcpu` option, similarly for `tune=`. The attribute also allows the
+`branch-protection=<args>` option, where the permissible arguments and their
+effect on code generation are the same as for the command-line option
+`-mbranch-protection`.
+
+Example "subtarget features" from the x86 backend include: "mmx", "sse", "sse4.2",
+"avx", "xop" and largely correspond to the machine specific options handled by
+the front end.
+
+Note that this attribute does not apply transitively to nested functions such
+as blocks or C++ lambdas.
+
+Additionally, this attribute supports function multiversioning for ELF based
+x86/x86-64 targets, which can be used to create multiple implementations of the
+same function that will be resolved at runtime based on the priority of their
+`target` attribute strings. A function is considered a multiversioned function
+if either two declarations of the function have different `target` attribute
+strings, or if it has a `target` attribute string of `default`. For
+example:
+
+```c++
+__attribute__((target("arch=atom")))
+void foo() {} // will be called on 'atom' processors.
+__attribute__((target("default")))
+void foo() {} // will be called on any other processors.
+```
+
+All multiversioned functions must contain a `default` (fallback)
+implementation, otherwise usages of the function are considered invalid.
+Additionally, a function may not become multiversioned after its first use.
+
+
+### target_clones
+
+{clang-attr-syntaxes}`TargetClonesDocs`
+
+Clang supports the `target_clones("OPTIONS")` attribute. This attribute may be
+attached to a function declaration and causes function multiversioning, where
+multiple versions of the function will be emitted with different code
+generation options. Additionally, these versions will be resolved at runtime
+based on the priority of their attribute options. All `target_clone` functions
+are considered multiversioned functions.
+
+For AArch64 target:
+The attribute contains comma-separated strings of target features joined by "+"
+sign. For example:
+
+```c++
+__attribute__((target_clones("sha2+memtag", "fcma+sve2-pmull128")))
+void foo() {}
+```
+
+For every multiversioned function a `default` (fallback) implementation
+always generated if not specified directly.
+
+For x86/x86-64 targets:
+All multiversioned functions must contain a `default` (fallback)
+implementation, otherwise usages of the function are considered invalid.
+Additionally, a function may not become multiversioned after its first use.
+
+The options to `target_clones` can either be a target-specific architecture
+(specified as `arch=CPU`), or one of a list of subtarget features.
+
+Example "subtarget features" from the x86 backend include: "mmx", "sse", "sse4.2",
+"avx", "xop" and largely correspond to the machine specific options handled by
+the front end.
+
+The versions can either be listed as a comma-separated sequence of string
+literals or as a single string literal containing a comma-separated list of
+versions. For compatibility with GCC, the two formats can be mixed. For
+example, the following will emit 4 versions of the function:
+
+```c++
+__attribute__((target_clones("arch=atom,avx2","arch=ivybridge","default")))
+void foo() {}
+```
+
+For targets that support the GNU indirect function (IFUNC) feature, dispatch
+is performed by emitting an indirect function that is resolved to the appropriate
+target clone at load time. The indirect function is given the name the
+multiversioned function would have if it had been declared without the attribute.
+For backward compatibility with earlier Clang releases, a function alias with an
+`.ifunc` suffix is also emitted. The `.ifunc` suffixed symbol is a deprecated
+feature and support for it may be removed in the future.
+
+For PowerPC targets, `target_clones` is supported on AIX only. The attribute
+contains comma-separated strings of one of:
+(a) `default`, (b) `cpu=CPU`, (c) `FEATURE` or `no-FEATURE`.
+The minimum CPU supported is `pwr7` (long spelling such as `power7` is accepted).
+The list of target features is a subset of what's allowed on `target`, limited
+to what is detectable at runtime using `__builtin_cpu_supports`. IFUNC is supported
+on AIX in Clang, so dispatch is implemented similar to other targets using IFUNC.
+An FMV function that is only declared in a translation unit is treated as a
+non-FMV. The resolver and the function clones are given internal linkage.
+
+
+### target_version
+
+{clang-attr-syntaxes}`TargetVersionDocs`
+
+For AArch64 target clang supports function multiversioning by
+`__attribute__((target_version("OPTIONS")))` attribute. When applied to a
+function it instructs compiler to emit multiple function versions based on
+`target_version` attribute strings, which resolved at runtime depend on their
+priority and target features availability. One of the versions is always
+(implicitly or explicitly) the `default` (fallback). Attribute strings can
+contain dependent features names joined by the "+" sign.
+
+For targets that support the GNU indirect function (IFUNC) feature, dispatch
+is performed by emitting an indirect function that is resolved to the appropriate
+target clone at load time. The indirect function is given the name the
+multiversioned function would have if it had been declared without the attribute.
+For backward compatibility with earlier Clang releases, a function alias with an
+`.ifunc` suffix is also emitted. The `.ifunc` suffixed symbol is a deprecated
+feature and support for it may be removed in the future.
+
+
+### try_acquire_capability, try_acquire_shared_capability
+
+{clang-attr-syntaxes}`TryAcquireCapabilityDocs`
+
+Marks a function that attempts to acquire a capability. This function may fail to
+actually acquire the capability; they accept a Boolean value determining
+whether acquiring the capability means success (true), or failing to acquire
+the capability means success (false).
+
+
+### unsafe_buffer_usage
+
+{clang-attr-syntaxes}`UnsafeBufferUsageDocs`
+
+The attribute `[[clang::unsafe_buffer_usage]]` should be placed on functions
+that need to be avoided as they are prone to buffer overflows or unsafe buffer
+struct fields. It is designed to work together with the off-by-default compiler
+warning `-Wunsafe-buffer-usage` to help codebases transition away from raw pointer
+based buffer management, in favor of safer abstractions such as C++20 `std::span`.
+The attribute causes `-Wunsafe-buffer-usage` to warn on every use of the function or
+the field it is attached to, and it may also lead to emission of automatic fix-it
+hints which would help the user replace the use of unsafe functions(/fields) with safe
+alternatives, though the attribute can be used even when the fix can't be automated.
+
+- Attribute attached to functions: The attribute suppresses all
+ `-Wunsafe-buffer-usage` warnings within the function it is attached to, as the
+ function is now classified as unsafe. The attribute should be used carefully, as it
+ will silence all unsafe operation warnings inside the function; including any new
+ unsafe operations introduced in the future.
+
+ The attribute is warranted even if the only way a function can overflow
+ the buffer is by violating the function's preconditions. For example, it
+ would make sense to put the attribute on function `foo()` below because
+ passing an incorrect size parameter would cause a buffer overflow:
+
+ ```c++
+ [[clang::unsafe_buffer_usage]]
+ void foo(int *buf, size_t size) {
+ for (size_t i = 0; i < size; ++i) {
+ buf[i] = i;
+ }
+ }
+ ```
+
+ The attribute is NOT warranted when the function uses safe abstractions,
+ assuming that these abstractions weren't misused outside the function.
+ For example, function `bar()` below doesn't need the attribute,
+ because assuming that the container `buf` is well-formed (has size that
+ fits the original buffer it refers to), overflow cannot occur:
+
+ ```c++
+ void bar(std::span<int> buf) {
+ for (size_t i = 0; i < buf.size(); ++i) {
+ buf[i] = i;
+ }
+ }
+ ```
+
+ In this case function `bar()` enables the user to keep the buffer
+ "containerized" in a span for as long as possible. On the other hand,
+ Function `foo()` in the previous example may have internal
+ consistency, but by accepting a raw buffer it requires the user to unwrap
+ their span, which is undesirable according to the programming model
+ behind `-Wunsafe-buffer-usage`.
+
+ The attribute is warranted when a function accepts a raw buffer only to
+ immediately put it into a span:
+
+ ```c++
+ [[clang::unsafe_buffer_usage]]
+ void baz(int *buf, size_t size) {
+ std::span<int> sp{ buf, size };
+ for (size_t i = 0; i < sp.size(); ++i) {
+ sp[i] = i;
+ }
+ }
+ ```
+
+ In this case `baz()` does not contain any unsafe operations, but the awkward
+ parameter type causes the caller to unwrap the span unnecessarily.
+ Note that regardless of the attribute, code inside `baz()` isn't flagged
+ by `-Wunsafe-buffer-usage` as unsafe. It is definitely undesirable,
+ but if `baz()` is on an API surface, there is no way to improve it
+ to make it as safe as `bar()` without breaking the source and binary
+ compatibility with existing users of the function. In such cases
+ the proper solution would be to create a different function (possibly
+ an overload of `baz()`) that accepts a safe container like `bar()`,
+ and then use the attribute on the original `baz()` to help the users
+ update their code to use the new function.
+
+- Attribute attached to fields: The attribute should only be attached to
+ struct fields, if the fields can not be updated to a safe type with bounds
+ check, such as `std::span`. In other words, the buffers prone to unsafe accesses
+ should always be updated to use safe containers/views and attaching the attribute
+ must be last resort when such an update is infeasible.
+
+ The attribute can be placed on individual fields or a set of them as shown below.
+
+ ```c++
+ struct A {
+ [[clang::unsafe_buffer_usage]]
+ int *ptr1;
+
+ [[clang::unsafe_buffer_usage]]
+ int *ptr2, buf[10];
+
+ [[clang::unsafe_buffer_usage]]
+ size_t sz;
+ };
+ ```
+
+ Here, every read/write to the fields `ptr1`, `ptr2`, `buf` and `sz` will trigger a warning
+ that the field has been explicitly marked as unsafe due to unsafe-buffer operations.
+
+- Attribute attached to container constructors and factory functions: The
+ spellings `[[clang::unsafe_buffer_usage_in_container]]` and
+ `[[clang::unsafe_buffer_usage("container")]]` are equivalent and can be
+ placed on two-parameter constructors and factory functions of container or
+ view types (such as custom span types taking a `(pointer, size)` or
+ `(begin, end)` pair) to opt them in to `-Wunsafe-buffer-usage-in-container`.
+
+ Unlike the general `[[clang::unsafe_buffer_usage]]` attribute, which warns on
+ every call, this form suppresses the warning when the argument pair is
+ provably safe -- for example, when constructing from `c.data(), c.size()` or
+ `c.begin(), c.end()` on the same container object `c`, a constant-sized array
+ with a matching bound, `&var, 1`, or a `0` size:
+
+ ```c++
+ template <typename T>
+ class CustomSpan {
+ public:
+ [[clang::unsafe_buffer_usage_in_container]]
+ CustomSpan(T *ptr, size_t size);
+
+ template <typename It>
+ [[clang::unsafe_buffer_usage("container")]]
+ CustomSpan(It first, It last);
+ };
+
+ template <typename T>
+ [[clang::unsafe_buffer_usage("container")]]
+ CustomSpan<T> MakeCustomSpan(T *ptr, size_t size);
+
+ void example(int *p, size_t n, MyVector<int> &v) {
+ CustomSpan<int> s1(p, n); // warning: decoupled pointer and size
+ auto s2 = MakeCustomSpan(p, n); // warning: decoupled pointer and size
+ CustomSpan<int> s3(v.data(), v.size()); // no warning
+ CustomSpan<int> s4(v.begin(), v.end()); // no warning
+ auto s5 = MakeCustomSpan(v.data(), v.size()); // no warning
+ }
+ ```
+
+
+### used
+
+{clang-attr-syntaxes}`UsedDocs`
+
+This attribute, when attached to a function or variable definition, indicates
+that there may be references to the entity which are not apparent in the source
+code. For example, it may be referenced from inline `asm`, or it may be
+found through a dynamic symbol or section lookup.
+
+The compiler must emit the definition even if it appears to be unused, and it
+must not apply optimizations which depend on fully understanding how the entity
+is used.
+
+Whether this attribute has any effect on the linker depends on the target and
+the linker. Most linkers support the feature of section garbage collection
+(`--gc-sections`), also known as "dead stripping" (`ld64 -dead_strip`) or
+discarding unreferenced sections (`link.exe /OPT:REF`). On COFF and Mach-O
+targets (Windows and Apple platforms), the `used` attribute prevents symbols
+from being removed by linker section GC. On ELF targets, it has no effect on its
+own, and the linker may remove the definition if it is not otherwise referenced.
+This linker GC can be avoided by also adding the `retain` attribute. Note
+that `retain` requires special support from the linker; see that attribute's
+documentation for further information.
+
+
+### xray_always_instrument, xray_never_instrument, xray_log_args
+
+{clang-attr-syntaxes}`XRayDocs`
+
+`__attribute__((xray_always_instrument))` or
+`[[clang::xray_always_instrument]]` is used to mark member functions (in C++),
+methods (in Objective C), and free functions (in C, C++, and Objective C) to be
+instrumented with XRay. This will cause the function to always have space at
+the beginning and exit points to allow for runtime patching.
+
+Conversely, `__attribute__((xray_never_instrument))` or
+`[[clang::xray_never_instrument]]` will inhibit the insertion of these
+instrumentation points.
+
+If a function has neither of these attributes, they become subject to the XRay
+heuristics used to determine whether a function should be instrumented or
+otherwise.
+
+`__attribute__((xray_log_args(N)))` or `[[clang::xray_log_args(N)]]` is
+used to preserve N function arguments for the logging function. Currently,
+only N==1 is supported.
+
+
+### zero_call_used_regs
+
+{clang-attr-syntaxes}`ZeroCallUsedRegsDocs`
+
+This attribute, when attached to a function, causes the compiler to zero a
+subset of all call-used registers before the function returns. It's used to
+increase program security by either mitigating [Return-Oriented Programming][return-oriented programming]
+(ROP) attacks or preventing information leakage through registers.
+
+The term "call-used" means registers which are not guaranteed to be preserved
+unchanged for the caller by the current calling convention. This could also be
+described as "caller-saved" or "not callee-saved".
+
+The `choice` parameters gives the programmer flexibility to choose the subset
+of the call-used registers to be zeroed:
+
+- `skip` doesn't zero any call-used registers. This choice overrides any
+ command-line arguments.
+- `used` only zeros call-used registers used in the function. By `used`, we
+ mean a register whose contents have been set or referenced in the function.
+- `used-gpr` only zeros call-used GPR registers used in the function.
+- `used-arg` only zeros call-used registers used to pass arguments to the
+ function.
+- `used-gpr-arg` only zeros call-used GPR registers used to pass arguments to
+ the function.
+- `all` zeros all call-used registers.
+- `all-gpr` zeros all call-used GPR registers.
+- `all-arg` zeros all call-used registers used to pass arguments to the
+ function.
+- `all-gpr-arg` zeros all call-used GPR registers used to pass arguments to
+ the function.
+
+The default for the attribute is controlled by the `-fzero-call-used-regs`
+flag.
+
+[return-oriented programming]: https://en.wikipedia.org/wiki/Return-oriented_programming
+
+
diff --git a/clang/docs/AttributeReference/HandleAttributes.md b/clang/docs/AttributeReference/HandleAttributes.md
new file mode 100644
index 0000000000000..4c9467c3d8a2c
--- /dev/null
+++ b/clang/docs/AttributeReference/HandleAttributes.md
@@ -0,0 +1,63 @@
+## Handle Attributes
+
+Handles are a way to identify resources like files, sockets, and processes.
+They are more opaque than pointers and widely used in system programming. They
+have similar risks such as never releasing a resource associated with a handle,
+attempting to use a handle that was already released, or trying to release a
+handle twice. Using the annotations below it is possible to make the ownership
+of the handles clear: whose responsibility is to release them. They can also
+aid static analysis tools to find bugs.
+
+### acquire_handle
+
+{clang-attr-syntaxes}`AcquireHandleDocs`
+
+If this annotation is on a function or a function type it is assumed to return
+a new handle. In case this annotation is on an output parameter,
+the function is assumed to fill the corresponding argument with a new
+handle. The attribute requires a string literal argument which used to
+identify the handle with later uses of `use_handle` or
+`release_handle`.
+
+```c++
+// Output arguments from Zircon.
+zx_status_t zx_socket_create(uint32_t options,
+ zx_handle_t __attribute__((acquire_handle("zircon"))) * out0,
+ zx_handle_t* out1 [[clang::acquire_handle("zircon")]]);
+
+
+// Returned handle.
+[[clang::acquire_handle("tag")]] int open(const char *path, int oflag, ... );
+int open(const char *path, int oflag, ... ) __attribute__((acquire_handle("tag")));
+```
+
+
+### release_handle
+
+{clang-attr-syntaxes}`ReleaseHandleDocs`
+
+If a function parameter is annotated with `release_handle(tag)` it is assumed to
+close the handle. It is also assumed to require an open handle to work with. The
+attribute requires a string literal argument to identify the handle being released.
+
+```c++
+zx_status_t zx_handle_close(zx_handle_t handle [[clang::release_handle("tag")]]);
+```
+
+
+### use_handle
+
+{clang-attr-syntaxes}`UseHandleDocs`
+
+A function taking a handle by value might close the handle. If a function
+parameter is annotated with `use_handle(tag)` it is assumed to not to change
+the state of the handle. It is also assumed to require an open handle to work with.
+The attribute requires a string literal argument to identify the handle being used.
+
+```c++
+zx_status_t zx_port_wait(zx_handle_t handle [[clang::use_handle("zircon")]],
+ zx_time_t deadline,
+ zx_port_packet_t* packet);
+```
+
+
diff --git a/clang/docs/AttributeReference/NullabilityAttributes.md b/clang/docs/AttributeReference/NullabilityAttributes.md
new file mode 100644
index 0000000000000..3dc2e1290bb03
--- /dev/null
+++ b/clang/docs/AttributeReference/NullabilityAttributes.md
@@ -0,0 +1,200 @@
+## Nullability Attributes
+
+Whether a particular pointer may be "null" is an important concern when working
+with pointers in the C family of languages. The various nullability attributes
+indicate whether a particular pointer can be null or not, which makes APIs more
+expressive and can help static analysis tools identify bugs involving null
+pointers. Clang supports several kinds of nullability attributes: the
+`nonnull` and `returns_nonnull` attributes indicate which function or
+method parameters and result types can never be null, while nullability type
+qualifiers indicate which pointer types can be null (`_Nullable`) or cannot
+be null (`_Nonnull`).
+
+The nullability (type) qualifiers express whether a value of a given pointer
+type can be null (the `_Nullable` qualifier), doesn't have a defined meaning
+for null (the `_Nonnull` qualifier), or for which the purpose of null is
+unclear (the `_Null_unspecified` qualifier). Because nullability qualifiers
+are expressed within the type system, they are more general than the
+`nonnull` and `returns_nonnull` attributes, allowing one to express (for
+example) a nullable pointer to an array of nonnull pointers. Nullability
+qualifiers are written to the right of the pointer to which they apply. For
+example:
+
+```c
+// No meaningful result when 'ptr' is null (here, it happens to be undefined behavior).
+int fetch(int * _Nonnull ptr) { return *ptr; }
+
+// 'ptr' may be null.
+int fetch_or_zero(int * _Nullable ptr) {
+ return ptr ? *ptr : 0;
+}
+
+// A nullable pointer to non-null pointers to const characters.
+const char *join_strings(const char * _Nonnull * _Nullable strings, unsigned n);
+```
+
+In Objective-C, there is an alternate spelling for the nullability qualifiers
+that can be used in Objective-C methods and properties using context-sensitive,
+non-underscored keywords. For example:
+
+```objective-c
+ at interface NSView : NSResponder
+ - (nullable NSView *)ancestorSharedWithView:(nonnull NSView *)aView;
+ @property (assign, nullable) NSView *superview;
+ @property (readonly, nonnull) NSArray *subviews;
+ at end
+```
+
+As well as built-in pointer types, the nullability attributes can be attached
+to C++ classes marked with the `_Nullable` attribute.
+
+The following C++ standard library types are considered nullable:
+`unique_ptr`, `shared_ptr`, `auto_ptr`, `exception_ptr`, `function`,
+`move_only_function` and `coroutine_handle`.
+
+Types should be marked nullable only where the type itself leaves nullability
+ambiguous. For example, `std::optional` is not marked `_Nullable`, because
+`optional<int> _Nullable` is redundant and `optional<int> _Nonnull` is
+not a useful type. `std::weak_ptr` is not nullable, because its nullability
+can change with no visible modification, so static annotation is unlikely to be
+unhelpful.
+
+### _Nonnull
+
+{clang-attr-syntaxes}`TypeNonNullDocs`
+
+The `_Nonnull` nullability qualifier indicates that null is not a meaningful
+value for a value of the `_Nonnull` pointer type. For example, given a
+declaration such as:
+
+```c
+int fetch(int * _Nonnull ptr);
+```
+
+a caller of `fetch` should not provide a null value, and the compiler will
+produce a warning if it sees a literal null value passed to `fetch`. Note
+that, unlike the declaration attribute `nonnull`, the presence of
+`_Nonnull` does not imply that passing null is undefined behavior: `fetch`
+is free to consider null undefined behavior or (perhaps for
+backward-compatibility reasons) defensively handle null.
+
+
+### _Null_unspecified
+
+{clang-attr-syntaxes}`TypeNullUnspecifiedDocs`
+
+The `_Null_unspecified` nullability qualifier indicates that neither the
+`_Nonnull` nor `_Nullable` qualifiers make sense for a particular pointer
+type. It is used primarily to indicate that the role of null with specific
+pointers in a nullability-annotated header is unclear, e.g., due to
+overly-complex implementations or historical factors with a long-lived API.
+
+
+### _Nullable
+
+{clang-attr-syntaxes}`TypeNullableDocs`
+
+The `_Nullable` nullability qualifier indicates that a value of the
+`_Nullable` pointer type can be null. For example, given:
+
+```c
+int fetch_or_zero(int * _Nullable ptr);
+```
+
+a caller of `fetch_or_zero` can provide null.
+
+The `_Nullable` attribute on classes indicates that the given class can
+represent null values, and so the `_Nullable`, `_Nonnull` etc qualifiers
+make sense for this type. For example:
+
+```c
+class _Nullable ArenaPointer { ... };
+
+ArenaPointer _Nonnull x = ...;
+ArenaPointer _Nullable y = nullptr;
+```
+
+
+### _Nullable_result
+
+{clang-attr-syntaxes}`TypeNullableResultDocs`
+
+The `_Nullable_result` nullability qualifier means that a value of the
+`_Nullable_result` pointer can be `nil`, just like `_Nullable`. Where this
+attribute differs from `_Nullable` is when it's used on a parameter to a
+completion handler in a Swift async method. For instance, here:
+
+```objc
+-(void)fetchSomeDataWithID:(int)identifier
+ completionHandler:(void (^)(Data *_Nullable_result result, NSError *error))completionHandler;
+```
+
+This method asynchronously calls `completionHandler` when the data is
+available, or calls it with an error. `_Nullable_result` indicates to the
+Swift importer that this is the uncommon case where `result` can get `nil`
+even if no error has occurred, and will therefore import it as a Swift optional
+type. Otherwise, if `result` was annotated with `_Nullable`, the Swift
+importer will assume that `result` will always be non-nil unless an error
+occurred.
+
+
+### nonnull
+
+{clang-attr-syntaxes}`NonNullDocs`
+
+The `nonnull` attribute indicates that some function parameters must not be
+null, and can be used in several different ways. It's original usage
+([from GCC](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#Common-Function-Attributes))
+is as a function (or Objective-C method) attribute that specifies which
+parameters of the function are nonnull in a comma-separated list. For example:
+
+```c
+extern void * my_memcpy (void *dest, const void *src, size_t len)
+ __attribute__((nonnull (1, 2)));
+```
+
+Here, the `nonnull` attribute indicates that parameters 1 and 2
+cannot have a null value. Omitting the parenthesized list of parameter indices
+means that all parameters of pointer type cannot be null:
+
+```c
+extern void * my_memcpy (void *dest, const void *src, size_t len)
+ __attribute__((nonnull));
+```
+
+Clang also allows the `nonnull` attribute to be placed directly on a function
+(or Objective-C method) parameter, eliminating the need to specify the
+parameter index ahead of type. For example:
+
+```c
+extern void * my_memcpy (void *dest __attribute__((nonnull)),
+ const void *src __attribute__((nonnull)), size_t len);
+```
+
+Note that the `nonnull` attribute indicates that passing null to a non-null
+parameter is undefined behavior, which the optimizer may take advantage of to,
+e.g., remove null checks. The `_Nonnull` type qualifier indicates that a
+pointer cannot be null in a more general manner (because it is part of the type
+system) and does not imply undefined behavior, making it more widely applicable.
+
+
+### returns_nonnull
+
+{clang-attr-syntaxes}`ReturnsNonNullDocs`
+
+The `returns_nonnull` attribute indicates that a particular function (or
+Objective-C method) always returns a non-null pointer. For example, a
+particular system `malloc` might be defined to terminate a process when
+memory is not available rather than returning a null pointer:
+
+```c
+extern void * malloc (size_t size) __attribute__((returns_nonnull));
+```
+
+The `returns_nonnull` attribute implies that returning a null pointer is
+undefined behavior, which the optimizer may take advantage of. The `_Nonnull`
+type qualifier indicates that a pointer cannot be null in a more general manner
+(because it is part of the type system) and does not imply undefined behavior,
+making it more widely applicable
+
+
diff --git a/clang/docs/AttributeReference/OpenCLAddressSpaces.md b/clang/docs/AttributeReference/OpenCLAddressSpaces.md
new file mode 100644
index 0000000000000..ba8c5b4ee7831
--- /dev/null
+++ b/clang/docs/AttributeReference/OpenCLAddressSpaces.md
@@ -0,0 +1,108 @@
+## OpenCL Address Spaces
+
+The address space qualifier may be used to specify the region of memory that is
+used to allocate the object. OpenCL supports the following address spaces:
+`__generic` (or `generic`), `__global` (or `global`), `__local` (or `local`),
+`__private` (or `private`), and `__constant` (or `constant`).
+
+```c
+__constant int c = ...;
+
+__generic int* foo(global int* g) {
+ __local int* l;
+ private int p;
+ ...
+ return l;
+}
+```
+
+More details can be found in the OpenCL C language Specification version 3,
+Section 6.7, "Address Space Qualifiers".
+
+### [[clang::opencl_global_device]], [[clang::opencl_global_host]]
+
+{clang-attr-syntaxes}`OpenCLAddressSpaceGlobalExtDocs`
+
+The `global_device` and `global_host` address space attributes specify that
+an object is allocated in global memory on the device/host. It helps to
+distinguish USM (Unified Shared Memory) pointers that access global device
+memory from those that access global host memory. These new address spaces are
+a subset of the `__global/opencl_global` address space, the full address space
+set model for OpenCL 2.0 with the extension looks as follows:
+
+```text
+generic->global->host
+ ->device
+ ->private
+ ->local
+constant
+```
+
+As `global_device` and `global_host` are a subset of
+`__global/opencl_global` address spaces it is allowed to convert
+`global_device` and `global_host` address spaces to
+`__global/opencl_global` address spaces (following ISO/IEC TR 18037 5.1.3
+"Address space nesting and rules for pointers").
+
+These attributes are deprecated and may be removed in a future version of Clang.
+
+
+### __constant, constant, [[clang::opencl_constant]]
+
+{clang-attr-syntaxes}`OpenCLAddressSpaceConstantDocs`
+
+The constant address space attribute signals that an object is located in
+a constant (non-modifiable) memory region. It is available to all work items.
+Any type can be annotated with the constant address space attribute. Objects
+with the constant address space qualifier can be declared in any scope and must
+have an initializer.
+
+
+### __generic, generic, [[clang::opencl_generic]]
+
+{clang-attr-syntaxes}`OpenCLAddressSpaceGenericDocs`
+
+The generic address space attribute is only available with OpenCL v2.0 and later.
+It can be used with pointer types. Variables in global and local scope and
+function parameters in non-kernel functions can have the generic address space
+type attribute. It is intended to be a placeholder for any other address space
+except for `__constant` in OpenCL code which can be used with multiple address
+spaces.
+
+
+### __global, global, [[clang::opencl_global]]
+
+{clang-attr-syntaxes}`OpenCLAddressSpaceGlobalDocs`
+
+The global address space attribute specifies that an object is allocated in
+global memory, which is accessible by all work items. The content stored in this
+memory area persists between kernel executions. Pointer types to the global
+address space are allowed as function parameters or local variables. Starting
+with OpenCL v2.0, the global address space can be used with global (program
+scope) variables and static local variable as well.
+
+
+### __local, local, [[clang::opencl_local]]
+
+{clang-attr-syntaxes}`OpenCLAddressSpaceLocalDocs`
+
+The local address space specifies that an object is allocated in the local (work
+group) memory area, which is accessible to all work items in the same work
+group. The content stored in this memory region is not accessible after
+the kernel execution ends. In a kernel function scope, any variable can be in
+the local address space. In other scopes, only pointer types to the local address
+space are allowed. Local address space variables cannot have an initializer.
+
+
+### __private, private, [[clang::opencl_private]]
+
+{clang-attr-syntaxes}`OpenCLAddressSpacePrivateDocs`
+
+The private address space specifies that an object is allocated in the private
+(work item) memory. Other work items cannot access the same memory area and its
+content is destroyed after work item execution ends. Local variables can be
+declared in the private address space. Function arguments are always in the
+private address space. Kernel function arguments of a pointer or an array type
+cannot point to the private address space.
+
+
diff --git a/clang/docs/AttributeReference/PerformanceConstraintAttributes.md b/clang/docs/AttributeReference/PerformanceConstraintAttributes.md
new file mode 100644
index 0000000000000..6065e8b7d53dc
--- /dev/null
+++ b/clang/docs/AttributeReference/PerformanceConstraintAttributes.md
@@ -0,0 +1,60 @@
+## Performance Constraint Attributes
+
+The `nonblocking`, `blocking`, `nonallocating` and `allocating` attributes can be attached
+to function types, including blocks, C++ lambdas, and member functions. The attributes declare
+constraints about a function's behavior pertaining to blocking and heap memory allocation.
+
+There are several rules for function types with these attributes, enforced with
+compiler warnings:
+
+- When assigning or otherwise converting to a function pointer of `nonblocking` or
+ `nonallocating` type, the source must also be a function or function pointer of
+ that type, unless it is a null pointer, i.e. the attributes should not be "spoofed". Conversions
+ that remove the attributes are transparent and valid.
+- An override of a `nonblocking` or `nonallocating` virtual method must also be declared
+ with that same attribute (or a stronger one.) An overriding method may add an attribute.
+- A redeclaration of a `nonblocking` or `nonallocating` function must also be declared with
+ the same attribute (or a stronger one). A redeclaration may add an attribute.
+
+The warnings are controlled by `-Wfunction-effects`, which is disabled by default.
+
+The compiler also diagnoses function calls from `nonblocking` and `nonallocating`
+functions to other functions which lack the appropriate attribute.
+
+### allocating
+
+{clang-attr-syntaxes}`AllocatingDocs`
+
+Declares that a function potentially allocates heap memory, and prevents any potential inference
+of `nonallocating` by the compiler.
+
+
+### blocking
+
+{clang-attr-syntaxes}`BlockingDocs`
+
+Declares that a function potentially blocks, and prevents any potential inference of `nonblocking`
+by the compiler.
+
+
+### nonallocating
+
+{clang-attr-syntaxes}`NonAllocatingDocs`
+
+Declares that a function or function type either does or does not allocate heap memory, according
+to the optional, compile-time constant boolean argument, which defaults to true. When the argument
+is false, the attribute is equivalent to `allocating`.
+
+
+### nonblocking
+
+{clang-attr-syntaxes}`NonBlockingDocs`
+
+Declares that a function or function type either does or does not block in any way, according
+to the optional, compile-time constant boolean argument, which defaults to true. When the argument
+is false, the attribute is equivalent to `blocking`.
+
+For the purposes of diagnostics, `nonblocking` is considered to include the
+`nonallocating` guarantee and is therefore a "stronger" constraint or attribute.
+
+
diff --git a/clang/docs/AttributeReference/StatementAttributes.md b/clang/docs/AttributeReference/StatementAttributes.md
new file mode 100644
index 0000000000000..f46610a65dea9
--- /dev/null
+++ b/clang/docs/AttributeReference/StatementAttributes.md
@@ -0,0 +1,807 @@
+## Statement Attributes
+
+
+
+### #pragma clang loop
+
+{clang-attr-syntaxes}`LoopHintDocs`
+
+The `#pragma clang loop` directive allows loop optimization hints to be
+specified for the subsequent loop. The directive allows pipelining to be
+disabled, or vectorization, vector predication, interleaving, and unrolling to
+be enabled or disabled. Vector width, vector predication, interleave count,
+unrolling count, and the initiation interval for pipelining can be explicitly
+specified. See
+{ref}`loop hint optimizations <langext-loop-hint-optimizations>` for details.
+
+
+### #pragma clang loop pipeline, #pragma clang loop pipeline_initiation_interval
+
+{clang-attr-syntaxes}`PipelineHintDocs`
+
+Software Pipelining optimization is a technique used to optimize loops by
+utilizing instruction-level parallelism. It reorders loop instructions to
+overlap iterations. As a result, the next iteration starts before the previous
+iteration has finished. The module scheduling technique creates a schedule for
+one iteration such that when repeating at regular intervals, no inter-iteration
+dependencies are violated. This constant interval(in cycles) between the start
+of iterations is called the initiation interval. i.e. The initiation interval
+is the number of cycles between two iterations of an unoptimized loop in the
+newly created schedule. A new, optimized loop is created such that a single iteration
+of the loop executes in the same number of cycles as the initiation interval.
+
+For further details see <https://llvm.org/pubs/2005-06-17-LattnerMSThesis-book.pdf>.
+
+`#pragma clang loop pipeline and #pragma loop pipeline_initiation_interval`
+could be used as hints for the software pipelining optimization. The pragma is
+placed immediately before a for, while, do-while, or a C++11 range-based for
+loop.
+
+Using `#pragma clang loop pipeline(disable)` avoids the software pipelining
+optimization. The disable state can only be specified:
+
+```c++
+#pragma clang loop pipeline(disable)
+for (...) {
+ ...
+}
+```
+
+Using `#pragma loop pipeline_initiation_interval` instructs
+the software pipeliner to try the specified initiation interval.
+If a schedule was found then the resulting loop iteration would have
+the specified cycle count. If a schedule was not found then loop
+remains unchanged. The initiation interval must be a positive number
+greater than zero:
+
+```c++
+#pragma loop pipeline_initiation_interval(10)
+for (...) {
+ ...
+}
+```
+
+
+### #pragma unroll, #pragma nounroll
+
+{clang-attr-syntaxes}`UnrollHintDocs`
+
+Loop unrolling optimization hints can be specified with `#pragma unroll` and
+`#pragma nounroll`. The pragma is placed immediately before a for, while,
+do-while, or c++11 range-based for loop. GCC's loop unrolling hints
+`#pragma GCC unroll` and `#pragma GCC nounroll` are also supported and have
+identical semantics to `#pragma unroll` and `#pragma nounroll`.
+
+Specifying `#pragma unroll` without a parameter directs the loop unroller to
+attempt to fully unroll the loop if the trip count is known at compile time and
+attempt to partially unroll the loop if the trip count is not known at compile
+time:
+
+```c++
+#pragma unroll
+for (...) {
+ ...
+}
+```
+
+Specifying the optional parameter, `#pragma unroll _value_`, directs the
+unroller to unroll the loop `_value_` times. The parameter may optionally be
+enclosed in parentheses:
+
+```c++
+#pragma unroll 16
+for (...) {
+ ...
+}
+
+#pragma unroll(16)
+for (...) {
+ ...
+}
+```
+
+Specifying `#pragma nounroll` indicates that the loop should not be unrolled:
+
+```c++
+#pragma nounroll
+for (...) {
+ ...
+}
+```
+
+`#pragma unroll` and `#pragma unroll _value_` have identical semantics to
+`#pragma clang loop unroll(enable)` and
+`#pragma clang loop unroll_count(_value_)` respectively. `#pragma nounroll`
+is equivalent to `#pragma clang loop unroll(disable)`. See
+{ref}`loop hint optimizations <langext-loop-hint-optimizations>` for further
+details including limitations of the unroll hints.
+
+
+### [loop]
+
+{clang-attr-syntaxes}`HLSLLoopHintDocs`
+
+The `[loop]` directive allows loop optimization hints to be
+specified for the subsequent loop. The directive allows unrolling to
+be disabled and is not compatible with `[unroll(x)]`.
+
+Specifying the parameter, `[loop]`, directs the
+unroller to not unroll the loop.
+
+```hlsl
+[loop]
+for (...) {
+ ...
+}
+```
+
+```hlsl
+[loop]
+while (...) {
+ ...
+}
+```
+
+```hlsl
+[loop]
+do {
+ ...
+} while (...)
+```
+
+See [hlsl loop extensions](https://learn.microsoft.com/en-us/windows/win32/direct3dhlsl/dx-graphics-hlsl-for)
+for details.
+
+
+### [unroll(x)], [unroll]
+
+{clang-attr-syntaxes}`HLSLUnrollHintDocs`
+
+Loop unrolling optimization hints can be specified with `[unroll(x)]`
+. The attribute is placed immediately before a for, while,
+or do-while.
+Specifying the parameter, `[unroll(_value_)]`, directs the
+unroller to unroll the loop `_value_` times. Note: `[unroll(x)]` is not compatible with `[loop]`.
+
+```hlsl
+[unroll(4)]
+for (...) {
+ ...
+}
+```
+
+```hlsl
+[unroll]
+for (...) {
+ ...
+}
+```
+
+```hlsl
+[unroll(4)]
+while (...) {
+ ...
+}
+```
+
+```hlsl
+[unroll]
+while (...) {
+ ...
+}
+```
+
+```hlsl
+[unroll(4)]
+do {
+ ...
+} while (...)
+```
+
+```hlsl
+[unroll]
+do {
+ ...
+} while (...)
+```
+
+See [hlsl loop extensions](https://learn.microsoft.com/en-us/windows/win32/direct3dhlsl/dx-graphics-hlsl-for)
+for details.
+
+
+### __read_only, __write_only, __read_write (read_only, write_only, read_write)
+
+{clang-attr-syntaxes}`OpenCLAccessDocs`
+
+The access qualifiers must be used with image object arguments or pipe arguments
+to declare if they are being read or written by a kernel or function.
+
+The `read_only`, `__read_only`, `write_only`, `__write_only`, `read_write`, and `__read_write`
+names are reserved for use as access qualifiers and shall not be used otherwise.
+
+```c
+kernel void
+foo (read_only image2d_t imageA,
+ write_only image2d_t imageB) {
+ ...
+}
+```
+
+In the above example imageA is a read-only 2D image object, and imageB is a
+write-only 2D image object.
+
+The `read_write` (or `__read_write`) qualifier cannot be used with pipe arguments.
+
+More details can be found in the OpenCL C language Spec v2.0, Section 6.6.
+
+
+### assume
+
+{clang-attr-syntaxes}`CXXAssumeDocs`
+
+The `assume` attribute is used to indicate to the optimizer that a
+certain condition is assumed to be true at a certain point in the
+program. If this condition is violated at runtime, the behavior is
+undefined. `assume` can only be applied to a null statement.
+
+Different optimisers are likely to react differently to the presence of
+this attribute; in some cases, adding `assume` may affect performance
+negatively. It should be used with parsimony and care.
+
+Example:
+
+```c++
+int f(int x, int y) {
+ [[assume(x == 27)]];
+ [[assume(x == y)]];
+ return y + 1; // May be optimised to `return 28`.
+}
+```
+
+
+### atomic
+
+{clang-attr-syntaxes}`AtomicDocs`
+
+The `atomic` attribute can be applied to *compound statements* to override or
+further specify the default atomic code-generation behavior, especially on
+targets such as AMDGPU. You can annotate compound statements with options
+to modify how atomic instructions inside that statement are emitted at the IR
+level.
+
+For details, see the documentation for
+{ref}`@atomic <langext-atomic-code-generation>`
+
+
+### branch, flatten
+
+{clang-attr-syntaxes}`HLSLControlFlowHintDocs`
+
+The `branch` and `flatten` attributes can be applied to *if* and *switch*
+statements in the HLSL language mode to provide hints for how the backend
+should execute them.
+
+- `branch` means that control flow is preferred. The condition should be
+ evaluated first and we should only execute the block guarded by it.
+
+- `flatten` means that control flow should be avoided. All blocks should be
+ executed and variables that are modified should be conditionally assigned.
+
+These control flow hints are preserved through the compilation and emitted in a
+backend-specific way.
+
+For details, see the Direct3D documentation for [if Statement][if Statement]
+and [switch Statement][switch Statement].
+
+[if Statement]: https://learn.microsoft.com/en-us/windows/win32/direct3dhlsl/dx-graphics-hlsl-if
+[switch Statement]: https://learn.microsoft.com/en-us/windows/win32/direct3dhlsl/dx-graphics-hlsl-switch
+
+
+### constexpr
+
+{clang-attr-syntaxes}`MSConstexprDocs`
+
+The `[[msvc::constexpr]]` attribute can be applied only to a function
+definition or a `return` statement. It does not impact function declarations.
+A `[[msvc::constexpr]]` function cannot be `constexpr` or `consteval`.
+A `[[msvc::constexpr]]` function is treated as if it were a `constexpr` function
+when it is evaluated in a constant context of `[[msvc::constexpr]] return` statement.
+Otherwise, it is treated as a regular function.
+
+Semantics of this attribute are enabled only under MSVC compatibility
+(`-fms-compatibility-version`) 19.33 and later.
+
+
+### fallthrough
+
+{clang-attr-syntaxes}`FallthroughDocs`
+
+The `fallthrough` (or `clang::fallthrough`) attribute is used
+to annotate intentional fall-through
+between switch labels. It can only be applied to a null statement placed at a
+point of execution between any statement and the next switch label. It is
+common to mark these places with a specific comment, but this attribute is
+meant to replace comments with a more strict annotation, which can be checked
+by the compiler. This attribute doesn't change semantics of the code and can
+be used wherever an intended fall-through occurs. It is designed to mimic
+control-flow statements like `break;`, so it can be placed in most places
+where `break;` can, but only if there are no statements on the execution path
+between it and the next switch label.
+
+By default, Clang does not warn on unannotated fallthrough from one `switch`
+case to another. Diagnostics on fallthrough without a corresponding annotation
+can be enabled with the `-Wimplicit-fallthrough` argument.
+
+Here is an example:
+
+```c++
+// compile with -Wimplicit-fallthrough
+switch (n) {
+case 22:
+case 33: // no warning: no statements between case labels
+ f();
+case 44: // warning: unannotated fall-through
+ g();
+ [[clang::fallthrough]];
+case 55: // no warning
+ if (x) {
+ h();
+ break;
+ }
+ else {
+ i();
+ [[clang::fallthrough]];
+ }
+case 66: // no warning
+ p();
+ [[clang::fallthrough]]; // warning: fallthrough annotation does not
+ // directly precede case label
+ q();
+case 77: // warning: unannotated fall-through
+ r();
+}
+```
+
+
+### intel_reqd_sub_group_size
+
+{clang-attr-syntaxes}`OpenCLIntelReqdSubGroupSizeDocs`
+
+The optional attribute intel_reqd_sub_group_size can be used to indicate that
+the kernel must be compiled and executed with the specified subgroup size. When
+this attribute is present, get_max_sub_group_size() is guaranteed to return the
+specified integer value. This is important for the correctness of many subgroup
+algorithms, and in some cases may be used by the compiler to generate more optimal
+code. See
+[`cl_intel_required_subgroup_size`](https://www.khronos.org/registry/OpenCL/extensions/intel/cl_intel_required_subgroup_size.html)
+for details.
+
+
+### likely and unlikely
+
+{clang-attr-syntaxes}`LikelihoodDocs`
+
+The `likely` and `unlikely` attributes are used as compiler hints.
+The attributes are used to aid the compiler to determine which branch is
+likely or unlikely to be taken. This is done by marking the branch substatement
+with one of the two attributes.
+
+It isn't allowed to annotate a single statement with both `likely` and
+`unlikely`. Annotating the `true` and `false` branch of an `if`
+statement with the same likelihood attribute will result in a diagnostic and
+the attributes are ignored on both branches.
+
+In a `switch` statement it's allowed to annotate multiple `case` labels
+or the `default` label with the same likelihood attribute. This makes
+\* all labels without an attribute have a neutral likelihood,
+\* all labels marked `[[likely]]` have an equally positive likelihood, and
+\* all labels marked `[[unlikely]]` have an equally negative likelihood.
+The neutral likelihood is the more likely of path execution than the negative
+likelihood. The positive likelihood is the more likely of path of execution
+than the neutral likelihood.
+
+These attributes have no effect on the generated code when using
+PGO (Profile-Guided Optimization) or at optimization level 0.
+
+In Clang, the attributes will be ignored if they're not placed on
+\* the `case` or `default` label of a `switch` statement,
+\* or on the substatement of an `if` or `else` statement,
+\* or on the substatement of an `for` or `while` statement.
+The C++ Standard recommends to honor them on every statement in the
+path of execution, but that can be confusing:
+
+```c++
+if (b) {
+ [[unlikely]] --b; // Per the standard this is in the path of
+ // execution, so this branch should be considered
+ // unlikely. However, Clang ignores the attribute
+ // here since it is not on the substatement.
+}
+
+if (b) {
+ --b;
+ if(b)
+ return;
+ [[unlikely]] --b; // Not in the path of execution,
+} // the branch has no likelihood information.
+
+if (b) {
+ --b;
+ foo(b);
+ // Whether or not the next statement is in the path of execution depends
+ // on the declaration of foo():
+ // In the path of execution: void foo(int);
+ // Not in the path of execution: [[noreturn]] void foo(int);
+ // This means the likelihood of the branch depends on the declaration
+ // of foo().
+ [[unlikely]] --b;
+}
+```
+
+Below are some example usages of the likelihood attributes and their effects:
+
+```c++
+if (b) [[likely]] { // Placement on the first statement in the branch.
+ // The compiler will optimize to execute the code here.
+} else {
+}
+
+if (b)
+ [[unlikely]] b++; // Placement on the first statement in the branch.
+else {
+ // The compiler will optimize to execute the code here.
+}
+
+if (b) {
+ [[unlikely]] b++; // Placement on the second statement in the branch.
+} // The attribute will be ignored.
+
+if (b) [[likely]] {
+ [[unlikely]] b++; // No contradiction since the second attribute
+} // is ignored.
+
+if (b)
+ ;
+else [[likely]] {
+ // The compiler will optimize to execute the code here.
+}
+
+if (b)
+ ;
+else
+ // The compiler will optimize to execute the next statement.
+ [[likely]] b = f();
+
+if (b) [[likely]]; // Both branches are likely. A diagnostic is issued
+else [[likely]]; // and the attributes are ignored.
+
+if (b)
+ [[likely]] int i = 5; // Issues a diagnostic since the attribute
+ // isn't allowed on a declaration.
+
+switch (i) {
+ [[likely]] case 1: // This value is likely
+ ...
+ break;
+
+ [[unlikely]] case 2: // This value is unlikely
+ ...
+ [[fallthrough]];
+
+ case 3: // No likelihood attribute
+ ...
+ [[likely]] break; // No effect
+
+ case 4: [[likely]] { // attribute on substatement has no effect
+ ...
+ break;
+ }
+
+ [[unlikely]] default: // All other values are unlikely
+ ...
+ break;
+}
+
+switch (i) {
+ [[likely]] case 0: // This value and code path is likely
+ ...
+ [[fallthrough]];
+
+ case 1: // No likelihood attribute, code path is neutral
+ break; // falling through has no effect on the likelihood
+
+ case 2: // No likelihood attribute, code path is neutral
+ [[fallthrough]];
+
+ [[unlikely]] default: // This value and code path are both unlikely
+ break;
+}
+
+for(int i = 0; i != size; ++i) [[likely]] {
+ ... // The loop is the likely path of execution
+}
+
+for(const auto &E : Elements) [[likely]] {
+ ... // The loop is the likely path of execution
+}
+
+while(i != size) [[unlikely]] {
+ ... // The loop is the unlikely path of execution
+} // The generated code will optimize to skip the loop body
+
+while(true) [[unlikely]] {
+ ... // The attribute has no effect
+} // Clang elides the comparison and generates an infinite
+ // loop
+```
+
+
+### musttail
+
+{clang-attr-syntaxes}`MustTailDocs`
+
+If a `return` statement is marked `musttail`, this indicates that the
+compiler must generate a tail call for the program to be correct, even when
+optimizations are disabled. This guarantees that the call will not cause
+unbounded stack growth if it is part of a recursive cycle in the call graph.
+
+If the callee is a virtual function that is implemented by a thunk, there is
+no guarantee in general that the thunk tail-calls the implementation of the
+virtual function, so such a call in a recursive cycle can still result in
+unbounded stack growth.
+
+`clang::musttail` can only be applied to a `return` statement whose value
+is the result of a function call (even functions returning void must use
+`return`, although no value is returned). The target function must have the
+same number of arguments as the caller. The types of the return value and all
+arguments must be similar according to C++ rules (differing only in cv
+qualifiers or array size), including the implicit "this" argument, if any.
+Any variables in scope, including all arguments to the function and the
+return value must be trivially destructible. The calling convention of the
+caller and callee must match, and they must not be variadic functions or have
+old style K&R C function declarations.
+
+The lifetimes of all local variables and function parameters end immediately
+before the call to the function. This means that it is undefined behaviour to
+pass a pointer or reference to a local variable to the called function, which
+is not the case without the attribute. Clang will emit a warning in common
+cases where this happens.
+
+`clang::musttail` provides assurances that the tail call can be optimized on
+all targets, not just one.
+
+
+### nomerge
+
+{clang-attr-syntaxes}`NoMergeDocs`
+
+If a statement is marked `nomerge` and contains call expressions, 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.
+
+`nomerge` attribute can also be used as function attribute to prevent all
+calls to the specified function from merging. It has no effect on indirect
+calls to such functions. For example:
+
+```c++
+[[clang::nomerge]] void foo(int) {}
+
+void bar(int x) {
+ auto *ptr = foo;
+ if (x) foo(1); else foo(2); // will not be merged
+ if (x) ptr(1); else ptr(2); // indirect call, can be merged
+}
+```
+
+`nomerge` attribute can also be used for pointers to functions to
+prevent calls through such pointer from merging. In such case the
+effect applies only to a specific function pointer. For example:
+
+```c++
+[[clang::nomerge]] void (*foo)(int);
+
+void bar(int x) {
+ auto *ptr = foo;
+ if (x) foo(1); else foo(2); // will not be merged
+ if (x) ptr(1); else ptr(2); // 'ptr' has no 'nomerge' attribute, can be merged
+}
+```
+
+
+### opencl_unroll_hint
+
+{clang-attr-syntaxes}`OpenCLUnrollHintDocs`
+
+The `opencl_unroll_hint` attribute qualifier can be used to specify that a loop
+(for, while and do loops) can be unrolled. This attribute qualifier can be
+used to specify full unrolling or partial unrolling by a specified amount.
+This is a compiler hint and the compiler may ignore this directive. See
+[OpenCL v2.0](https://www.khronos.org/registry/cl/specs/opencl-2.0.pdf)
+s6.11.5 for details.
+
+
+### suppress
+
+{clang-attr-syntaxes}`SuppressDocs`
+
+The `suppress` attribute suppresses unwanted warnings coming from static
+analysis tools such as the Clang Static Analyzer. The tool will not report
+any issues in source code annotated with the attribute.
+
+The attribute cannot be used to suppress traditional Clang warnings, because
+many such warnings are emitted before the attribute is fully parsed.
+Consider using `#pragma clang diagnostic` to control such diagnostics,
+as described in
+{ref}`Controlling Diagnostics via Pragmas <pragma-gcc-diagnostic>`.
+
+The `suppress` attribute can be placed on an individual statement in order to
+suppress warnings about undesirable behavior occurring at that statement:
+
+```c++
+int foo() {
+ int *x = nullptr;
+ ...
+ [[clang::suppress]]
+ return *x; // null pointer dereference warning suppressed here
+}
+```
+
+Putting the attribute on a compound statement suppresses all warnings in scope:
+
+```c++
+int foo() {
+ [[clang::suppress]] {
+ int *x = nullptr;
+ ...
+ return *x; // warnings suppressed in the entire scope
+ }
+}
+```
+
+The attribute can also be placed on entire declarations of functions, classes,
+variables, member variables, and so on, to suppress warnings related
+to the declarations themselves. When used this way, the attribute additionally
+suppresses all warnings in the lexical scope of the declaration:
+
+```c++
+class [[clang::suppress]] C {
+ int foo() {
+ int *x = nullptr;
+ ...
+ return *x; // warnings suppressed in the entire class scope
+ }
+
+ int bar();
+};
+
+int C::bar() {
+ int *x = nullptr;
+ ...
+ return *x; // warning NOT suppressed! - not lexically nested in 'class C{}'
+}
+```
+
+Some static analysis warnings are accompanied by one or more notes, and the
+line of code against which the warning is emitted isn't necessarily the best
+for suppression purposes. In such cases the tools are allowed to implement
+additional ways to suppress specific warnings based on the attribute attached
+to a note location.
+
+For example, the Clang Static Analyzer suppresses memory leak warnings when
+the suppression attribute is placed at the allocation site (highlited by
+a "note: memory is allocated"), which may be different from the line of code
+at which the program "loses track" of the pointer (where the warning
+is ultimately emitted):
+
+```c
+int bar1(bool coin_flip) {
+ __attribute__((suppress))
+ int *result = (int *)malloc(sizeof(int));
+ if (coin_flip)
+ return 1; // warning about this leak path is suppressed
+
+ return *result; // warning about this leak path is also suppressed
+}
+
+int bar2(bool coin_flip) {
+ int *result = (int *)malloc(sizeof(int));
+ if (coin_flip)
+ return 1; // leak warning on this path NOT suppressed
+
+ __attribute__((suppress))
+ return *result; // leak warning is suppressed only on this path
+}
+```
+
+When written as `[[gsl::suppress]]`, this attribute suppresses specific
+clang-tidy diagnostics for rules of the [C++ Core Guidelines][c++ core guidelines] in a portable
+way. The attribute can be attached to declarations, statements, and at
+namespace scope.
+
+```c++
+[[gsl::suppress("Rh-public")]]
+void f_() {
+ int *p;
+ [[gsl::suppress("type")]] {
+ p = reinterpret_cast<int*>(7);
+ }
+}
+namespace N {
+ [[clang::suppress("type", "bounds")]];
+ ...
+}
+```
+
+[c++ core guidelines]: https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#inforce-enforcement
+
+
+### sycl_special_class
+
+{clang-attr-syntaxes}`SYCLSpecialClassDocs`
+
+SYCL defines some special classes (accessor, sampler, and stream) which require
+specific handling during the generation of the SPIR entry point.
+The `__attribute__((sycl_special_class))` attribute is used in SYCL
+headers to indicate that a class or a struct needs a specific handling when
+it is passed from host to device.
+Special classes will have a mandatory `__init` method and an optional
+`__finalize` method (the `__finalize` method is used only with the
+`stream` type). Kernel parameters types are extract from the `__init` method
+parameters. The kernel function arguments list is derived from the
+arguments of the `__init` method. The arguments of the `__init` method are
+copied into the kernel function argument list and the `__init` and
+`__finalize` methods are called at the beginning and the end of the kernel,
+respectively.
+The `__init` and `__finalize` methods must be defined inside the
+special class.
+Please note that this is an attribute that is used as an internal
+implementation detail and not intended to be used by external users.
+
+The syntax of the attribute is as follows:
+
+```text
+class __attribute__((sycl_special_class)) accessor {};
+class [[clang::sycl_special_class]] accessor {};
+```
+
+This is a code example that illustrates the use of the attribute:
+
+```c++
+class __attribute__((sycl_special_class)) SpecialType {
+ int F1;
+ int F2;
+ void __init(int f1) {
+ F1 = f1;
+ F2 = f1;
+ }
+ void __finalize() {}
+public:
+ SpecialType() = default;
+ int getF2() const { return F2; }
+};
+
+int main () {
+ SpecialType T;
+ cgh.single_task([=] {
+ T.getF2();
+ });
+}
+```
+
+This would trigger the following kernel entry point in the AST:
+
+```c++
+void __sycl_kernel(int f1) {
+ SpecialType T;
+ T.__init(f1);
+ ...
+ T.__finalize()
+}
+```
+
+
diff --git a/clang/docs/AttributeReference/TypeAttributes.md b/clang/docs/AttributeReference/TypeAttributes.md
new file mode 100644
index 0000000000000..2fe4d0866b953
--- /dev/null
+++ b/clang/docs/AttributeReference/TypeAttributes.md
@@ -0,0 +1,801 @@
+## Type Attributes
+
+
+
+### SYCL Address Spaces
+
+{clang-attr-syntaxes}`SYCLAddressSpaceDocs`
+
+:::{Note}
+These attributes are intended for use in the implementation of SYCL run-time
+libraries and should not be used in any other context.
+Programmers writing code intended to conform to the SYCL specification should
+use the address space facilities specified in the following sections of the
+SYCL 2020 specification.
+
+* [4.7.2, "Buffers"][SYCL-2020-4.7.2]
+* [4.7.6, "Accessors"][SYCL-2020-4.7.6]
+* [4.7.7, "Address space classes"][SYCL-2020-4.7.7]
+* [F.7, "sycl_khr_static_addrspace_cast"][SYCL-2020-F.7]
+* [F.8, "sycl_khr_dynamic_addrspace_cast"][SYCL-2020-F.8]
+:::
+
+The SYCL address space attributes listed below correspond to the five address
+spaces described by
+[SYCL 2020 section 3.8.2, "SYCL device memory model"][SYCL-2020-3.8.2] and
+[SYCL 2020 section 4.7.7, "Address space classes"][SYCL-2020-4.7.7].
+
+::: {list-table} SYCL address space attributes
+:header-rows: 1
+
+* - Address space attribute
+ - SYCL address space
+ - Description
+* - `[[clang::sycl_global]]`
+ - global
+ - A memory region accessible by all work-items executing on a device.
+* - `[[clang::sycl_local]]`
+ - local
+ - A memory region accessible by all work-items of a single work-group.
+* - `[[clang::sycl_private]]`
+ - private
+ - A memory region that is private to a single work-item.
+* - `[[clang::sycl_generic]]`
+ - generic
+ - A virtual memory region from which the global, local, and private memory
+ regions may all be accessed.
+* - `[[clang::sycl_constant]]`
+ - constant
+ - (*deprecated*) A memory region that holds constant data for an executing
+ kernel.
+:::
+
+The SYCL address space attributes are type attributes that may be applied to
+non-function non-reference types to specify an address space qualified type.
+
+A type with a SYCL address space qualifier is a distinct type from the
+otherwise unattributed type. For example, `int *` and `int [[clang::sycl_global]]*`
+designate distinct pointer types which participate in overload resolution and
+template specialization.
+
+The top-level type of a variable declaration cannot have a SYCL address space
+qualifier. For example:
+
+```c++
+int [[clang::sycl_global]] gv; // error: the top-level type has an address space qualifier.
+int [[clang::sycl_global]] *pgi; // ok; the address space qualifier is on the pointee type.
+```
+
+Conversions between SYCL address space attributed types are permitted as
+follows.
+
+- Types attributed with the global, local, or private address space attributes
+ are implicitly convertible to matching types with the generic address space
+ attribute.
+
+The mapping of SYCL address spaces to physical address spaces is target
+dependent.
+
+For OpenCL device targets, the SYCL address space attributes are aligned with
+the [OpenCL address space attributes](#opencl-address-spaces) such that, e.g.,
+`int [[clang::sycl_global]]*` and `int [[clang::opencl_global]]*` specify
+distinct types both of which map to the same underlying address space.
+Corresponding SYCL and OpenCL address space attributed types are implicitly
+convertible; other conversions are permitted as described above; e.g.,
+`int [[clang::sycl_global]]*` is implicitly convertible to
+`int [[clang::opencl_generic]]*`.
+
+[SYCL-2020-3.8.2]: https://registry.khronos.org/SYCL/specs/sycl-2020/html/sycl-2020.html#_sycl_device_memory_model
+[SYCL-2020-4.7.2]: https://registry.khronos.org/SYCL/specs/sycl-2020/html/sycl-2020.html#subsec:buffers
+[SYCL-2020-4.7.6]: https://registry.khronos.org/SYCL/specs/sycl-2020/html/sycl-2020.html#subsec:accessors
+[SYCL-2020-4.7.7]: https://registry.khronos.org/SYCL/specs/sycl-2020/html/sycl-2020.html#_address_space_classes
+[SYCL-2020-F.7]: https://registry.khronos.org/SYCL/specs/sycl-2020/html/sycl-2020.html#sec:khr-static-addrspace-cast
+[SYCL-2020-F.8]: https://registry.khronos.org/SYCL/specs/sycl-2020/html/sycl-2020.html#sec:khr-dynamic-addrspace-cast
+
+
+### __ptr32
+
+{clang-attr-syntaxes}`Ptr32Docs`
+
+The `__ptr32` qualifier represents a native pointer on a 32-bit system. On a
+64-bit system, a pointer with `__ptr32` is extended to a 64-bit pointer. The
+`__sptr` and `__uptr` qualifiers can be used to specify whether the pointer
+is sign extended or zero extended. This qualifier is enabled under
+`-fms-extensions`.
+
+
+### __ptr64
+
+{clang-attr-syntaxes}`Ptr64Docs`
+
+The `__ptr64` qualifier represents a native pointer on a 64-bit system. On a
+32-bit system, a `__ptr64` pointer is truncated to a 32-bit pointer. This
+qualifier is enabled under `-fms-extensions`.
+
+
+### __sptr
+
+{clang-attr-syntaxes}`SPtrDocs`
+
+The `__sptr` qualifier specifies that a 32-bit pointer should be sign
+extended when converted to a 64-bit pointer.
+
+
+### __uptr
+
+{clang-attr-syntaxes}`UPtrDocs`
+
+The `__uptr` qualifier specifies that a 32-bit pointer should be zero
+extended when converted to a 64-bit pointer.
+
+
+(langext-address_space_documentation)=
+
+### address_space
+
+{clang-attr-syntaxes}`AddressSpaceDocs`
+
+:::{Note}
+This attribute is mainly intended to be used by target headers
+provided by the toolchain. End users should prefer the documented, named
+address space annotations for their platform, such as the
+[OpenCL address spaces](#opencl-address-spaces), `__global__`, `__local__`,
+or something else.
+:::
+
+The `address_space` attribute functions as a type qualifier that allows the
+programmer to specify the address space for a pointer or reference type.
+Qualified pointer types are considered distinct types for the purposes of
+overload resolution. The attribute takes a single, non-negative integer
+constant expression identifying the address space. For example:
+
+```c
+int * __attribute__((address_space(1))) ptr;
+
+void foo(__attribute__((address_space(2))) float *buf);
+```
+
+Only one address space qualifier may be applied to a given pointer or reference
+type. Where address spaces are allowed (e.g., variables, parameters, return
+types) and what values are valid depends on the target and language mode.
+
+The meaning of each value is defined by the target; multiple address spaces are
+used in environments such as OpenCL, CUDA, HIP, and other GPU programming
+models to distinguish global, local, constant, and private memory. See for
+example the address spaces defined in the [NVPTX User Guide][nvptx user guide] and the
+[AMDGPU User Guide][amdgpu user guide].
+
+Address spaces may partially overlap or be entirely distinct. The compiler may
+reject attempts to convert between distinct, incompatible address spaces.
+Pointer width may vary between different address spaces, so some explicit casts
+may truncate.
+
+For more information, refer to [ISO TR18037][iso tr18037], which covers embedded C language
+extensions. Section 5 covers named address spaces.
+
+[amdgpu user guide]: https://llvm.org/docs/AMDGPUUsage.html#address-spaces
+[iso tr18037]: https://standards.iso.org/ittf/PubliclyAvailableStandards/c051126_ISO_IEC_TR_18037_2008.zip
+[nvptx user guide]: https://llvm.org/docs/NVPTXUsage.html#address-spaces
+
+
+### align_value
+
+{clang-attr-syntaxes}`AlignValueDocs`
+
+The align_value attribute can be added to the typedef of a pointer type or the
+declaration of a variable of pointer or reference type. It specifies that the
+pointer will point to, or the reference will bind to, only objects with at
+least the provided alignment. This alignment value must be some positive power
+of 2.
+
+```c
+typedef double * aligned_double_ptr __attribute__((align_value(64)));
+void foo(double & x __attribute__((align_value(128))),
+ aligned_double_ptr y) { ... }
+```
+
+If the pointer value does not have the specified alignment at runtime, the
+behavior of the program is undefined.
+
+
+### annotate_type
+
+{clang-attr-syntaxes}`AnnotateTypeDocs`
+
+This attribute is used to add annotations to types, typically for use by static
+analysis tools that are not integrated into the core Clang compiler (e.g.,
+Clang-Tidy checks or out-of-tree Clang-based tools). It is a counterpart to the
+`annotate` attribute, which serves the same purpose, but for declarations.
+
+The attribute takes a mandatory string literal argument specifying the
+annotation category and an arbitrary number of optional arguments that provide
+additional information specific to the annotation category. The optional
+arguments must be constant expressions of arbitrary type.
+
+For example:
+
+```c++
+int* [[clang::annotate_type("category1", "foo", 1)]] f(int[[clang::annotate_type("category2")]] *);
+```
+
+The attribute does not have any effect on the semantics of the type system,
+neither type checking rules, nor runtime semantics. In particular:
+
+- `std::is_same<T, T [[clang::annotate_type("foo")]]>` is true for all types
+ `T`.
+- It is not permissible for overloaded functions or template specializations
+ to differ merely by an `annotate_type` attribute.
+- The presence of an `annotate_type` attribute will not affect name
+ mangling.
+
+
+### arm_sve_vector_bits
+
+{clang-attr-syntaxes}`ArmSveVectorBitsDocs`
+
+The `arm_sve_vector_bits(N)` attribute is defined by the Arm C Language
+Extensions (ACLE) for SVE. It is used to define fixed-length (VLST) variants of
+sizeless types (VLAT).
+
+For example:
+
+```c
+#include <arm_sve.h>
+
+#if __ARM_FEATURE_SVE_BITS==512
+typedef svint32_t fixed_svint32_t __attribute__((arm_sve_vector_bits(512)));
+#endif
+```
+
+Creates a type `fixed_svint32_t` that is a fixed-length variant of
+`svint32_t` that contains exactly 512-bits. Unlike `svint32_t`, this type
+can be used in globals, structs, unions, and arrays, all of which are
+unsupported for sizeless types.
+
+The attribute can be attached to a single SVE vector (such as `svint32_t`) or
+to the SVE predicate type `svbool_t`, this excludes tuple types such as
+`svint32x4_t`. The behavior of the attribute is undefined unless
+`N==__ARM_FEATURE_SVE_BITS`, the implementation defined feature macro that is
+enabled under the `-msve-vector-bits` flag.
+
+For more information See [Arm C Language Extensions for SVE](https://developer.arm.com/documentation/100987/latest) for more information.
+
+
+### bpf_fastcall
+
+{clang-attr-syntaxes}`BPFFastCallDocs`
+
+Functions annotated with this attribute are likely to be inlined by BPF JIT.
+It is assumed that inlined implementation uses less caller saved registers,
+than a regular function.
+Specifically, the following registers are likely to be preserved:
+- `R0` if function return value is `void`;
+- `R2-R5` if function takes 1 argument;
+- `R3-R5` if function takes 2 arguments;
+- `R4-R5` if function takes 3 arguments;
+- `R5` if function takes 4 arguments;
+
+For such functions Clang generates code pattern that allows BPF JIT
+to recognize and remove unnecessary spills and fills of the preserved
+registers.
+
+
+### btf_type_tag
+
+{clang-attr-syntaxes}`BTFTypeTagDocs`
+
+Clang supports the `__attribute__((btf_type_tag("ARGUMENT")))` attribute for
+all targets. It only has effect when `-g` is specified on the command line.
+
+The attribute can be applied to a pointer type, in which case the tag is
+associated with the pointee type, e.g.:
+
+```c
+int __attribute__((btf_type_tag("tag"))) *p;
+```
+
+It can also be applied to the underlying type of a typedef, in which case the
+tag follows the typedef down to its base type, e.g.:
+
+```c
+typedef struct foo __attribute__((btf_type_tag("tag"))) foo_t;
+```
+
+The following is the corresponding btf:
+
+```
+...
+[2] TYPE_TAG 'tag' type_id=4
+[3] TYPEDEF 'foo_t' type_id=2
+[4] STRUCT 'foo' size=4 vlen=1
+ 'c' type_id=5 bits_offset=0
+[5] INT 'int' size=4 bits_offset=0 nr_bits=32 encoding=SIGNED
+...
+```
+
+The attribute is currently silently ignored in any other position (note: this
+scenario may be diagnosed in the future).
+
+The `ARGUMENT` string will be preserved in IR and emitted to DWARF for the
+types used in variable declarations, function declarations, or typedef
+declarations.
+
+For BPF targets, the `ARGUMENT` string will also be emitted to .BTF ELF
+section.
+
+
+### cfi_unchecked_callee
+
+{clang-attr-syntaxes}`CFIUncheckedCalleeDocs`
+
+`cfi_unchecked_callee` is a function type attribute which prevents the
+compiler from instrumenting
+{doc}`Control Flow Integrity <ControlFlowIntegrity>` checks on indirect
+function calls. This also includes control flow checks added by
+`-fsanitize=function`; see {ref}`Available checks <ubsan-checks>`.
+Specifically, the attribute has the following semantics:
+
+1. Indirect calls to a function type with this attribute will not be instrumented with CFI. That is,
+ the indirect call will not be checked. Note that this only changes the behavior for indirect calls
+ on pointers to function types having this attribute. It does not prevent all indirect function calls
+ for a given type from being checked.
+2. All direct references to a function whose type has this attribute will always reference the
+ function definition rather than an entry in the CFI jump table.
+3. When a pointer to a function with this attribute is implicitly cast to a pointer to a function
+ without this attribute, the compiler will give a warning saying this attribute is discarded. This
+ warning can be silenced with an explicit cast. Note an explicit cast just disables the warning, so
+ direct references to a function with a `cfi_unchecked_callee` attribute will still reference the
+ function definition rather than the CFI jump table.
+
+```c
+#define CFI_UNCHECKED_CALLEE __attribute__((cfi_unchecked_callee))
+
+void no_cfi() CFI_UNCHECKED_CALLEE {}
+
+void (*with_cfi)() = no_cfi; // warning: implicit conversion discards `cfi_unchecked_callee` attribute.
+ // `with_cfi` also points to the actual definition of `no_cfi` rather than
+ // its jump table entry.
+
+void invoke(void (CFI_UNCHECKED_CALLEE *func)()) {
+ func(); // CFI will not instrument this indirect call.
+
+ void (*func2)() = func; // warning: implicit conversion discards `cfi_unchecked_callee` attribute.
+
+ func2(); // CFI will instrument this indirect call. Users should be careful however because if this
+ // references a function with type `cfi_unchecked_callee`, then the CFI check may incorrectly
+ // fail because the reference will be to the function definition rather than the CFI jump
+ // table entry.
+}
+```
+
+This attribute can only be applied on functions or member functions. This attribute can be a good
+alternative to `no_sanitize("cfi")` if you only want to disable innstrumentation for specific indirect
+calls rather than applying `no_sanitize("cfi")` on the whole function containing indirect call. Note
+that `cfi_unchecked_attribute` is a type attribute doesn't disable CFI instrumentation on a function
+body.
+
+
+### clang_arm_mve_strict_polymorphism
+
+{clang-attr-syntaxes}`ArmMveStrictPolymorphismDocs`
+
+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.
+
+```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.
+
+```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();
+```
+
+
+### cmse_nonsecure_call
+
+{clang-attr-syntaxes}`ArmCmseNSCallDocs`
+
+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.
+
+
+### contained_type
+
+{clang-attr-syntaxes}`HLSLContainedTypeDocs`
+
+The `hlsl::contained_type` attribute specifies the type of the HLSL resource
+represented by a member variable of type `__hlsl_resource_t`.
+
+This attribute is only valid for resource handles, and is an implementation
+detail of clang's HLSL implementation. For more information see
+{doc}`HLSL Resource Types <HLSL/ResourceTypes>`.
+
+
+### device_builtin_surface_type
+
+{clang-attr-syntaxes}`CUDADeviceBuiltinSurfaceTypeDocs`
+
+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.
+
+
+### device_builtin_texture_type
+
+{clang-attr-syntaxes}`CUDADeviceBuiltinTextureTypeDocs`
+
+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.
+
+
+### dimension
+
+{clang-attr-syntaxes}`HLSLResourceDimensionDocs`
+
+The `hlsl::dimension` attribute specifies the dimensions of the HLSL resource
+represented by a member variable of type `__hlsl_resource_t`, declaring the
+resource to have Unknown, 1D, 2D, 3D, or Cube dimension.
+
+This attribute is only valid for resource handles, and is an implementation
+detail of clang's HLSL implementation. For more information see
+{doc}`HLSL Resource Types <HLSL/ResourceTypes>`.
+
+
+### enforce_read_only_placement
+
+{clang-attr-syntaxes}`ReadOnlyPlacementDocs`
+
+This attribute is attached to a structure, class or union declaration.
+
+: When attached to a record declaration/definition, it checks if all instances
+ of this type can be placed in the read-only data segment of the program. If it
+ finds an instance that can not be placed in a read-only segment, the compiler
+ emits a warning at the source location where the type was used.
+
+ Examples:
+ - `struct __attribute__((enforce_read_only_placement)) Foo;`
+ - `struct __attribute__((enforce_read_only_placement)) Bar { ... };`
+
+ Both `Foo` and `Bar` types have the `enforce_read_only_placement` attribute.
+
+ The goal of introducing this attribute is to assist developers with writing secure
+ code. A `const`-qualified global is generally placed in the read-only section
+ of the memory that has additional run time protection from malicious writes. By
+ attaching this attribute to a declaration, the developer can express the intent
+ to place all instances of the annotated type in the read-only program memory.
+
+ Note 1: The attribute doesn't guarantee that the object will be placed in the
+ read-only data segment as it does not instruct the compiler to ensure such
+ a placement. It emits a warning if something in the code can be proven to prevent
+ an instance from being placed in the read-only data segment.
+
+ Note 2: Currently, clang only checks if all global declarations of a given type `T`
+ are `const`-qualified. The following conditions would also prevent the data to be
+ put into read only segment, but the corresponding warnings are not yet implemented.
+
+ 1. An instance of type `T` is allocated on the heap/stack.
+ 2. Type `T` defines/inherits a mutable field.
+ 3. Type `T` defines/inherits non-constexpr constructor(s) for initialization.
+ 4. A field of type `T` is defined by type `Q`, which does not bear the
+ `enforce_read_only_placement` attribute.
+ 5. A type `Q` inherits from type `T` and it does not have the
+ `enforce_read_only_placement` attribute.
+
+
+### is_array
+
+{clang-attr-syntaxes}`HLSLIsArrayDocs`
+
+The `hlsl::is_array` attribute specifies that the HLSL resource represented
+by a member variable of type `__hlsl_resource_t` has array dimensions.
+
+This attribute is only valid for resource handles, and is an implementation
+detail of clang's HLSL implementation. For more information see
+{doc}`HLSL Resource Types <HLSL/ResourceTypes>`.
+
+
+### is_counter
+
+{clang-attr-syntaxes}`HLSLIsCounterDocs`
+
+The `hlsl::is_counter` attribute specifies that the HLSL resource represented
+by a member variable of type `__hlsl_resource_t` is a counter buffer.
+
+This attribute is only valid for resource handles, and is an implementation
+detail of clang's HLSL implementation. For more information see
+{doc}`HLSL Resource Types <HLSL/ResourceTypes>`.
+
+
+### is_ms
+
+{clang-attr-syntaxes}`HLSLIsMultiSampledDocs`
+
+The `hlsl::is_array` attribute specifies that the HLSL resource represented
+by a member variable of type `__hlsl_resource_t` is multisampled.
+
+This attribute is only valid for resource handles, and is an implementation
+detail of clang's HLSL implementation. For more information see
+{doc}`HLSL Resource Types <HLSL/ResourceTypes>`.
+
+
+### is_rov
+
+{clang-attr-syntaxes}`HLSLIsROVDocs`
+
+The `hlsl::is_rov` attribute specifies that the HLSL resource represented by
+a member variable of type `__hlsl_resource_t` is a rasterizer ordered view.
+
+This attribute is only valid for resource handles, and is an implementation
+detail of clang's HLSL implementation. For more information see
+{doc}`HLSL Resource Types <HLSL/ResourceTypes>`.
+
+
+### noderef
+
+{clang-attr-syntaxes}`NoDerefDocs`
+
+The `noderef` attribute causes clang to diagnose dereferences of annotated pointer types.
+This is ideally used with pointers that point to special memory which cannot be read
+from or written to, but allowing for the pointer to be used in pointer arithmetic.
+The following are examples of valid expressions where dereferences are diagnosed:
+
+```c
+int __attribute__((noderef)) *p;
+int x = *p; // warning
+
+int __attribute__((noderef)) **p2;
+x = **p2; // warning
+
+int * __attribute__((noderef)) *p3;
+p = *p3; // warning
+
+struct S {
+ int a;
+};
+struct S __attribute__((noderef)) *s;
+x = s->a; // warning
+x = (*s).a; // warning
+```
+
+Not all dereferences may diagnose a warning if the value directed by the pointer may not be
+accessed. The following are examples of valid expressions where may not be diagnosed:
+
+```c
+int *q;
+int __attribute__((noderef)) *p;
+q = &*p;
+q = *&p;
+
+struct S {
+ int a;
+};
+struct S __attribute__((noderef)) *s;
+p = &s->a;
+p = &(*s).a;
+```
+
+`noderef` is currently only supported for pointers and arrays and not usable
+for references or Objective-C object pointers.
+
+```c++
+int x = 2;
+int __attribute__((noderef)) &y = x; // warning: 'noderef' can only be used on an array or pointer type
+```
+
+```objc
+id __attribute__((noderef)) obj = [NSObject new]; // warning: 'noderef' can only be used on an array or pointer type
+```
+
+
+### objc_class_stub
+
+{clang-attr-syntaxes}`ObjCClassStubDocs`
+
+This attribute specifies that the Objective-C class to which it applies is
+instantiated at runtime.
+
+Unlike `__attribute__((objc_runtime_visible))`, a class having this attribute
+still has a "class stub" that is visible to the linker. This allows categories
+to be defined. Static message sends with the class as a receiver use a special
+access pattern to ensure the class is lazily instantiated from the class stub.
+
+Classes annotated with this attribute cannot be subclassed and cannot have
+implementations defined for them. This attribute is intended for use in
+Swift-generated headers for classes defined in Swift.
+
+Adding or removing this attribute to a class is an ABI-breaking change.
+
+
+### overflow_behavior
+
+{clang-attr-syntaxes}`OverflowBehaviorDocs`
+
+The `overflow_behavior` attribute provides fine-grained, type-level control
+over how arithmetic operations on an integer type behave on overflow. It may be
+applied to a `typedef`, to a variable or data member, or to an integer type
+directly, and accepts one of two behaviors as its argument:
+
+- `wrap`: arithmetic on the attributed type wraps on overflow, using two's
+ complement semantics. This is equivalent to `-fwrapv` but scoped to the
+ attributed type, and works for both signed and unsigned types. UBSan's
+ `signed-integer-overflow`, `unsigned-integer-overflow`,
+ `implicit-signed-integer-truncation`, and
+ `implicit-unsigned-integer-truncation` checks are suppressed for the type.
+- `trap`: arithmetic on the attributed type is checked for overflow, enabling
+ overflow checks for the type even when `-fwrapv` is in effect globally.
+
+```c++
+typedef unsigned int __attribute__((overflow_behavior(trap))) non_wrapping_uint;
+
+non_wrapping_uint add_one(non_wrapping_uint a) {
+ return a + 1; // Overflow is checked for this operation.
+}
+
+int mul_alot(int n) {
+ int __attribute__((overflow_behavior(wrap))) a = n;
+ return a * 1337; // Overflow is not checked and is well-defined.
+}
+```
+
+The keyword spellings `__ob_wrap` and `__ob_trap` are equivalent to
+`overflow_behavior(wrap)` and `overflow_behavior(trap)` respectively.
+
+The attribute wholly overrides global flags (`-ftrapv`, `-fwrapv`,
+sanitizers, and Sanitizer Special Case Lists) for the attributed type. It can
+only be applied to integer types.
+
+This feature is experimental and must be enabled with the `-cc1` option
+`-fexperimental-overflow-behavior-types`. For full details on promotion and
+conversion rules, pointer semantics, diagnostics, and interaction with
+sanitizers, see {doc}`OverflowBehaviorTypes`.
+
+
+### raw_buffer
+
+{clang-attr-syntaxes}`HLSLRawBufferDocs`
+
+The `hlsl::raw_buffer` attribute specifies that the HLSL resource represented
+by a member variable of type `__hlsl_resource_t` has raw buffer semantics.
+
+This attribute is only valid for resource handles, and is an implementation
+detail of clang's HLSL implementation. For more information see
+{doc}`HLSL Resource Types <HLSL/ResourceTypes>`.
+
+
+### resource_class
+
+{clang-attr-syntaxes}`HLSLResourceClassDocs`
+
+The `hlsl::resource_class` attribute specifies the resource class of the HLSL
+resource represented by a member variable of type `__hlsl_resource_t`,
+declaring it to be an SRV, UAV, CBuffer, or Sampler resource.
+
+This attribute is only valid for resource handles, and is an implementation
+detail of clang's HLSL implementation. For more information see
+{doc}`HLSL Resource Types <HLSL/ResourceTypes>`.
+
+
+### riscv_rvv_vector_bits
+
+{clang-attr-syntaxes}`RISCVRVVVectorBitsDocs`
+
+On RISC-V targets, the `riscv_rvv_vector_bits(N)` attribute is used to define
+fixed-length variants of sizeless types.
+
+For example:
+
+```c
+#include <riscv_vector.h>
+
+#if defined(__riscv_v_fixed_vlen)
+typedef vint8m1_t fixed_vint8m1_t __attribute__((riscv_rvv_vector_bits(__riscv_v_fixed_vlen)));
+#endif
+```
+
+Creates a type `fixed_vint8m1_t` that is a fixed-length variant of
+`vint8m1_t` that contains exactly 512 bits. Unlike `vint8m1_t`, this type
+can be used in globals, structs, unions, and arrays, all of which are
+unsupported for sizeless types.
+
+The attribute can be attached to a single RVV vector (such as `vint8m1_t`).
+The attribute will be rejected unless
+`N==(__riscv_v_fixed_vlen*LMUL)`, the implementation defined feature macro that
+is enabled under the `-mrvv-vector-bits` flag. `__riscv_v_fixed_vlen` can
+only be a power of 2 between 64 and 65536.
+
+For types where LMUL!=1, `__riscv_v_fixed_vlen` needs to be scaled by the LMUL
+of the type before passing to the attribute.
+
+For `vbool*_t` types, `__riscv_v_fixed_vlen` needs to be divided by the
+number from the type name. For example, `vbool8_t` needs to use
+`__riscv_v_fixed_vlen` / 8. If the resulting value is not a multiple of 8,
+the type is not supported for that value of `__riscv_v_fixed_vlen`.
+
+
+### type_visibility
+
+{clang-attr-syntaxes}`TypeVisibilityDocs`
+
+The `type_visibility` attribute allows the visibility of a type and its vague
+linkage objects (vtable, typeinfo, typeinfo name) to be controlled separately from
+the visibility of functions and data members of the type.
+
+For example, this can be used to give default visibility to the typeinfo and the vtable
+of a type while still keeping hidden visibility on its member functions and static data
+members.
+
+This attribute can only be applied to types and namespaces.
+
+If both `visibility` and `type_visibility` are applied to a type or a namespace, the
+visibility specified with the `type_visibility` attribute overrides the visibility
+provided with the regular `visibility` attribute.
+
+
+### warn_unused
+
+{clang-attr-syntaxes}`WarnUnusedDocs`
+
+The `warn_unused` attribute can be placed on the declaration of a structure or union type.
+When the `-Wunused-variable` diagnostic is enabled, local variables of types which have a non-trivial constructor or destructor are considered "used" by virtue of the constructor or destructor invocations involved.
+Those constructor or destructor invocations are not considered a use if the type is declared with the `warn_unused` attribute.
+The variable is considered used if it is named outside of its declaration.
+
+This attribute is available in both C and C++ language modes but is primarily useful in C++ for classes which have a non-trivial constructor or destructor but act as a value type rather than an RAII type.
+
+```c++
+struct [[gnu::warn_unused]] S {
+ S();
+ ~S();
+};
+
+struct T {
+ T();
+ ~T();
+ };
+
+ int func() {
+ S s1; // -Wunused-variable warning
+ S s2; // No -Wunused-variable warning because of the member access expression below
+ S s3; // No -Wunused-variable warning because of the sizeof operand below
+ T t; // No -Wunused-variable warning
+
+ s2.~S();
+ return sizeof(s3);
+ }
+```
+
+
diff --git a/clang/docs/AttributeReference/TypeSafetyChecking.md b/clang/docs/AttributeReference/TypeSafetyChecking.md
new file mode 100644
index 0000000000000..33d10d9cdc2e7
--- /dev/null
+++ b/clang/docs/AttributeReference/TypeSafetyChecking.md
@@ -0,0 +1,210 @@
+## Type Safety Checking
+
+Clang supports additional attributes to enable checking type safety properties
+that can't be enforced by the C type system. To see warnings produced by these
+checks, ensure that -Wtype-safety is enabled. Use cases include:
+
+- MPI library implementations, where these attributes enable checking that
+ the buffer type matches the passed `MPI_Datatype`;
+- for HDF5 library there is a similar use case to MPI;
+- checking types of variadic functions' arguments for functions like
+ `fcntl()` and `ioctl()`.
+
+You can detect support for these attributes with `__has_attribute()`. For
+example:
+
+```c++
+#if defined(__has_attribute)
+# if __has_attribute(argument_with_type_tag) && \
+ __has_attribute(pointer_with_type_tag) && \
+ __has_attribute(type_tag_for_datatype)
+# define ATTR_MPI_PWT(buffer_idx, type_idx) __attribute__((pointer_with_type_tag(mpi,buffer_idx,type_idx)))
+/* ... other macros ... */
+# endif
+#endif
+
+#if !defined(ATTR_MPI_PWT)
+# define ATTR_MPI_PWT(buffer_idx, type_idx)
+#endif
+
+int MPI_Send(void *buf, int count, MPI_Datatype datatype /*, other args omitted */)
+ ATTR_MPI_PWT(1,3);
+```
+
+### argument_with_type_tag
+
+{clang-attr-syntaxes}`ArgumentWithTypeTagDocs`
+
+Use `__attribute__((argument_with_type_tag(arg_kind, arg_idx,
+type_tag_idx)))` on a function declaration to specify that the function
+accepts a type tag that determines the type of some other argument.
+
+This attribute is primarily useful for checking arguments of variadic functions
+(`pointer_with_type_tag` can be used in most non-variadic cases).
+
+In the attribute prototype above:
+: - `arg_kind` is an identifier that should be used when annotating all
+ applicable type tags.
+ - `arg_idx` provides the position of a function argument. The expected type of
+ this function argument will be determined by the function argument specified
+ by `type_tag_idx`. In the code example below, "3" means that the type of the
+ function's third argument will be determined by `type_tag_idx`.
+ - `type_tag_idx` provides the position of a function argument. This function
+ argument will be a type tag. The type tag will determine the expected type of
+ the argument specified by `arg_idx`. In the code example below, "2" means
+ that the type tag associated with the function's second argument should agree
+ with the type of the argument specified by `arg_idx`.
+
+For example:
+
+```c++
+int fcntl(int fd, int cmd, ...)
+ __attribute__(( argument_with_type_tag(fcntl,3,2) ));
+// The function's second argument will be a type tag; this type tag will
+// determine the expected type of the function's third argument.
+```
+
+
+### pointer_with_type_tag
+
+{clang-attr-syntaxes}`PointerWithTypeTagDocs`
+
+Use `__attribute__((pointer_with_type_tag(ptr_kind, ptr_idx, type_tag_idx)))`
+on a function declaration to specify that the function accepts a type tag that
+determines the pointee type of some other pointer argument.
+
+In the attribute prototype above:
+: - `ptr_kind` is an identifier that should be used when annotating all
+ applicable type tags.
+ - `ptr_idx` provides the position of a function argument; this function
+ argument will have a pointer type. The expected pointee type of this pointer
+ type will be determined by the function argument specified by
+ `type_tag_idx`. In the code example below, "1" means that the pointee type
+ of the function's first argument will be determined by `type_tag_idx`.
+ - `type_tag_idx` provides the position of a function argument; this function
+ argument will be a type tag. The type tag will determine the expected pointee
+ type of the pointer argument specified by `ptr_idx`. In the code example
+ below, "3" means that the type tag associated with the function's third
+ argument should agree with the pointee type of the pointer argument specified
+ by `ptr_idx`.
+
+For example:
+
+```c++
+typedef int MPI_Datatype;
+int MPI_Send(void *buf, int count, MPI_Datatype datatype /*, other args omitted */)
+ __attribute__(( pointer_with_type_tag(mpi,1,3) ));
+// The function's 3rd argument will be a type tag; this type tag will
+// determine the expected pointee type of the function's 1st argument.
+```
+
+
+### type_tag_for_datatype
+
+{clang-attr-syntaxes}`TypeTagForDatatypeDocs`
+
+When declaring a variable, use
+`__attribute__((type_tag_for_datatype(kind, type)))` to create a type tag that
+is tied to the `type` argument given to the attribute.
+
+In the attribute prototype above:
+: - `kind` is an identifier that should be used when annotating all applicable
+ type tags.
+ - `type` indicates the name of the type.
+
+Clang supports annotating type tags of two forms.
+
+- **Type tag that is a reference to a declared identifier.**
+ Use `__attribute__((type_tag_for_datatype(kind, type)))` when declaring that
+ identifier:
+
+ ```c++
+ typedef int MPI_Datatype;
+ extern struct mpi_datatype mpi_datatype_int
+ __attribute__(( type_tag_for_datatype(mpi,int) ));
+ #define MPI_INT ((MPI_Datatype) &mpi_datatype_int)
+ // &mpi_datatype_int is a type tag. It is tied to type "int".
+ ```
+
+- **Type tag that is an integral literal.**
+ Declare a `static const` variable with an initializer value and attach
+ `__attribute__((type_tag_for_datatype(kind, type)))` on that declaration:
+
+ ```c++
+ typedef int MPI_Datatype;
+ static const MPI_Datatype mpi_datatype_int
+ __attribute__(( type_tag_for_datatype(mpi,int) )) = 42;
+ #define MPI_INT ((MPI_Datatype) 42)
+ // The number 42 is a type tag. It is tied to type "int".
+ ```
+
+The `type_tag_for_datatype` attribute also accepts an optional third argument
+that determines how the type of the function argument specified by either
+`arg_idx` or `ptr_idx` is compared against the type associated with the type
+tag. (Recall that for the `argument_with_type_tag` attribute, the type of the
+function argument specified by `arg_idx` is compared against the type
+associated with the type tag. Also recall that for the `pointer_with_type_tag`
+attribute, the pointee type of the function argument specified by `ptr_idx` is
+compared against the type associated with the type tag.) There are two supported
+values for this optional third argument:
+
+- `layout_compatible` will cause types to be compared according to
+ layout-compatibility rules (In C++11 [class.mem] p 17, 18, see the
+ layout-compatibility rules for two standard-layout struct types and for two
+ standard-layout union types). This is useful when creating a type tag
+ associated with a struct or union type. For example:
+
+ ```c++
+ /* In mpi.h */
+ typedef int MPI_Datatype;
+ struct internal_mpi_double_int { double d; int i; };
+ extern struct mpi_datatype mpi_datatype_double_int
+ __attribute__(( type_tag_for_datatype(mpi,
+ struct internal_mpi_double_int, layout_compatible) ));
+
+ #define MPI_DOUBLE_INT ((MPI_Datatype) &mpi_datatype_double_int)
+
+ int MPI_Send(void *buf, int count, MPI_Datatype datatype, ...)
+ __attribute__(( pointer_with_type_tag(mpi,1,3) ));
+
+ /* In user code */
+ struct my_pair { double a; int b; };
+ struct my_pair *buffer;
+ MPI_Send(buffer, 1, MPI_DOUBLE_INT /*, ... */); // no warning because the
+ // layout of my_pair is
+ // compatible with that of
+ // internal_mpi_double_int
+
+ struct my_int_pair { int a; int b; }
+ struct my_int_pair *buffer2;
+ MPI_Send(buffer2, 1, MPI_DOUBLE_INT /*, ... */); // warning because the
+ // layout of my_int_pair
+ // does not match that of
+ // internal_mpi_double_int
+ ```
+
+- `must_be_null` specifies that the function argument specified by either
+ `arg_idx` (for the `argument_with_type_tag` attribute) or `ptr_idx` (for
+ the `pointer_with_type_tag` attribute) should be a null pointer constant.
+ The second argument to the `type_tag_for_datatype` attribute is ignored. For
+ example:
+
+ ```c++
+ /* In mpi.h */
+ typedef int MPI_Datatype;
+ extern struct mpi_datatype mpi_datatype_null
+ __attribute__(( type_tag_for_datatype(mpi, void, must_be_null) ));
+
+ #define MPI_DATATYPE_NULL ((MPI_Datatype) &mpi_datatype_null)
+ int MPI_Send(void *buf, int count, MPI_Datatype datatype, ...)
+ __attribute__(( pointer_with_type_tag(mpi,1,3) ));
+
+ /* In user code */
+ struct my_pair { double a; int b; };
+ struct my_pair *buffer;
+ MPI_Send(buffer, 1, MPI_DATATYPE_NULL /*, ... */); // warning: MPI_DATATYPE_NULL
+ // was specified but buffer
+ // is not a null pointer
+ ```
+
+
diff --git a/clang/docs/AttributeReference/Undocumented.md b/clang/docs/AttributeReference/Undocumented.md
new file mode 100644
index 0000000000000..038a5cdf2812e
--- /dev/null
+++ b/clang/docs/AttributeReference/Undocumented.md
@@ -0,0 +1,579 @@
+## Undocumented
+
+This section lists attributes which are recognized by Clang, but which are
+currently missing documentation.
+
+### Alignas, align, alignas, aligned
+
+{clang-attr-syntaxes}`Aligned`
+
+No documentation.
+
+
+### NSObject
+
+{clang-attr-syntaxes}`ObjCNSObject`
+
+No documentation.
+
+
+### __kindof
+
+{clang-attr-syntaxes}`ObjCKindOf`
+
+No documentation.
+
+
+### acquired_after
+
+{clang-attr-syntaxes}`AcquiredAfter`
+
+No documentation.
+
+
+### acquired_before
+
+{clang-attr-syntaxes}`AcquiredBefore`
+
+No documentation.
+
+
+### alias
+
+{clang-attr-syntaxes}`Alias`
+
+No documentation.
+
+
+### analyzer_noreturn
+
+{clang-attr-syntaxes}`AnalyzerNoReturn`
+
+No documentation.
+
+
+### available_only_in_default_eval_method
+
+{clang-attr-syntaxes}`AvailableOnlyInDefaultEvalMethod`
+
+No documentation.
+
+
+### blocks
+
+{clang-attr-syntaxes}`Blocks`
+
+No documentation.
+
+
+### capability, shared_capability
+
+{clang-attr-syntaxes}`Capability`
+
+No documentation.
+
+
+### cdecl
+
+{clang-attr-syntaxes}`CDecl`
+
+No documentation.
+
+
+### cf_audited_transfer
+
+{clang-attr-syntaxes}`CFAuditedTransfer`
+
+No documentation.
+
+
+### cf_unknown_transfer
+
+{clang-attr-syntaxes}`CFUnknownTransfer`
+
+No documentation.
+
+
+### common
+
+{clang-attr-syntaxes}`Common`
+
+No documentation.
+
+
+### const
+
+{clang-attr-syntaxes}`Const`
+
+No documentation.
+
+
+### constant
+
+{clang-attr-syntaxes}`CUDAConstant`
+
+No documentation.
+
+
+### consumable_auto_cast_state
+
+{clang-attr-syntaxes}`ConsumableAutoCast`
+
+No documentation.
+
+
+### consumable_set_state_on_read
+
+{clang-attr-syntaxes}`ConsumableSetOnRead`
+
+No documentation.
+
+
+### device
+
+{clang-attr-syntaxes}`CUDADevice`
+
+No documentation.
+
+
+### exclusive_locks_required, requires_capability, requires_shared_capability, shared_locks_required
+
+{clang-attr-syntaxes}`RequiresCapability`
+
+No documentation.
+
+
+### format_arg
+
+{clang-attr-syntaxes}`FormatArg`
+
+No documentation.
+
+
+### global
+
+{clang-attr-syntaxes}`CUDAGlobal`
+
+No documentation.
+
+
+### guarded_by
+
+{clang-attr-syntaxes}`GuardedBy`
+
+No documentation.
+
+
+### guarded_var
+
+{clang-attr-syntaxes}`GuardedVar`
+
+No documentation.
+
+
+### host
+
+{clang-attr-syntaxes}`CUDAHost`
+
+No documentation.
+
+
+### ibaction
+
+{clang-attr-syntaxes}`IBAction`
+
+No documentation.
+
+
+### iboutlet
+
+{clang-attr-syntaxes}`IBOutlet`
+
+No documentation.
+
+
+### iboutletcollection
+
+{clang-attr-syntaxes}`IBOutletCollection`
+
+No documentation.
+
+
+### intel_ocl_bicc
+
+{clang-attr-syntaxes}`IntelOclBicc`
+
+No documentation.
+
+
+### interrupt
+
+{clang-attr-syntaxes}`M68kInterrupt`
+
+No documentation.
+
+
+### interrupt
+
+{clang-attr-syntaxes}`MSP430Interrupt`
+
+No documentation.
+
+
+### lock_returned
+
+{clang-attr-syntaxes}`LockReturned`
+
+No documentation.
+
+
+### lockable
+
+{clang-attr-syntaxes}`Lockable`
+
+No documentation.
+
+
+### locks_excluded
+
+{clang-attr-syntaxes}`LocksExcluded`
+
+No documentation.
+
+
+### matrix_type
+
+{clang-attr-syntaxes}`MatrixType`
+
+No documentation.
+
+
+### may_alias
+
+{clang-attr-syntaxes}`MayAlias`
+
+No documentation.
+
+
+### mips16
+
+{clang-attr-syntaxes}`Mips16`
+
+No documentation.
+
+
+### mode
+
+{clang-attr-syntaxes}`Mode`
+
+No documentation.
+
+
+### naked
+
+{clang-attr-syntaxes}`Naked`
+
+No documentation.
+
+
+### neon_polyvector_type
+
+{clang-attr-syntaxes}`NeonPolyVectorType`
+
+No documentation.
+
+
+### neon_vector_type
+
+{clang-attr-syntaxes}`NeonVectorType`
+
+No documentation.
+
+
+### no_field_protection
+
+{clang-attr-syntaxes}`NoFieldProtection`
+
+No documentation.
+
+
+### no_instrument_function
+
+{clang-attr-syntaxes}`NoInstrumentFunction`
+
+No documentation.
+
+
+### no_thread_safety_analysis
+
+{clang-attr-syntaxes}`NoThreadSafetyAnalysis`
+
+No documentation.
+
+
+### nocommon
+
+{clang-attr-syntaxes}`NoCommon`
+
+No documentation.
+
+
+### nomips16
+
+{clang-attr-syntaxes}`NoMips16`
+
+No documentation.
+
+
+### noreturn
+
+{clang-attr-syntaxes}`NoReturn`
+
+No documentation.
+
+
+### objc_arc_weak_reference_unavailable
+
+{clang-attr-syntaxes}`ArcWeakrefUnavailable`
+
+No documentation.
+
+
+### objc_bridge
+
+{clang-attr-syntaxes}`ObjCBridge`
+
+No documentation.
+
+
+### objc_bridge_mutable
+
+{clang-attr-syntaxes}`ObjCBridgeMutable`
+
+No documentation.
+
+
+### objc_bridge_related
+
+{clang-attr-syntaxes}`ObjCBridgeRelated`
+
+No documentation.
+
+
+### objc_designated_initializer
+
+{clang-attr-syntaxes}`ObjCDesignatedInitializer`
+
+No documentation.
+
+
+### objc_exception
+
+{clang-attr-syntaxes}`ObjCException`
+
+No documentation.
+
+
+### objc_gc
+
+{clang-attr-syntaxes}`ObjCGC`
+
+No documentation.
+
+
+### objc_independent_class
+
+{clang-attr-syntaxes}`ObjCIndependentClass`
+
+No documentation.
+
+
+### objc_ownership
+
+{clang-attr-syntaxes}`ObjCOwnership`
+
+No documentation.
+
+
+### objc_precise_lifetime
+
+{clang-attr-syntaxes}`ObjCPreciseLifetime`
+
+No documentation.
+
+
+### objc_protocol_requires_explicit_implementation
+
+{clang-attr-syntaxes}`ObjCExplicitProtocolImpl`
+
+No documentation.
+
+
+### objc_requires_property_definitions
+
+{clang-attr-syntaxes}`ObjCRequiresPropertyDefs`
+
+No documentation.
+
+
+### objc_returns_inner_pointer
+
+{clang-attr-syntaxes}`ObjCReturnsInnerPointer`
+
+No documentation.
+
+
+### objc_root_class
+
+{clang-attr-syntaxes}`ObjCRootClass`
+
+No documentation.
+
+
+### packed
+
+{clang-attr-syntaxes}`Packed`
+
+No documentation.
+
+
+### pascal
+
+{clang-attr-syntaxes}`Pascal`
+
+No documentation.
+
+
+### pointer_field_protection
+
+{clang-attr-syntaxes}`PointerFieldProtection`
+
+No documentation.
+
+
+### pt_guarded_by
+
+{clang-attr-syntaxes}`PtGuardedBy`
+
+No documentation.
+
+
+### pt_guarded_var
+
+{clang-attr-syntaxes}`PtGuardedVar`
+
+No documentation.
+
+
+### ptrauth_vtable_pointer
+
+{clang-attr-syntaxes}`VTablePointerAuthentication`
+
+No documentation.
+
+
+### pure
+
+{clang-attr-syntaxes}`Pure`
+
+No documentation.
+
+
+### reentrant_capability
+
+{clang-attr-syntaxes}`ReentrantCapability`
+
+No documentation.
+
+
+### reqd_work_group_size
+
+{clang-attr-syntaxes}`ReqdWorkGroupSize`
+
+No documentation.
+
+
+### returns_twice
+
+{clang-attr-syntaxes}`ReturnsTwice`
+
+No documentation.
+
+
+### scoped_lockable
+
+{clang-attr-syntaxes}`ScopedLockable`
+
+No documentation.
+
+
+### shared
+
+{clang-attr-syntaxes}`CUDAShared`
+
+No documentation.
+
+
+### unavailable
+
+{clang-attr-syntaxes}`Unavailable`
+
+No documentation.
+
+
+### uuid
+
+{clang-attr-syntaxes}`Uuid`
+
+No documentation.
+
+
+### vec_type_hint
+
+{clang-attr-syntaxes}`VecTypeHint`
+
+No documentation.
+
+
+### vecreturn
+
+{clang-attr-syntaxes}`VecReturn`
+
+No documentation.
+
+
+### vector_size
+
+{clang-attr-syntaxes}`VectorSize`
+
+No documentation.
+
+
+### visibility
+
+{clang-attr-syntaxes}`Visibility`
+
+No documentation.
+
+
+### weak_import
+
+{clang-attr-syntaxes}`WeakImport`
+
+No documentation.
+
+
+### weakref
+
+{clang-attr-syntaxes}`WeakRef`
+
+No documentation.
+
+
+### work_group_size_hint
+
+{clang-attr-syntaxes}`WorkGroupSizeHint`
+
+No documentation.
+
+
diff --git a/clang/docs/AttributeReference/VariableAttributes.md b/clang/docs/AttributeReference/VariableAttributes.md
new file mode 100644
index 0000000000000..a795a902c9d8b
--- /dev/null
+++ b/clang/docs/AttributeReference/VariableAttributes.md
@@ -0,0 +1,1128 @@
+## Variable Attributes
+
+
+
+### HLSL Interpolation Modifiers
+
+{clang-attr-syntaxes}`HLSLInterpolationModifierDocs`
+
+The HLSL keywords `nointerpolation`, `linear`, `centroid`,
+`noperspective`, `sample`, and `center` control interpolation of pixel
+shader inputs and vertex shader outputs.
+
+When applied to an aggregate type, the modifier propagates recursively to every
+scalar or vector of the type. A modifier on an inner field overrides one
+inherited from an enclosing declaration.
+
+`nointerpolation` cannot be combined with another interpolation modifier.
+For pixel shader inputs and vertex shader outputs, it cannot be used on
+`SV_Position`. Integer, boolean, and 64-bit floating-point components only
+support `nointerpolation`.
+
+Unqualified pixel shader inputs and vertex shader outputs default to `linear`
+for floating-point components of at most 32 bits and `nointerpolation` otherwise.
+`SV_Position` uses the corresponding `noperspective` mode. Vertex shader inputs,
+pixel shader outputs, and signatures in other shader stages have no
+interpolation mode; their interpolation modifiers are ignored.
+
+
+### HLSL Parameter Modifiers
+
+{clang-attr-syntaxes}`HLSLParamQualifierDocs`
+
+HLSL function parameters are passed by value. Parameter declarations support
+three qualifiers to denote parameter passing behavior. The three qualifiers are
+`in`, `out` and `inout`.
+
+Parameters annotated with `in` or with no annotation are passed by value from
+the caller to the callee.
+
+Parameters annotated with `out` are written to the argument after the callee
+returns (Note: arguments values passed into `out` parameters *are not* copied
+into the callee).
+
+Parameters annotated with `inout` are copied into the callee via a temporary,
+and copied back to the argument after the callee returns.
+
+
+### __ptrauth
+
+{clang-attr-syntaxes}`PtrAuthDocs`
+
+The `__ptrauth` qualifier allows the programmer to directly control
+how pointers are signed when they are stored in a particular variable.
+This can be used to strengthen the default protections of pointer
+authentication and make it more difficult for an attacker to escalate
+an ability to alter memory into full control of a process.
+
+```c
+#include <ptrauth.h>
+
+typedef void (*my_callback)(const void*);
+my_callback __ptrauth(ptrauth_key_process_dependent_code, 1, 0xe27a) callback;
+```
+
+The first argument to `__ptrauth` is the name of the signing key.
+Valid key names for the target are defined in `<ptrauth.h>`.
+
+The second argument to `__ptrauth` is a flag (0 or 1) specifying whether
+the object should use address discrimination.
+
+The third argument to `__ptrauth` is a 16-bit non-negative integer which
+allows additional discrimination between objects.
+
+
+### always_destroy
+
+{clang-attr-syntaxes}`AlwaysDestroyDocs`
+
+The `always_destroy` attribute specifies that a variable with static or thread
+storage duration should have its exit-time destructor run. This attribute is the
+default unless clang was invoked with `-fno-c++-static-destructors`.
+
+If a variable is explicitly declared with this attribute, Clang will silence
+otherwise applicable `-Wexit-time-destructors` warnings.
+
+
+### binding
+
+{clang-attr-syntaxes}`HLSLVkBindingDocs`
+
+The `[[vk::binding]]` attribute allows you to explicitly specify the descriptor
+set and binding for a resource when targeting SPIR-V. This is particularly
+useful when you need different bindings for SPIR-V and DXIL, as the `register`
+attribute can be used for DXIL-specific bindings.
+
+The attribute takes two integer arguments: the binding and the descriptor set.
+The descriptor set is optional and defaults to 0 if not provided.
+
+```c++
+// A structured buffer with binding 23 in descriptor set 102.
+[[vk::binding(23, 102)]] StructuredBuffer<float> Buf;
+
+// A structured buffer with binding 14 in descriptor set 0.
+[[vk::binding(14)]] StructuredBuffer<float> Buf2;
+
+// A cbuffer with binding 1 in descriptor set 2.
+[[vk::binding(1, 2)]] cbuffer MyCBuffer {
+ float4x4 worldViewProj;
+};
+```
+
+
+### called_once
+
+{clang-attr-syntaxes}`CalledOnceDocs`
+
+The `called_once` attribute specifies that the annotated function or method
+parameter is invoked exactly once on all execution paths. It only applies
+to parameters with function-like types, i.e. function pointers or blocks. This
+concept is particularly useful for asynchronous programs.
+
+Clang implements a check for `called_once` parameters,
+`-Wcalled-once-parameter`. It is on by default and finds the following
+violations:
+
+- Parameter is not called at all.
+- Parameter is called more than once.
+- Parameter is not called on one of the execution paths.
+
+In the latter case, Clang pinpoints the path where parameter is not invoked
+by showing the control-flow statement where the path diverges.
+
+```objc
+void fooWithCallback(void (^callback)(void) __attribute__((called_once))) {
+ if (somePredicate()) {
+ ...
+ callback();
+ } else {
+ callback(); // OK: callback is called on every path
+ }
+}
+
+void barWithCallback(void (^callback)(void) __attribute__((called_once))) {
+ if (somePredicate()) {
+ ...
+ callback(); // note: previous call is here
+ }
+ callback(); // warning: callback is called twice
+}
+
+void foobarWithCallback(void (^callback)(void) __attribute__((called_once))) {
+ if (somePredicate()) { // warning: callback is not called when condition is false
+ ...
+ callback();
+ }
+}
+```
+
+This attribute is useful for API developers who want to double-check if they
+implemented their method correctly.
+
+
+### clang::code_align
+
+{clang-attr-syntaxes}`CodeAlignAttrDocs`
+
+The `clang::code_align(N)` attribute applies to a loop and specifies the byte
+alignment for a loop. The attribute accepts a positive integer constant
+initialization expression indicating the number of bytes for the minimum
+alignment boundary. Its value must be a power of 2, between 1 and 4096
+(inclusive).
+
+```c++
+void foo() {
+ int var = 0;
+ [[clang::code_align(16)]] for (int i = 0; i < 10; ++i) var++;
+}
+
+void Array(int *array, size_t n) {
+ [[clang::code_align(64)]] for (int i = 0; i < n; ++i) array[i] = 0;
+}
+
+void count () {
+ int a1[10], int i = 0;
+ [[clang::code_align(32)]] while (i < 10) { a1[i] += 3; }
+}
+
+void check() {
+ int a = 10;
+ [[clang::code_align(8)]] do {
+ a = a + 1;
+ } while (a < 20);
+}
+
+template<int A>
+void func() {
+ [[clang::code_align(A)]] for(;;) { }
+}
+```
+
+
+### cleanup
+
+{clang-attr-syntaxes}`CleanupDocs`
+
+This attribute allows a function to be run when a local variable goes out of
+scope. The attribute takes the identifier of a function with a parameter type
+that is a pointer to the type with the attribute.
+
+```c
+static void foo (int *) { ... }
+static void bar (int *) { ... }
+void baz (void) {
+ int x __attribute__((cleanup(foo)));
+ {
+ int y __attribute__((cleanup(bar)));
+ }
+}
+```
+
+The above example will result in a call to `bar` being passed the address of
+`y` when `y` goes out of scope, then a call to `foo` being passed the
+address of `x` when `x` goes out of scope. If two or more variables share
+the same scope, their `cleanup` callbacks are invoked in the reverse order
+the variables were declared in. It is not possible to check the return value
+(if any) of these `cleanup` callback functions.
+
+
+### dllexport
+
+{clang-attr-syntaxes}`DLLExportDocs`
+
+The `__declspec(dllexport)` attribute declares a variable, function, or
+Objective-C interface to be exported from the module. It is available under the
+`-fdeclspec` flag for compatibility with various compilers. The primary use
+is for COFF object files which explicitly specify what interfaces are available
+for external use. See the [dllexport][dllexport] documentation on MSDN for more
+information.
+
+[dllexport]: https://msdn.microsoft.com/en-us/library/3y1sfaz2.aspx
+
+
+### dllimport
+
+{clang-attr-syntaxes}`DLLImportDocs`
+
+The `__declspec(dllimport)` attribute declares a variable, function, or
+Objective-C interface to be imported from an external module. It is available
+under the `-fdeclspec` flag for compatibility with various compilers. The
+primary use is for COFF object files which explicitly specify what interfaces
+are imported from external modules. See the [dllimport][dllimport] documentation on MSDN
+for more information.
+
+Note that a dllimport function may still be inlined, if its definition is
+available and it doesn't reference any non-dllimport functions or global
+variables.
+
+[dllimport]: https://msdn.microsoft.com/en-us/library/3y1sfaz2.aspx
+
+
+### ext_builtin_input
+
+{clang-attr-syntaxes}`HLSLVkExtBuiltinInputDocs`
+
+Vulkan shaders have `Input` builtins. Those variables are externally
+initialized by the driver/pipeline, but each copy is private to the current
+lane.
+
+Those builtins can be declared using the `[[vk::ext_builtin_input]]` attribute
+like follows:
+
+```c++
+[[vk::ext_builtin_input(/* WorkgroupId */ 26)]]
+static const uint3 groupid;
+```
+
+This variable will be lowered into a module-level variable, with the `Input`
+storage class, and the `BuiltIn 26` decoration.
+
+The full documentation for this inline SPIR-V attribute can be found here:
+<https://github.com/microsoft/hlsl-specs/blob/main/proposals/0011-inline-spirv.md>
+
+
+### ext_builtin_output
+
+{clang-attr-syntaxes}`HLSLVkExtBuiltinOutputDocs`
+
+Vulkan shaders have `Output` builtins. Those variables are externally
+visible to the driver/pipeline, but each copy is private to the current
+lane.
+
+Those builtins can be declared using the `[[vk::ext_builtin_output]]`
+attribute like follows:
+
+```c++
+[[vk::ext_builtin_output(/* Position */ 0)]]
+static float4 position;
+```
+
+This variable will be lowered into a module-level variable, with the `Output`
+storage class, and the `BuiltIn 0` decoration.
+
+The full documentation for this inline SPIR-V attribute can be found here:
+<https://github.com/microsoft/hlsl-specs/blob/main/proposals/0011-inline-spirv.md>
+
+
+### groupshared
+
+{clang-attr-syntaxes}`HLSLGroupSharedAddressSpaceDocs`
+
+HLSL enables threads of a compute shader to exchange values via shared memory.
+HLSL provides barrier primitives such as GroupMemoryBarrierWithGroupSync,
+and so on to ensure the correct ordering of reads and writes to shared memory
+in the shader and to avoid data races.
+Here's an example to declare a groupshared variable.
+
+```c++
+groupshared GSData data[5*5*1];
+```
+
+The full documentation is available here: <https://learn.microsoft.com/en-us/windows/win32/direct3dhlsl/dx-graphics-hlsl-variable-syntax#group-shared>
+
+
+### init_priority
+
+{clang-attr-syntaxes}`InitPriorityDocs`
+
+In C++, the order in which global variables are initialized across translation
+units is unspecified, unlike the ordering within a single translation unit. The
+`init_priority` attribute allows you to specify a relative ordering for the
+initialization of objects declared at namespace scope in C++ within a single
+linked image on supported platforms. The priority is given as an integer constant
+expression between 101 and 65535 (inclusive). Priorities outside of that range are
+reserved for use by the implementation. A lower value indicates a higher priority
+of initialization. Note that only the relative ordering of values is important.
+For example:
+
+```c++
+struct SomeType { SomeType(); };
+__attribute__((init_priority(200))) SomeType Obj1;
+__attribute__((init_priority(101))) SomeType Obj2;
+```
+
+`Obj2` will be initialized *before* `Obj1` despite the usual order of
+initialization being the opposite.
+
+Note that this attribute does not control the initialization order of objects
+across final linked image boundaries like shared objects and executables.
+
+On Windows, `init_seg(compiler)` is represented with a priority of 200 and
+`init_seg(library)` is represented with a priority of 400. `init_seg(user)`
+uses the default 65535 priority.
+
+On MachO platforms, this attribute also does not control the order of initialization
+across translation units, where it only affects the order within a single TU.
+
+This attribute is only supported for C++ and Objective-C++ and is ignored in
+other language modes.
+
+
+### init_seg
+
+{clang-attr-syntaxes}`InitSegDocs`
+
+The attribute applied by `pragma init_seg()` controls the section into
+which global initialization function pointers are emitted. It is only
+available with `-fms-extensions`. Typically, this function pointer is
+emitted into `.CRT$XCU` on Windows. The user can change the order of
+initialization by using a different section name with the same
+`.CRT$XC` prefix and a suffix that sorts lexicographically before or
+after the standard `.CRT$XCU` sections. See the [init_seg][init_seg]
+documentation on MSDN for more information.
+
+[init_seg]: http://msdn.microsoft.com/en-us/library/7977wcck(v=vs.110).aspx
+
+
+### leaf
+
+{clang-attr-syntaxes}`LeafDocs`
+
+The `leaf` attribute is used as a compiler hint to improve dataflow analysis
+in library functions. Functions marked with the `leaf` attribute are not allowed
+to jump back into the caller's translation unit, whether through invoking a
+callback function, an external function call, use of `longjmp`, or other means.
+Therefore, they cannot use or modify any data that does not escape the caller function's
+compilation unit.
+
+For more information see the
+[GCC common attributes documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html)
+
+
+### loader_uninitialized
+
+{clang-attr-syntaxes}`LoaderUninitializedDocs`
+
+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.
+
+
+### location
+
+{clang-attr-syntaxes}`HLSLVkLocationDocs`
+
+Attribute used for specifying the location number for the stage input/output
+variables. Allowed on function parameters, function returns, and struct
+fields. This parameter has no effect when used outside of an entrypoint
+parameter/parameter field/return value.
+
+This attribute maps to the `Location` SPIR-V decoration.
+
+
+### maybe_undef
+
+{clang-attr-syntaxes}`MaybeUndefDocs`
+
+The `maybe_undef` attribute can be placed on a function parameter. It indicates
+that the parameter is allowed to use undef values. It informs the compiler
+to insert a freeze LLVM IR instruction on the function parameter.
+Please note that this is an attribute that is used as an internal
+implementation detail and not intended to be used by external users.
+
+In languages HIP, CUDA etc., some functions have multi-threaded semantics and
+it is enough for only one or some threads to provide defined arguments.
+Depending on semantics, undef arguments in some threads don't produce
+undefined results in the function call. Since, these functions accept undefined
+arguments, `maybe_undef` attribute can be placed.
+
+Sample usage:
+
+```c
+void maybeundeffunc(int __attribute__((maybe_undef))param);
+```
+
+
+### maybe_unused, unused
+
+{clang-attr-syntaxes}`WarnMaybeUnusedDocs`
+
+When passing the `-Wunused` flag to Clang, entities that are unused by the
+program may be diagnosed. The `[[maybe_unused]]` (or
+`__attribute__((unused))`) attribute can be used to silence such diagnostics
+when the entity cannot be removed. For instance, a local variable may exist
+solely for use in an `assert()` statement, which makes the local variable
+unused when `NDEBUG` is defined.
+
+The attribute may be applied to the declaration of a class, a typedef, a
+variable, a function or method, a function parameter, an enumeration, an
+enumerator, a non-static data member, or a label.
+
+```c++
+#include <cassert>
+
+[[maybe_unused]] void f([[maybe_unused]] bool thing1,
+ [[maybe_unused]] bool thing2) {
+ [[maybe_unused]] bool b = thing1 && thing2;
+ assert(b);
+}
+```
+
+
+### model
+
+{clang-attr-syntaxes}`CodeModelDocs`
+
+The `model` attribute allows overriding the translation unit's
+code model (specified by `-mcmodel`) for a specific global variable.
+
+On LoongArch, allowed values are "normal", "medium", "extreme".
+
+On x86-64, allowed values are `"small"` and `"large"`. `"small"` is
+roughly equivalent to `-mcmodel=small`, meaning the global is considered
+"small" placed closer to the `.text` section relative to "large" globals, and
+to prefer using 32-bit relocations to access the global. `"large"` is roughly
+equivalent to `-mcmodel=large`, meaning the global is considered "large" and
+placed further from the `.text` section relative to "small" globals, and
+64-bit relocations must be used to access the global.
+
+
+### no_destroy
+
+{clang-attr-syntaxes}`NoDestroyDocs`
+
+The `no_destroy` attribute specifies that a variable with static or thread
+storage duration shouldn't have its exit-time destructor run. Annotating every
+static and thread duration variable with this attribute is equivalent to
+invoking clang with `-fno-c++-static-destructors`.
+
+If a variable is declared with this attribute, clang doesn't access check or
+generate the type's destructor. If you have a type that you only want to be
+annotated with `no_destroy`, you can therefore declare the destructor private:
+
+```c++
+struct only_no_destroy {
+ only_no_destroy();
+private:
+ ~only_no_destroy();
+};
+
+[[clang::no_destroy]] only_no_destroy global; // fine!
+```
+
+Note that destructors are still required for subobjects of aggregates annotated
+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:
+
+```c++
+void f() {
+ try {
+ [[clang::no_destroy]]
+ static only_no_destroy array[10]; // error, only_no_destroy has a private destructor.
+ } catch (...) {
+ // Handle the error
+ }
+}
+```
+
+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.
+
+
+### nodebug
+
+{clang-attr-syntaxes}`NoDebugDocs`
+
+The `nodebug` attribute allows you to suppress debugging information for a
+function or method, for a variable that is not a parameter or a non-static
+data member, or for a typedef or using declaration.
+
+
+### noescape
+
+{clang-attr-syntaxes}`NoEscapeDocs`
+
+`noescape` placed on a function parameter of a pointer type is used to inform
+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 actually escape. The optimizer may make
+assumptions based on the fact that it knows that a call to the function does
+not escape a certain parameter, so incorrectly annotating a parameter with
+`noescape` leads to undefined behavior. The callee is also not allowed to
+deallocate memory through a `noescape` parameter: the optimizer does not make
+assumptions based on this information at the moment, but may do so in the
+future. Some cases of invalid uses of `noescape` can be found with
+{ref}`-Wlifetime-safety-noescape <Wlifetime-safety-noescape>`.
+
+For example:
+
+```c
+int *gp;
+
+void nonescapingFunc(__attribute__((noescape)) int *p) {
+ *p += 100; // OK.
+}
+
+void escapingFunc(__attribute__((noescape)) int *p) {
+ gp = p; // Not OK.
+}
+
+void freeingFunc(__attribute__((noescape)) int *p) {
+ free(p); // Not OK.
+}
+```
+
+Since `noescape` is a parameter attribute and not a type attribute, it only
+applies to the outermost pointer level, regardless of where in the parameter
+declaration you place it:
+
+```c
+int **gp;
+
+void nestingEscapes(__attribute__((noescape)) int **p) {
+ gp = p; // Not OK.
+ *gp = *p; // OK, p does not escape.
+}
+```
+
+Additionally, when the parameter is a
+{doc}`block pointer <BlockLanguageSpec>`, the same restriction applies to
+copies of the block. For example:
+
+```c
+typedef void (^BlockTy)();
+BlockTy g0, g1;
+
+void nonescapingFunc(__attribute__((noescape)) BlockTy block) {
+ block(); // OK.
+}
+
+void escapingFunc(__attribute__((noescape)) BlockTy block) {
+ g0 = block; // Not OK.
+ g1 = Block_copy(block); // Not OK either.
+}
+```
+
+The function *is* allowed to leak information about the memory address of the
+pointer, but not any provenance of the allocation:
+
+```c
+bool isNull(__attribute__((noescape)) void *p) {
+ return !p; // OK.
+}
+
+uintptr_t gi;
+
+void escapingAddress(__attribute__((noescape)) int *p) {
+ // OK *if and only if* gi is never casted back to a pointer.
+ gi = (uintptr_t)p;
+}
+
+bool usingEscapedAddress(int *p) {
+ return (uintptr_t)p > gi; // OK.
+}
+
+bool usingEscapedPointer(int *p) {
+ return p > (int*)gi; // Not OK.
+}
+
+int *gp;
+
+void escapingEndFunc(__attribute__((noescape)) int *p, size_t len) {
+ gp = p + len; // Not OK.
+}
+```
+
+
+### nosvm
+
+{clang-attr-syntaxes}`OpenCLNoSVMDocs`
+
+OpenCL 2.0 supports the optional `__attribute__((nosvm))` qualifier for
+pointer variable. It informs the compiler that the pointer does not refer
+to a shared virtual memory region. See OpenCL v2.0 s6.7.2 for details.
+
+Since it is not widely used and has been removed from OpenCL 2.1, it is ignored
+by Clang.
+
+
+### objc_externally_retained
+
+{clang-attr-syntaxes}`ObjCExternallyRetainedDocs`
+
+The `objc_externally_retained` attribute can be applied to strong local
+variables, functions, methods, or blocks to opt into
+{ref}`externally-retained semantics <arc.misc.externally_retained>`.
+
+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 behavior for that parameter. For instance,
+`first_param` is externally-retained below, but not `second_param`:
+
+```objc
+__attribute__((objc_externally_retained))
+void f(NSArray *first_param, __strong NSArray *second_param) {
+ // ...
+}
+```
+
+Likewise, when applied to a strong local variable, that variable becomes
+`const` and is considered externally-retained.
+
+When compiled without `-fobjc-arc`, this attribute is ignored.
+
+
+### pass_object_size, pass_dynamic_object_size
+
+{clang-attr-syntaxes}`PassObjectSizeDocs`
+
+:::{Note}
+The mangling of functions with parameters that are annotated with
+`pass_object_size` is subject to change. You can get around this by
+using `__asm__("foo")` to explicitly name your functions, thus preserving
+your ABI; also, non-overloadable C functions with `pass_object_size` are
+not mangled.
+:::
+
+The `pass_object_size(Type)` attribute can be placed on function parameters to
+instruct clang to call `__builtin_object_size(param, Type)` at each callsite
+of said function, and implicitly pass the result of this call in as an invisible
+argument of type `size_t` directly after the parameter annotated with
+`pass_object_size`. Clang will also replace any calls to
+`__builtin_object_size(param, Type)` in the function by said implicit
+parameter.
+
+Example usage:
+
+```c
+int bzero1(char *const p __attribute__((pass_object_size(0))))
+ __attribute__((noinline)) {
+ int i = 0;
+ for (/**/; i < (int)__builtin_object_size(p, 0); ++i) {
+ p[i] = 0;
+ }
+ return i;
+}
+
+int main() {
+ char chars[100];
+ int n = bzero1(&chars[0]);
+ assert(n == sizeof(chars));
+ return 0;
+}
+```
+
+If successfully evaluating `__builtin_object_size(param, Type)` at the
+callsite is not possible, then the "failed" value is passed in. So, using the
+definition of `bzero1` from above, the following code would exit cleanly:
+
+```c
+int main2(int argc, char *argv[]) {
+ int n = bzero1(argv);
+ assert(n == -1);
+ return 0;
+}
+```
+
+`pass_object_size` plays a part in overload resolution. If two overload
+candidates are otherwise equally good, then the overload with one or more
+parameters with `pass_object_size` is preferred. This implies that the choice
+between two identical overloads both with `pass_object_size` on one or more
+parameters will always be ambiguous; for this reason, having two such overloads
+is illegal. For example:
+
+```c++
+#define PS(N) __attribute__((pass_object_size(N)))
+// OK
+void Foo(char *a, char *b); // Overload A
+// OK -- overload A has no parameters with pass_object_size.
+void Foo(char *a PS(0), char *b PS(0)); // Overload B
+// Error -- Same signature (sans pass_object_size) as overload B, and both
+// overloads have one or more parameters with the pass_object_size attribute.
+void Foo(void *a PS(0), void *b);
+
+// OK
+void Bar(void *a PS(0)); // Overload C
+// OK
+void Bar(char *c PS(1)); // Overload D
+
+void main() {
+ char known[10], *unknown;
+ Foo(unknown, unknown); // Calls overload B
+ Foo(known, unknown); // Calls overload B
+ Foo(unknown, known); // Calls overload B
+ Foo(known, known); // Calls overload B
+
+ Bar(known); // Calls overload D
+ Bar(unknown); // Calls overload D
+}
+```
+
+Currently, `pass_object_size` is a bit restricted in terms of its usage:
+
+- Only one use of `pass_object_size` is allowed per parameter.
+- It is an error to take the address of a function with `pass_object_size` on
+ any of its parameters. If you wish to do this, you can create an overload
+ without `pass_object_size` on any parameters.
+- It is an error to apply the `pass_object_size` attribute to parameters that
+ are not pointers. Additionally, any parameter that `pass_object_size` is
+ applied to must be marked `const` at its function's definition.
+
+Clang also supports the `pass_dynamic_object_size` attribute, which behaves
+identically to `pass_object_size`, but evaluates a call to
+`__builtin_dynamic_object_size` at the callee instead of
+`__builtin_object_size`. `__builtin_dynamic_object_size` provides some extra
+runtime checks when the object size can't be determined at compile-time. You can
+read more about `__builtin_dynamic_object_size` in
+{ref}`Evaluating Object Size <langext-evaluating-object-size>`.
+
+
+### push_constant
+
+{clang-attr-syntaxes}`HLSLVkPushConstantDocs`
+
+Vulkan shaders have `PushConstants`
+
+The `[[vk::push_constant]]` attribute allows you to declare this
+global variable as a push constant when targeting Vulkan.
+This attribute is ignored otherwise.
+
+This attribute must be applied to the variable, not underlying type.
+The variable type must be a struct, per the requirements of Vulkan, "there
+must be no more than one push constant block statically used per shader entry
+point."
+
+
+### require_constant_initialization, constinit (C++20)
+
+{clang-attr-syntaxes}`ConstInitDocs`
+
+This attribute specifies that the variable to which it is attached is intended
+to have a [*constant initializer*](http://en.cppreference.com/w/cpp/language/constant_initialization)
+according to the rules of [basic.start.static]. The variable is required to
+have static or thread storage duration. If the initialization of the variable
+is not a constant initializer an error will be produced. This attribute may
+only be used in C++; the `constinit` spelling is only accepted in C++20
+onwards.
+
+Note that in C++03 strict constant expression checking is not done. Instead
+the attribute reports if Clang can emit the variable as a constant, even if it's
+not technically a *constant initializer*. This behavior is non-portable.
+
+Static storage duration variables with constant initializers avoid hard-to-find
+bugs caused by the indeterminate order of dynamic initialization. They can also
+be safely used during dynamic initialization across translation units.
+
+This attribute acts as a compile time assertion that the requirements
+for constant initialization have been met. Since these requirements change
+between dialects and have subtle pitfalls it's important to fail fast instead
+of silently falling back on dynamic initialization.
+
+The first use of the attribute on a variable must be part of, or precede, the
+initializing declaration of the variable. C++20 requires the `constinit`
+spelling of the attribute to be present on the initializing declaration if it
+is used anywhere. The other spellings can be specified on a forward declaration
+and omitted on a later initializing declaration.
+
+```c++
+// -std=c++14
+#define SAFE_STATIC [[clang::require_constant_initialization]]
+struct T {
+ constexpr T(int) {}
+ ~T(); // non-trivial
+};
+SAFE_STATIC T x = {42}; // Initialization OK. Doesn't check destructor.
+SAFE_STATIC T y = 42; // error: variable does not have a constant initializer
+// copy initialization is not a constant expression on a non-literal type.
+```
+
+
+### row_major, column_major
+
+{clang-attr-syntaxes}`HLSLMatrixLayoutDocs`
+
+The `row_major` and `column_major` keywords specify the memory layout
+of an HLSL matrix type.
+
+- `row_major`: Matrices are stored in memory row-by-row.
+- `column_major`: Matrices are stored in memory column-by-column (default).
+
+Example:
+
+```hlsl
+row_major float2x2 myMatrix;
+```
+
+
+### section, __declspec(allocate)
+
+{clang-attr-syntaxes}`SectionDocs`
+
+The `section` attribute allows you to specify a specific section a
+global variable or function should be in after translation.
+
+
+### standalone_debug
+
+{clang-attr-syntaxes}`StandaloneDebugDocs`
+
+The `standalone_debug` attribute causes debug info to be emitted for a record
+type regardless of the debug info optimizations that are enabled with
+-fno-standalone-debug. This attribute only has an effect when debug info
+optimizations are enabled (e.g. with -fno-standalone-debug), and is C++-only.
+
+
+### swift_async_context
+
+{clang-attr-syntaxes}`SwiftAsyncContextDocs`
+
+The `swift_async_context` attribute marks a parameter of a `swiftasynccall`
+function as having the special asynchronous context-parameter ABI treatment.
+
+If the function is not `swiftasynccall`, this attribute only generates
+extended frame information.
+
+A context parameter must have pointer or reference type.
+
+
+### swift_context
+
+{clang-attr-syntaxes}`SwiftContextDocs`
+
+The `swift_context` attribute marks a parameter of a `swiftcall`
+or `swiftasynccall` function as having the special context-parameter
+ABI treatment.
+
+This treatment generally passes the context value in a special register
+which is normally callee-preserved.
+
+A `swift_context` parameter must either be the last parameter or must be
+followed by a `swift_error_result` parameter (which itself must always be
+the last parameter).
+
+A context parameter must have pointer or reference type.
+
+
+### swift_error_result
+
+{clang-attr-syntaxes}`SwiftErrorResultDocs`
+
+The `swift_error_result` attribute marks a parameter of a `swiftcall`
+function as having the special error-result ABI treatment.
+
+This treatment generally passes the underlying error value in and out of
+the function through a special register which is normally callee-preserved.
+This is modeled in C by pretending that the register is addressable memory:
+
+- The caller appears to pass the address of a variable of pointer type.
+ The current value of this variable is copied into the register before
+ the call; if the call returns normally, the value is copied back into the
+ variable.
+- The callee appears to receive the address of a variable. This address
+ is actually a hidden location in its own stack, initialized with the
+ value of the register upon entry. When the function returns normally,
+ the value in that hidden location is written back to the register.
+
+A `swift_error_result` parameter must be the last parameter, and it must be
+preceded by a `swift_context` parameter.
+
+A `swift_error_result` parameter must have type `T**` or `T*&` for some
+type T. Note that no qualifiers are permitted on the intermediate level.
+
+It is undefined behavior if the caller does not pass a pointer or
+reference to a valid object.
+
+The standard convention is that the error value itself (that is, the
+value stored in the apparent argument) will be null upon function entry,
+but this is not enforced by the ABI.
+
+
+### swift_indirect_result
+
+{clang-attr-syntaxes}`SwiftIndirectResultDocs`
+
+The `swift_indirect_result` attribute marks a parameter of a `swiftcall`
+or `swiftasynccall` function as having the special indirect-result ABI
+treatment.
+
+This treatment gives the parameter the target's normal indirect-result
+ABI treatment, which may involve passing it differently from an ordinary
+parameter. However, only the first indirect result will receive this
+treatment. Furthermore, low-level lowering may decide that a direct result
+must be returned indirectly; if so, this will take priority over the
+`swift_indirect_result` parameters.
+
+A `swift_indirect_result` parameter must either be the first parameter or
+follow another `swift_indirect_result` parameter.
+
+A `swift_indirect_result` parameter must have type `T*` or `T&` for
+some object type `T`. If `T` is a complete type at the point of
+definition of a function, it is undefined behavior if the argument
+value does not point to storage of adequate size and alignment for a
+value of type `T`.
+
+Making indirect results explicit in the signature allows C functions to
+directly construct objects into them without relying on language
+optimizations like C++'s named return value optimization (NRVO).
+
+
+### swiftasynccall
+
+{clang-attr-syntaxes}`SwiftAsyncCallDocs`
+
+The `swiftasynccall` attribute indicates that a function is
+compatible with the low-level conventions of Swift async functions,
+provided it declares the right formal arguments.
+
+In most respects, this is similar to the `swiftcall` attribute, except for
+the following:
+
+- A parameter may be marked `swift_async_context`, `swift_context`
+ or `swift_indirect_result` (with the same restrictions on parameter
+ ordering as `swiftcall`) but the parameter attribute
+ `swift_error_result` is not permitted.
+- A `swiftasynccall` function must have return type `void`.
+- Within a `swiftasynccall` function, a call to a `swiftasynccall`
+ function that is the immediate operand of a `return` statement is
+ guaranteed to be performed as a tail call. This syntax is allowed even
+ in C as an extension (a call to a void-returning function cannot be a
+ return operand in standard C). If something in the calling function would
+ semantically be performed after a guaranteed tail call, such as the
+ non-trivial destruction of a local variable or temporary,
+ then the program is ill-formed.
+
+Query for this attribute with `__has_attribute(swiftasynccall)`. Query if
+the target supports the calling convention with
+`__has_extension(swiftasynccc)`.
+
+Since this attribute follows the Swift async calling convention, it is
+considered ABI-unstable except on targets where the Swift project
+has declared ABI stability. Users are responsible for ensuring that
+calls and definitions of functions with this attribute are compiled
+with compatible compilers. Note that different operating systems
+on the same architecture may use different ABIs and therefore may
+have different standards for ABI stability.
+
+
+### swiftcall
+
+{clang-attr-syntaxes}`SwiftCallDocs`
+
+The `swiftcall` attribute indicates that a function should be called
+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 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
+stack. The `swiftcall` convention only handles this second phase of
+lowering; the C function type must accurately reflect the results
+of the first phase, as follows:
+
+- Results classified as indirect by high-level lowering should be
+ represented as parameters with the `swift_indirect_result` attribute.
+
+- Results classified as direct by high-level lowering should be represented
+ as follows:
+
+ - First, remove any empty direct results.
+ - If there are no direct results, the C result type should be `void`.
+ - If there is one direct result, the C result type should be a type with
+ the exact layout of that result type.
+ - If there are a multiple direct results, the C result type should be
+ a struct type with the exact layout of a tuple of those results.
+
+- Parameters classified as indirect by high-level lowering should be
+ represented as parameters of pointer type.
+
+- Parameters classified as direct by high-level lowering should be
+ omitted if they are empty types; otherwise, they should be represented
+ as a parameter type with a layout exactly matching the layout of the
+ Swift parameter type.
+
+- The context parameter, if present, should be represented as a trailing
+ parameter with the `swift_context` attribute.
+
+- The error result parameter, if present, should be represented as a
+ trailing parameter (always following a context parameter) with the
+ `swift_error_result` attribute.
+
+`swiftcall` does not support variadic arguments or unprototyped functions.
+
+The parameter ABI treatment attributes are aspects of the function type.
+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.
+
+Support for this feature is target-dependent, although it should be
+supported on every target that Swift supports. Query for this attribute
+with `__has_attribute(swiftcall)`. Query if the target supports the
+calling convention with `__has_extension(swiftcc)`. This implies
+support for the `swift_context`, `swift_error_result`, and
+`swift_indirect_result` attributes.
+
+Since this attribute follows the Swift calling convention, it is
+considered ABI-unstable except on targets where the Swift project
+has declared ABI stability. Users are responsible for ensuring that
+calls and definitions of functions with this attribute are compiled
+with compatible compilers. Note that different operating systems
+on the same architecture may use different ABIs and therefore may
+have different standards for ABI stability.
+
+
+### thread
+
+{clang-attr-syntaxes}`ThreadDocs`
+
+The `__declspec(thread)` attribute declares a variable with thread local
+storage. It is available under the `-fms-extensions` flag for MSVC
+compatibility. See the documentation for [`__declspec(thread)`][__declspec(thread)] on MSDN.
+
+In Clang, `__declspec(thread)` is generally equivalent in functionality to the
+GNU `__thread` keyword. The variable must not have a destructor and must have
+a constant initializer, if any. The attribute only applies to variables
+declared with static storage duration, such as globals, class static data
+members, and static locals.
+
+[__declspec(thread)]: http://msdn.microsoft.com/en-us/library/9w1sdazb.aspx
+
+
+### tls_model
+
+{clang-attr-syntaxes}`TLSModelDocs`
+
+The `tls_model` attribute allows you to specify which thread-local storage
+model to use. It accepts the following strings:
+
+- global-dynamic
+- local-dynamic
+- initial-exec
+- local-exec
+
+TLS models are mutually exclusive.
+
+
+### uninitialized
+
+{clang-attr-syntaxes}`UninitializedDocs`
+
+The command-line parameter `-ftrivial-auto-var-init=*` can be used to
+initialize trivial automatic stack variables. By default, trivial automatic
+stack variables are uninitialized. This attribute is used to override the
+command-line parameter, forcing variables to remain uninitialized. It has no
+semantic meaning in that using uninitialized values is undefined behavior,
+it rather documents the programmer's intent.
+
+
diff --git a/clang/docs/CMakeLists.txt b/clang/docs/CMakeLists.txt
index b074641fe3800..0e842f0c4189e 100644
--- a/clang/docs/CMakeLists.txt
+++ b/clang/docs/CMakeLists.txt
@@ -108,8 +108,6 @@ if (LLVM_ENABLE_SPHINX)
# copy all the non-generated source files from the source to the build
# directory before we run sphinx.
set(clang_generated_docs
- AttributeReference.md
- _generated/AttributeReference.split.md
_generated/AttributeReferenceSyntaxes.json
DiagnosticsReference.md
AMDGPUBuiltinReference.rst
@@ -118,8 +116,6 @@ if (LLVM_ENABLE_SPHINX)
add_sphinx_source_sync_target(copy-clang-rst-docs
"${CMAKE_CURRENT_SOURCE_DIR}" "${CMAKE_CURRENT_BINARY_DIR}"
PRESERVE_DOCS ${clang_generated_docs})
- set(clang_docs_sync_stamp
- "${CMAKE_CURRENT_BINARY_DIR}/CMakeFiles/copy-clang-rst-docs.sphinx-source-sync/sync.stamp")
add_custom_command(TARGET copy-clang-rst-docs POST_BUILD
COMMAND "${CMAKE_COMMAND}" -E copy_if_different
"${CMAKE_CURRENT_SOURCE_DIR}/../Maintainers.md"
@@ -154,29 +150,7 @@ if (LLVM_ENABLE_SPHINX)
endif()
# Generated files
- set(attr_reference_split_input "${CMAKE_CURRENT_BINARY_DIR}/_generated/AttributeReference.split.md")
- set(attr_reference_split_stamp "${CMAKE_CURRENT_BINARY_DIR}/_generated/AttributeReferenceSplit.stamp")
- gen_sphinx_file_from_td(_generated/AttributeReference.split.md -gen-attr-docs ../include/clang/Basic/Attr.td "")
gen_sphinx_file_from_td(_generated/AttributeReferenceSyntaxes.json -gen-attr-doc-syntaxes ../include/clang/Basic/Attr.td "${docs_targets}")
- add_custom_command(
- OUTPUT "${attr_reference_split_stamp}"
- COMMAND "${CMAKE_COMMAND}" -E rm -rf
- "${CMAKE_CURRENT_BINARY_DIR}/AttributeReference"
- COMMAND $<TARGET_FILE:split-file>
- "${attr_reference_split_input}"
- "${CMAKE_CURRENT_BINARY_DIR}"
- COMMAND "${CMAKE_COMMAND}" -E touch
- "${attr_reference_split_stamp}"
- DEPENDS "${attr_reference_split_input}"
- "${clang_docs_sync_stamp}"
- split-file
- VERBATIM
- COMMENT "Splitting generated AttributeReference Markdown")
- add_custom_target(gen-AttributeReferenceSplit
- DEPENDS "${attr_reference_split_stamp}")
- foreach(target ${docs_targets})
- add_dependencies(${target} gen-AttributeReferenceSplit)
- endforeach()
gen_sphinx_file_from_td(DiagnosticsReference.md -gen-diag-docs ../include/clang/Basic/Diagnostic.td "${docs_targets}")
gen_sphinx_file_from_td(AMDGPUBuiltinReference.rst -gen-builtin-docs ../include/clang/Basic/BuiltinsAMDGPU.td "${docs_targets}")
gen_sphinx_file_from_td(ClangCommandLineReference.md -gen-opt-docs ../include/clang/Options/ClangOptionDocs.td "${docs_targets}")
diff --git a/clang/docs/_extensions/clang_attr_syntaxes.py b/clang/docs/_extensions/clang_attr_syntaxes.py
index be5762faa997d..288671bc0c645 100644
--- a/clang/docs/_extensions/clang_attr_syntaxes.py
+++ b/clang/docs/_extensions/clang_attr_syntaxes.py
@@ -3,11 +3,17 @@
from __future__ import annotations
import json
+import re
from pathlib import Path
from docutils import nodes
from sphinx.errors import ExtensionError
from sphinx.transforms import SphinxTransform
+from sphinx.util import logging
+
+
+LOGGER = logging.getLogger(__name__)
+ATTRIBUTE_HEADING_RE = re.compile(r"^###\s+(.+?)\s*$")
class clang_attr_syntaxes(nodes.General, nodes.Element):
@@ -135,6 +141,34 @@ def apply(self):
node.replace_self(replacement)
+def check_attribute_heading_order(app):
+ attribute_reference_dir = Path(app.srcdir) / "AttributeReference"
+ if not attribute_reference_dir.is_dir():
+ return
+
+ for path in sorted(attribute_reference_dir.glob("*.md")):
+ headings = []
+ for line_no, line in enumerate(
+ path.read_text(encoding="utf-8").splitlines(), 1
+ ):
+ match = ATTRIBUTE_HEADING_RE.match(line)
+ if match:
+ headings.append((match.group(1), line_no))
+
+ sorted_headings = sorted(heading for heading, _ in headings)
+ for index, (heading, line_no) in enumerate(headings):
+ if heading != sorted_headings[index]:
+ LOGGER.warning(
+ "attribute heading %r on line %d is out of order; "
+ "expected %r here",
+ heading,
+ line_no,
+ sorted_headings[index],
+ location=str(path),
+ )
+ break
+
+
def setup(app):
"""Register the Clang attribute syntax extension with Sphinx."""
app.add_config_value(
@@ -144,4 +178,5 @@ def setup(app):
)
app.add_role("clang-attr-syntaxes", clang_attr_syntaxes_role)
app.add_transform(ClangAttrSyntaxesTransform)
+ app.connect("builder-inited", check_attribute_heading_order)
return {"version": "1.0", "parallel_read_safe": True, "parallel_write_safe": True}
More information about the llvm-branch-commits
mailing list