[llvm-branch-commits] [clang] [clang][docs] Rewrite 20 selected Clang docs from reST to Markdown (PR #208310)
Reid Kleckner via llvm-branch-commits
llvm-branch-commits at lists.llvm.org
Thu Jul 9 08:13:24 PDT 2026
https://github.com/rnk updated https://github.com/llvm/llvm-project/pull/208310
>From fd00ac7106b4dadc0c96ebb5ab184e2a9cddb5ea Mon Sep 17 00:00:00 2001
From: Reid Kleckner <rkleckner at nvidia.com>
Date: Wed, 8 Jul 2026 18:52:25 +0000
Subject: [PATCH 1/5] [docs] Rename selected Clang docs to Markdown
---
clang/docs/{HIPSupport.rst => HIPSupport.md} | 0
clang/docs/HLSL/{HLSLDocs.rst => HLSLDocs.md} | 0
clang/docs/InternalsManual.rst | 2 +-
clang/docs/{LTOVisibility.rst => LTOVisibility.md} | 0
clang/docs/{MSVCCompatibility.rst => MSVCCompatibility.md} | 0
clang/docs/{MisExpect.rst => MisExpect.md} | 0
clang/docs/{Modules.rst => Modules.md} | 0
clang/docs/{OpenCLSupport.rst => OpenCLSupport.md} | 0
clang/docs/{OpenMPSupport.rst => OpenMPSupport.md} | 0
.../{OverflowBehaviorTypes.rst => OverflowBehaviorTypes.md} | 0
.../{PointerAuthentication.rst => PointerAuthentication.md} | 0
clang/docs/{SYCLSupport.rst => SYCLSupport.md} | 0
clang/docs/{SafeStack.rst => SafeStack.md} | 0
...anitizerSpecialCaseList.rst => SanitizerSpecialCaseList.md} | 0
clang/docs/{SanitizerStats.rst => SanitizerStats.md} | 0
clang/docs/{ShadowCallStack.rst => ShadowCallStack.md} | 0
...{SourceBasedCodeCoverage.rst => SourceBasedCodeCoverage.md} | 0
...tandardCPlusPlusModules.rst => StandardCPlusPlusModules.md} | 0
clang/docs/{StructureProtection.rst => StructureProtection.md} | 0
clang/docs/{ThinLTO.rst => ThinLTO.md} | 0
clang/docs/{UsersManual.rst => UsersManual.md} | 0
clang/lib/CodeGen/CodeGenModule.cpp | 2 +-
clang/lib/Driver/ToolChains/MSVC.cpp | 2 +-
clang/test/CodeGen/ubsan-type-ignorelist-category.test | 3 +--
24 files changed, 4 insertions(+), 5 deletions(-)
rename clang/docs/{HIPSupport.rst => HIPSupport.md} (100%)
rename clang/docs/HLSL/{HLSLDocs.rst => HLSLDocs.md} (100%)
rename clang/docs/{LTOVisibility.rst => LTOVisibility.md} (100%)
rename clang/docs/{MSVCCompatibility.rst => MSVCCompatibility.md} (100%)
rename clang/docs/{MisExpect.rst => MisExpect.md} (100%)
rename clang/docs/{Modules.rst => Modules.md} (100%)
rename clang/docs/{OpenCLSupport.rst => OpenCLSupport.md} (100%)
rename clang/docs/{OpenMPSupport.rst => OpenMPSupport.md} (100%)
rename clang/docs/{OverflowBehaviorTypes.rst => OverflowBehaviorTypes.md} (100%)
rename clang/docs/{PointerAuthentication.rst => PointerAuthentication.md} (100%)
rename clang/docs/{SYCLSupport.rst => SYCLSupport.md} (100%)
rename clang/docs/{SafeStack.rst => SafeStack.md} (100%)
rename clang/docs/{SanitizerSpecialCaseList.rst => SanitizerSpecialCaseList.md} (100%)
rename clang/docs/{SanitizerStats.rst => SanitizerStats.md} (100%)
rename clang/docs/{ShadowCallStack.rst => ShadowCallStack.md} (100%)
rename clang/docs/{SourceBasedCodeCoverage.rst => SourceBasedCodeCoverage.md} (100%)
rename clang/docs/{StandardCPlusPlusModules.rst => StandardCPlusPlusModules.md} (100%)
rename clang/docs/{StructureProtection.rst => StructureProtection.md} (100%)
rename clang/docs/{ThinLTO.rst => ThinLTO.md} (100%)
rename clang/docs/{UsersManual.rst => UsersManual.md} (100%)
diff --git a/clang/docs/HIPSupport.rst b/clang/docs/HIPSupport.md
similarity index 100%
rename from clang/docs/HIPSupport.rst
rename to clang/docs/HIPSupport.md
diff --git a/clang/docs/HLSL/HLSLDocs.rst b/clang/docs/HLSL/HLSLDocs.md
similarity index 100%
rename from clang/docs/HLSL/HLSLDocs.rst
rename to clang/docs/HLSL/HLSLDocs.md
diff --git a/clang/docs/InternalsManual.rst b/clang/docs/InternalsManual.rst
index a09e23063858c..27adfae06416d 100644
--- a/clang/docs/InternalsManual.rst
+++ b/clang/docs/InternalsManual.rst
@@ -692,7 +692,7 @@ deterministic manner. This enables features such as implicitly discovered,
explicitly built modules.
..
- TODO: Create and link corresponding section in Modules.rst.
+ TODO: Create and link corresponding section in Modules.md.
Adding new Command Line Option
------------------------------
diff --git a/clang/docs/LTOVisibility.rst b/clang/docs/LTOVisibility.md
similarity index 100%
rename from clang/docs/LTOVisibility.rst
rename to clang/docs/LTOVisibility.md
diff --git a/clang/docs/MSVCCompatibility.rst b/clang/docs/MSVCCompatibility.md
similarity index 100%
rename from clang/docs/MSVCCompatibility.rst
rename to clang/docs/MSVCCompatibility.md
diff --git a/clang/docs/MisExpect.rst b/clang/docs/MisExpect.md
similarity index 100%
rename from clang/docs/MisExpect.rst
rename to clang/docs/MisExpect.md
diff --git a/clang/docs/Modules.rst b/clang/docs/Modules.md
similarity index 100%
rename from clang/docs/Modules.rst
rename to clang/docs/Modules.md
diff --git a/clang/docs/OpenCLSupport.rst b/clang/docs/OpenCLSupport.md
similarity index 100%
rename from clang/docs/OpenCLSupport.rst
rename to clang/docs/OpenCLSupport.md
diff --git a/clang/docs/OpenMPSupport.rst b/clang/docs/OpenMPSupport.md
similarity index 100%
rename from clang/docs/OpenMPSupport.rst
rename to clang/docs/OpenMPSupport.md
diff --git a/clang/docs/OverflowBehaviorTypes.rst b/clang/docs/OverflowBehaviorTypes.md
similarity index 100%
rename from clang/docs/OverflowBehaviorTypes.rst
rename to clang/docs/OverflowBehaviorTypes.md
diff --git a/clang/docs/PointerAuthentication.rst b/clang/docs/PointerAuthentication.md
similarity index 100%
rename from clang/docs/PointerAuthentication.rst
rename to clang/docs/PointerAuthentication.md
diff --git a/clang/docs/SYCLSupport.rst b/clang/docs/SYCLSupport.md
similarity index 100%
rename from clang/docs/SYCLSupport.rst
rename to clang/docs/SYCLSupport.md
diff --git a/clang/docs/SafeStack.rst b/clang/docs/SafeStack.md
similarity index 100%
rename from clang/docs/SafeStack.rst
rename to clang/docs/SafeStack.md
diff --git a/clang/docs/SanitizerSpecialCaseList.rst b/clang/docs/SanitizerSpecialCaseList.md
similarity index 100%
rename from clang/docs/SanitizerSpecialCaseList.rst
rename to clang/docs/SanitizerSpecialCaseList.md
diff --git a/clang/docs/SanitizerStats.rst b/clang/docs/SanitizerStats.md
similarity index 100%
rename from clang/docs/SanitizerStats.rst
rename to clang/docs/SanitizerStats.md
diff --git a/clang/docs/ShadowCallStack.rst b/clang/docs/ShadowCallStack.md
similarity index 100%
rename from clang/docs/ShadowCallStack.rst
rename to clang/docs/ShadowCallStack.md
diff --git a/clang/docs/SourceBasedCodeCoverage.rst b/clang/docs/SourceBasedCodeCoverage.md
similarity index 100%
rename from clang/docs/SourceBasedCodeCoverage.rst
rename to clang/docs/SourceBasedCodeCoverage.md
diff --git a/clang/docs/StandardCPlusPlusModules.rst b/clang/docs/StandardCPlusPlusModules.md
similarity index 100%
rename from clang/docs/StandardCPlusPlusModules.rst
rename to clang/docs/StandardCPlusPlusModules.md
diff --git a/clang/docs/StructureProtection.rst b/clang/docs/StructureProtection.md
similarity index 100%
rename from clang/docs/StructureProtection.rst
rename to clang/docs/StructureProtection.md
diff --git a/clang/docs/ThinLTO.rst b/clang/docs/ThinLTO.md
similarity index 100%
rename from clang/docs/ThinLTO.rst
rename to clang/docs/ThinLTO.md
diff --git a/clang/docs/UsersManual.rst b/clang/docs/UsersManual.md
similarity index 100%
rename from clang/docs/UsersManual.rst
rename to clang/docs/UsersManual.md
diff --git a/clang/lib/CodeGen/CodeGenModule.cpp b/clang/lib/CodeGen/CodeGenModule.cpp
index e155fdd752d7f..8e75ac4dd650f 100644
--- a/clang/lib/CodeGen/CodeGenModule.cpp
+++ b/clang/lib/CodeGen/CodeGenModule.cpp
@@ -5109,7 +5109,7 @@ void CodeGenModule::emitMultiVersionFunctions() {
}
// Symbols with this prefix are used as deactivation symbols for PFP fields.
-// See clang/docs/StructureProtection.rst for more information.
+// See clang/docs/StructureProtection.md for more information.
static const char PFPDeactivationSymbolPrefix[] = "__pfp_ds_";
llvm::GlobalValue *
diff --git a/clang/lib/Driver/ToolChains/MSVC.cpp b/clang/lib/Driver/ToolChains/MSVC.cpp
index fd3c225d27f03..2b428c56ed1be 100644
--- a/clang/lib/Driver/ToolChains/MSVC.cpp
+++ b/clang/lib/Driver/ToolChains/MSVC.cpp
@@ -944,7 +944,7 @@ VersionTuple MSVCToolChain::computeMSVCVersion(const Driver *D,
IsWindowsMSVC)) {
// -fms-compatibility-version=19.33 is default, aka 2022, 17.3
// NOTE: when changing this value, also update
- // clang/docs/CommandGuide/clang.rst and clang/docs/UsersManual.rst
+ // clang/docs/CommandGuide/clang.rst and clang/docs/UsersManual.md
// accordingly.
MSVT = VersionTuple(19, 33);
}
diff --git a/clang/test/CodeGen/ubsan-type-ignorelist-category.test b/clang/test/CodeGen/ubsan-type-ignorelist-category.test
index 70a89d3e31249..480279c7c32bc 100644
--- a/clang/test/CodeGen/ubsan-type-ignorelist-category.test
+++ b/clang/test/CodeGen/ubsan-type-ignorelist-category.test
@@ -101,7 +101,7 @@ void ignore_all_except_myty_divrem(int A, int B, myty C, myty D) {
(void)(A%B);
}
-// Matches the example from clang/docs/SanitizerSpecialCaseList.rst
+// Matches the example from clang/docs/SanitizerSpecialCaseList.md
typedef char T;
typedef char U;
// TRUNC2-LABEL: docs_example
@@ -113,4 +113,3 @@ void docs_example(int toobig) {
// TRUNC2-NOT: %handler.implicit_conversion
char c = toobig;
}
-
>From 2a0213fd5e509bf9496b66c84dee20e7a53ae218 Mon Sep 17 00:00:00 2001
From: Reid Kleckner <rkleckner at nvidia.com>
Date: Wed, 8 Jul 2026 18:53:31 +0000
Subject: [PATCH 2/5] [docs] Convert selected rst docs with rst2myst
---
clang/docs/HIPSupport.md | 1015 +++--
clang/docs/HLSL/HLSLDocs.md | 31 +-
clang/docs/LTOVisibility.md | 97 +-
clang/docs/MSVCCompatibility.md | 338 +-
clang/docs/MisExpect.md | 59 +-
clang/docs/Modules.md | 1012 ++---
clang/docs/OpenCLSupport.md | 326 +-
clang/docs/OpenMPSupport.md | 875 ++--
clang/docs/OverflowBehaviorTypes.md | 813 ++--
clang/docs/PointerAuthentication.md | 1308 +++---
clang/docs/SYCLSupport.md | 106 +-
clang/docs/SafeStack.md | 148 +-
clang/docs/SanitizerSpecialCaseList.md | 419 +-
clang/docs/SanitizerStats.md | 72 +-
clang/docs/ShadowCallStack.md | 210 +-
clang/docs/SourceBasedCodeCoverage.md | 475 +--
clang/docs/StandardCPlusPlusModules.md | 3119 +++++++-------
clang/docs/StructureProtection.md | 78 +-
clang/docs/ThinLTO.md | 252 +-
clang/docs/UsersManual.md | 5138 ++++++++++++------------
20 files changed, 7695 insertions(+), 8196 deletions(-)
diff --git a/clang/docs/HIPSupport.md b/clang/docs/HIPSupport.md
index 5fde8a92289c6..e2b81227e7846 100644
--- a/clang/docs/HIPSupport.md
+++ b/clang/docs/HIPSupport.md
@@ -1,122 +1,122 @@
-.. raw:: html
-
- <style type="text/css">
- .none { background-color: #FFCCCC }
- .part { background-color: #FFFF99 }
- .good { background-color: #CCFF99 }
- </style>
-
+```{raw} html
+<style type="text/css">
+ .none { background-color: #FFCCCC }
+ .part { background-color: #FFFF99 }
+ .good { background-color: #CCFF99 }
+</style>
+```
+
+```{eval-rst}
.. role:: none
+```
+
+```{eval-rst}
.. role:: part
+```
+
+```{eval-rst}
.. role:: good
+```
-.. contents::
- :local:
+```{contents}
+:local: true
+```
-=============
-HIP Support
-=============
+# HIP Support
-HIP (Heterogeneous-Compute Interface for Portability) `<https://github.com/ROCm/HIP>`_ is
+HIP (Heterogeneous-Compute Interface for Portability) [https://github.com/ROCm/HIP](https://github.com/ROCm/HIP) is
a C++ Runtime API and Kernel Language. It enables developers to create portable applications for
offloading computation to different hardware platforms from a single source code.
-AMD GPU Support
-===============
+## AMD GPU Support
-Clang provides HIP support on AMD GPUs via the ROCm platform `<https://rocm.docs.amd.com/en/latest/#>`_.
+Clang provides HIP support on AMD GPUs via the ROCm platform [https://rocm.docs.amd.com/en/latest/#](https://rocm.docs.amd.com/en/latest/#).
The ROCm runtime forms the base for HIP host APIs, while HIP device APIs are realized through HIP header
files and the ROCm device library. The Clang driver uses the HIPAMD toolchain to compile HIP device code
to AMDGPU ISA via the AMDGPU backend, or SPIR-V via the workflow outlined below.
The compiled code is then bundled and embedded in the host executables.
-Intel GPU Support
-=================
+## Intel GPU Support
-Clang provides partial HIP support on Intel GPUs using the CHIP-Star project `<https://github.com/CHIP-SPV/chipStar>`_.
+Clang provides partial HIP support on Intel GPUs using the CHIP-Star project [https://github.com/CHIP-SPV/chipStar](https://github.com/CHIP-SPV/chipStar).
CHIP-Star implements the HIP runtime over oneAPI Level Zero or OpenCL runtime. The Clang driver uses the HIPSPV
toolchain to compile HIP device code into LLVM IR, which is subsequently translated to SPIR-V via the SPIR-V
backend or the out-of-tree LLVM-SPIRV translator. The SPIR-V is then bundled and embedded into the host executables.
-.. note::
- While Clang does not directly provide HIP support for NVIDIA GPUs and CPUs, these platforms are supported via other means:
+:::{note}
+While Clang does not directly provide HIP support for NVIDIA GPUs and CPUs, these platforms are supported via other means:
- - NVIDIA GPUs: HIP support is offered through the HIP project `<https://github.com/ROCm/HIP>`_, which provides a header-only library for translating HIP runtime APIs into CUDA runtime APIs. The code is subsequently compiled using NVIDIA's `nvcc`.
+- NVIDIA GPUs: HIP support is offered through the HIP project [https://github.com/ROCm/HIP](https://github.com/ROCm/HIP), which provides a header-only library for translating HIP runtime APIs into CUDA runtime APIs. The code is subsequently compiled using NVIDIA's `nvcc`.
+- CPUs: HIP support is available through the HIP-CPU runtime library [https://github.com/ROCm/HIP-CPU](https://github.com/ROCm/HIP-CPU). This header-only library enables CPUs to execute unmodified HIP code.
+:::
- - CPUs: HIP support is available through the HIP-CPU runtime library `<https://github.com/ROCm/HIP-CPU>`_. This header-only library enables CPUs to execute unmodified HIP code.
-
-
-Example Usage
-=============
+## Example Usage
To compile a HIP program, use the following command:
-.. code-block:: shell
+```shell
+clang++ -c --offload-arch=gfx906 -xhip sample.cpp -o sample.o
+```
- clang++ -c --offload-arch=gfx906 -xhip sample.cpp -o sample.o
-
-The ``-xhip`` option indicates that the source is a HIP program. If the file has a ``.hip`` extension,
+The `-xhip` option indicates that the source is a HIP program. If the file has a `.hip` extension,
Clang will automatically recognize it as a HIP program:
-.. code-block:: shell
-
- clang++ -c --offload-arch=gfx906 sample.hip -o sample.o
+```shell
+clang++ -c --offload-arch=gfx906 sample.hip -o sample.o
+```
To link a HIP program, use this command:
-.. code-block:: shell
+```shell
+clang++ --hip-link --offload-arch=gfx906 sample.o -o sample
+```
- clang++ --hip-link --offload-arch=gfx906 sample.o -o sample
-
-In the above command, the ``--hip-link`` flag instructs Clang to link the HIP runtime library. However,
+In the above command, the `--hip-link` flag instructs Clang to link the HIP runtime library. However,
the use of this flag is unnecessary if a HIP input file is already present in your program.
For convenience, Clang also supports compiling and linking in a single step:
-.. code-block:: shell
-
- clang++ --offload-arch=gfx906 -xhip sample.cpp -o sample
-
-In the above commands, ``gfx906`` is the GPU architecture that the code is being compiled for. The supported GPU
-architectures can be found in the `AMDGPU Processor Table <https://llvm.org/docs/AMDGPUUsage.html#processors>`_.
-Alternatively, you can use the ``amdgpu-arch`` tool that comes with Clang to list the GPU architecture on your system:
-
-.. code-block:: shell
+```shell
+clang++ --offload-arch=gfx906 -xhip sample.cpp -o sample
+```
- amdgpu-arch
+In the above commands, `gfx906` is the GPU architecture that the code is being compiled for. The supported GPU
+architectures can be found in the [AMDGPU Processor Table](https://llvm.org/docs/AMDGPUUsage.html#processors).
+Alternatively, you can use the `amdgpu-arch` tool that comes with Clang to list the GPU architecture on your system:
-You can use ``--offload-arch=native`` to automatically detect the GPU architectures on your system:
+```shell
+amdgpu-arch
+```
-.. code-block:: shell
+You can use `--offload-arch=native` to automatically detect the GPU architectures on your system:
- clang++ --offload-arch=native -xhip sample.cpp -o sample
+```shell
+clang++ --offload-arch=native -xhip sample.cpp -o sample
+```
-
-Path Setting for Dependencies
-=============================
+## Path Setting for Dependencies
Compiling a HIP program depends on the HIP runtime and device library. The paths to the HIP runtime and device libraries
can be specified either using compiler options or environment variables. The paths can also be set through the ROCm path
if they follow the ROCm installation directory structure.
-Order of Precedence for HIP Path
---------------------------------
+### Order of Precedence for HIP Path
-1. ``--hip-path`` compiler option
-2. ``HIP_PATH`` environment variable *(use with caution)*
-3. ``--rocm-path`` compiler option
-4. ``ROCM_PATH`` environment variable *(use with caution)*
+1. `--hip-path` compiler option
+2. `HIP_PATH` environment variable *(use with caution)*
+3. `--rocm-path` compiler option
+4. `ROCM_PATH` environment variable *(use with caution)*
5. Default automatic detection (relative to Clang or at the default ROCm installation location)
-Order of Precedence for Device Library Path
--------------------------------------------
+### Order of Precedence for Device Library Path
-1. ``--hip-device-lib-path`` compiler option
-2. ``HIP_DEVICE_LIB_PATH`` environment variable *(use with caution)*
-3. ``--rocm-path`` compiler option
-4. ``ROCM_PATH`` environment variable *(use with caution)*
+1. `--hip-device-lib-path` compiler option
+2. `HIP_DEVICE_LIB_PATH` environment variable *(use with caution)*
+3. `--rocm-path` compiler option
+4. `ROCM_PATH` environment variable *(use with caution)*
5. Default automatic detection (relative to Clang or at the default ROCm installation location)
+```{eval-rst}
.. list-table::
:header-rows: 1
@@ -136,15 +136,15 @@ Order of Precedence for Device Library Path
- ``HIP_DEVICE_LIB_PATH``
- Specifies the HIP device library installation path.
- Determined by ROCm directory structure
+```
-.. note::
-
- We recommend using the compiler options as the primary method for specifying these paths. While the environment variables ``ROCM_PATH``, ``HIP_PATH``, and ``HIP_DEVICE_LIB_PATH`` are supported, their use can lead to implicit dependencies that might cause issues in the long run. Use them with caution.
-
+:::{note}
+We recommend using the compiler options as the primary method for specifying these paths. While the environment variables `ROCM_PATH`, `HIP_PATH`, and `HIP_DEVICE_LIB_PATH` are supported, their use can lead to implicit dependencies that might cause issues in the long run. Use them with caution.
+:::
-Predefined Macros
-=================
+## Predefined Macros
+```{eval-rst}
.. list-table::
:header-rows: 1
@@ -178,31 +178,29 @@ Predefined Macros
- Defined when the GPU default stream is set to per-thread mode.
* - ``HIP_API_PER_THREAD_DEFAULT_STREAM``
- Alias to ``__HIP_API_PER_THREAD_DEFAULT_STREAM__``. Deprecated.
+```
Note that some architecture specific AMDGPU macros will have default values when
used from the HIP host compilation.
-Compilation Modes
-=================
+## Compilation Modes
-Each HIP source file contains intertwined device and host code. Depending on the chosen compilation mode by the compiler options ``-fno-gpu-rdc`` and ``-fgpu-rdc``, these portions of code are compiled differently.
+Each HIP source file contains intertwined device and host code. Depending on the chosen compilation mode by the compiler options `-fno-gpu-rdc` and `-fgpu-rdc`, these portions of code are compiled differently.
-Device Code Compilation
------------------------
+### Device Code Compilation
-**``-fno-gpu-rdc`` Mode (default)**:
+**\`\`-fno-gpu-rdc\`\` Mode (default)**:
- Compiles to a self-contained, fully linked offloading device binary for each offloading device architecture.
- Device code within a Translation Unit (TU) cannot call functions located in another TU.
-**``-fgpu-rdc`` Mode**:
+**\`\`-fgpu-rdc\`\` Mode**:
- Compiles to a bitcode for each GPU architecture.
- For each offloading device architecture, the bitcode from different TUs are linked together to create a single offloading device binary.
- Device code in one TU can call functions located in another TU.
-Host Code Compilation
----------------------
+### Host Code Compilation
**Both Modes**:
@@ -210,17 +208,16 @@ Host Code Compilation
- These relocatable objects are then linked together.
- Host code within a TU can call host functions and launch kernels from another TU.
-HIP Fat Binary Registration and Unregistration
-==============================================
+## HIP Fat Binary Registration and Unregistration
When compiling HIP for AMD GPUs, Clang embeds device code into HIP "fat
binaries" and generates host-side helper functions that register these
fat binaries with the HIP runtime at program start and unregister them at
-program exit. In non-RDC mode (``-fno-gpu-rdc``), each compilation unit
+program exit. In non-RDC mode (`-fno-gpu-rdc`), each compilation unit
typically produces its own HIP fat binary: a container that holds, for every
enabled GPU architecture, a fully linked offloading device image (for example,
a GPU code object) that can be loaded directly by the HIP runtime. In RDC mode
-(``-fgpu-rdc``), each compilation unit contributes device code in a relocatable
+(`-fgpu-rdc`), each compilation unit contributes device code in a relocatable
form (for example, GPU object files or LLVM IR). A later device-link step links
those relocatable inputs into fully linked device images per GPU architecture
and then packages those images into a HIP fat binary container.
@@ -233,30 +230,30 @@ established during registration (and the fat binary handle it returned) to
identify which GPU kernel symbol to launch from which device image.
At the LLVM IR level, Clang/LLVM typically create an internal module
-constructor (for example ``__hip_module_ctor`` or a ``.hip.fatbin_reg``
-function) and add it to ``@llvm.global_ctors``. This constructor is called by
-the C runtime before ``main`` and it:
+constructor (for example `__hip_module_ctor` or a `.hip.fatbin_reg`
+function) and add it to `@llvm.global_ctors`. This constructor is called by
+the C runtime before `main` and it:
-* calls ``__hipRegisterFatBinary`` with a pointer to an internal wrapper
+- calls `__hipRegisterFatBinary` with a pointer to an internal wrapper
object that describes the HIP fat binary;
-* stores the returned handle in an internal global variable;
-* calls an internal helper such as ``__hip_register_globals`` to register
+- stores the returned handle in an internal global variable;
+- calls an internal helper such as `__hip_register_globals` to register
kernels, device variables and other metadata associated with the fat binary;
-* registers a corresponding module destructor with ``atexit`` so it will run
+- registers a corresponding module destructor with `atexit` so it will run
during program termination and use the stored handle to unregister the fat
binary from the HIP runtime.
-The compiler-generated wrapper object is placed in the ``.hipFatBinSegment``
+The compiler-generated wrapper object is placed in the `.hipFatBinSegment`
section. Its layout is:
-.. code-block:: c++
-
- struct {
- uint32_t magic;
- uint32_t version;
- void *image;
- void *reserved;
- };
+```c++
+struct {
+ uint32_t magic;
+ uint32_t version;
+ void *image;
+ void *reserved;
+};
+```
The section is an internal ABI between Clang-generated host objects, the HIP
runtime, and binary tools that need to find HIP fat binaries. Consumers may
@@ -264,78 +261,73 @@ walk the raw section contents as a packed array of wrapper records, so compiler
and instrumentation passes must preserve the wrapper object layout in the
section.
-The module destructor (for example ``__hip_module_dtor`` or a
-``.hip.fatbin_unreg`` function) loads the stored handle, checks that it is
-non-null, calls ``__hipUnregisterFatBinary`` to unregister the fat binary from
+The module destructor (for example `__hip_module_dtor` or a
+`.hip.fatbin_unreg` function) loads the stored handle, checks that it is
+non-null, calls `__hipUnregisterFatBinary` to unregister the fat binary from
the HIP runtime, and then clears the handle. This ensures that the HIP runtime
sees each fat binary registered exactly once and that it is unregistered once
at exit, even when multiple translation units contribute HIP kernels to the
same host program.
These registration/unregistration helpers are implementation details of Clang's
-HIP code generation; user code should not call ``__hipRegisterFatBinary`` or
-``__hipUnregisterFatBinary`` directly.
+HIP code generation; user code should not call `__hipRegisterFatBinary` or
+`__hipUnregisterFatBinary` directly.
-Implications for HIP Application Developers
--------------------------------------------
+### Implications for HIP Application Developers
From the point of view of HIP application code, Clang and the HIP runtime
provide the following guarantees:
-* Kernels and device variables defined in HIP code will be registered with the
- HIP runtime before ``main`` begins execution.
-* Fat binaries will be unregistered via an ``atexit``-registered module
- destructor after ``main`` returns (or after ``exit`` is called).
+- Kernels and device variables defined in HIP code will be registered with the
+ HIP runtime before `main` begins execution.
+- Fat binaries will be unregistered via an `atexit`-registered module
+ destructor after `main` returns (or after `exit` is called).
Beyond these points, the detailed ordering of fat binary registration and
unregistration relative to user-defined global constructors, destructors and
-other ``atexit`` handlers is not specified and should not be relied upon.
+other `atexit` handlers is not specified and should not be relied upon.
Applications should avoid depending on HIP kernels or device variables being
usable from global constructors or destructors, and instead perform HIP
-initialization and teardown that touches device state in ``main`` (or in
-functions called from ``main``).
+initialization and teardown that touches device state in `main` (or in
+functions called from `main`).
-Implications for HIP Runtime Developers
----------------------------------------
+### Implications for HIP Runtime Developers
HIP runtime implementations that are linked with Clang-generated host code
must handle registration and unregistration in the presence of uncertain
global ctor/dtor ordering:
-* ``__hipRegisterFatBinary`` must accept a pointer to the compiler-generated
+- `__hipRegisterFatBinary` must accept a pointer to the compiler-generated
wrapper object and return an opaque handle that remains valid for as long as
the fat binary may be used.
-* ``__hipUnregisterFatBinary`` must accept the handle previously returned by
- ``__hipRegisterFatBinary`` and perform any necessary cleanup. It may be
+- `__hipUnregisterFatBinary` must accept the handle previously returned by
+ `__hipRegisterFatBinary` and perform any necessary cleanup. It may be
called late in process teardown, after other parts of the runtime have
started shutting down, so it should be robust in the presence of partially
torn-down state.
-* Runtimes should use appropriate synchronization and guards so that fat
+- Runtimes should use appropriate synchronization and guards so that fat
binary registration does not observe uninitialized resources and
unregistration does not release resources that are still required by other
runtime components. In particular, registration and unregistration routines
should be written to be safe under repeated calls and in the presence of
concurrent or overlapping initialization/teardown logic.
-Syntax Difference with CUDA
-===========================
+## Syntax Difference with CUDA
-Clang's front end, used for both CUDA and HIP programming models, shares the same parsing and semantic analysis mechanisms. This includes the resolution of overloads concerning device and host functions. While there exists a comprehensive documentation on the syntax differences between Clang and NVCC for CUDA at `Dialect Differences Between Clang and NVCC <https://llvm.org/docs/CompileCudaWithLLVM.html#dialect-differences-between-clang-and-nvcc>`_, it is important to note that these differences also apply to HIP code compilation.
+Clang's front end, used for both CUDA and HIP programming models, shares the same parsing and semantic analysis mechanisms. This includes the resolution of overloads concerning device and host functions. While there exists a comprehensive documentation on the syntax differences between Clang and NVCC for CUDA at [Dialect Differences Between Clang and NVCC](https://llvm.org/docs/CompileCudaWithLLVM.html#dialect-differences-between-clang-and-nvcc), it is important to note that these differences also apply to HIP code compilation.
-Predefined Macros for Differentiation
--------------------------------------
+### Predefined Macros for Differentiation
To facilitate differentiation between HIP and CUDA code, as well as between device and host compilations within HIP, Clang defines specific macros:
-- ``__HIP__`` : This macro is defined only when compiling HIP code. It can be used to conditionally compile code specific to HIP, enabling developers to write portable code that can be compiled for both CUDA and HIP.
-
-- ``__HIP_DEVICE_COMPILE__`` : Defined exclusively during HIP device compilation, this macro allows for conditional compilation of device-specific code. It provides a mechanism to segregate device and host code, ensuring that each can be optimized for their respective execution environments.
+- `__HIP__` : This macro is defined only when compiling HIP code. It can be used to conditionally compile code specific to HIP, enabling developers to write portable code that can be compiled for both CUDA and HIP.
+- `__HIP_DEVICE_COMPILE__` : Defined exclusively during HIP device compilation, this macro allows for conditional compilation of device-specific code. It provides a mechanism to segregate device and host code, ensuring that each can be optimized for their respective execution environments.
-Function Pointers Support
-=========================
+## Function Pointers Support
Function pointers' support varies with the usage mode in Clang with HIP. The following table provides an overview of the support status across different use-cases and modes.
+```{eval-rst}
.. list-table:: Function Pointers Support Overview
:widths: 25 25 25
:header-rows: 1
@@ -349,13 +341,13 @@ Function pointers' support varies with the usage mode in Clang with HIP. The fol
* - Defined in one TU and used in another TU
- Not Supported
- Supported
+```
-In the ``-fno-gpu-rdc`` mode, the compiler calculates the resource usage of kernels based only on functions present within the same TU. This mode does not support the use of function pointers defined in a different TU due to the possibility of incorrect resource usage calculations, leading to undefined behavior.
+In the `-fno-gpu-rdc` mode, the compiler calculates the resource usage of kernels based only on functions present within the same TU. This mode does not support the use of function pointers defined in a different TU due to the possibility of incorrect resource usage calculations, leading to undefined behavior.
-On the other hand, the ``-fgpu-rdc`` mode allows the definition and use of function pointers across different TUs, as resource usage calculations can accommodate functions from disparate TUs.
+On the other hand, the `-fgpu-rdc` mode allows the definition and use of function pointers across different TUs, as resource usage calculations can accommodate functions from disparate TUs.
-Virtual Function Support
-========================
+## Virtual Function Support
In Clang with HIP, support for calling virtual functions of an object in device or host code is contingent on where the object is constructed.
@@ -364,126 +356,119 @@ In Clang with HIP, support for calling virtual functions of an object in device
In other scenarios, calling virtual functions is not allowed.
-Explanation
------------
+### Explanation
An object constructed on the device side contains a pointer to the virtual function table on the device side, which is not accessible in host code, and vice versa. Thus, trying to invoke virtual functions from a context different from where the object was constructed will be disallowed because the appropriate virtual table cannot be accessed. The virtual function tables for offloading devices with different architectures are different, therefore trying to invoke virtual functions from an offloading device with a different architecture than where the object is constructed is also disallowed.
-Example Usage
--------------
-
-.. code-block:: c++
-
- class Base {
- public:
- __device__ virtual void virtualFunction() {
- // Base virtual function implementation
- }
- };
-
- class Derived : public Base {
- public:
- __device__ void virtualFunction() override {
- // Derived virtual function implementation
- }
- };
-
- __global__ void kernel() {
- Derived obj;
- Base* basePtr = &obj;
- basePtr->virtualFunction(); // Allowed since obj is constructed in device code
- }
-
-Alias Attribute Support
-=======================
-
-Clang supports alias attributes in HIP code, allowing creation of alternative names for functions and variables.
- - Aliases work with ``__host__``, ``__device__``, and ``__host__ __device__`` functions and variables.
- - The alias attribute uses the syntax ``__attribute__((alias("target_name")))``. Both weak and strong aliases are supported.
- - Outside of ``extern "C"``, the alias target must use the mangled name of the aliasee
- - The alias is only emitted if the aliasee is emitted on the same side (ie __host__ or __device__), otherwise it is ignored.
-
-Example Usage
--------------
-
-.. code-block:: c++
-
- extern "C" {
- // Host function alias
- int __HostFunc(void) { return 0; }
- int HostFunc(void) __attribute__((weak, alias("__HostFunc")));
+### Example Usage
- // Device function alias
- __device__ int __DeviceFunc(void) { return 1; }
- __device__ int DeviceFunc(void) __attribute__((weak, alias("__DeviceFunc")));
-
- // Host-device function alias
- __host__ __device__ int __BothFunc(void) { return 2; }
- __host__ __device__ int BothFunc(void) __attribute__((alias("__BothFunc")));
-
- // Variable alias
- int __host_var = 3;
- extern int __attribute__((weak, alias("__host_var"))) host_var;
+```c++
+class Base {
+public:
+ __device__ virtual void virtualFunction() {
+ // Base virtual function implementation
}
- // Mangled / overload alias
- __host__ __device__ float __Four(float f) { return 2.0f * f; }
- __host__ __device__ int Four(void) __attribute__((weak, alias("_Z6__Fourv")));
- __host__ __device__ float Four(float f) __attribute__((weak, alias("_Z6__Fourf")));
+};
-C++17 Class Template Argument Deduction (CTAD) Support
-======================================================
+class Derived : public Base {
+public:
+ __device__ void virtualFunction() override {
+ // Derived virtual function implementation
+ }
+};
+
+__global__ void kernel() {
+ Derived obj;
+ Base* basePtr = &obj;
+ basePtr->virtualFunction(); // Allowed since obj is constructed in device code
+}
+```
+
+## Alias Attribute Support
+
+Clang supports alias attributes in HIP code, allowing creation of alternative names for functions and variables.
+: - Aliases work with `__host__`, `__device__`, and `__host__ __device__` functions and variables.
+ - The alias attribute uses the syntax `__attribute__((alias("target_name")))`. Both weak and strong aliases are supported.
+ - Outside of `extern "C"`, the alias target must use the mangled name of the aliasee
+ - The alias is only emitted if the aliasee is emitted on the same side (ie \_\_host\_\_ or \_\_device\_\_), otherwise it is ignored.
+
+### Example Usage
+
+```c++
+extern "C" {
+ // Host function alias
+ int __HostFunc(void) { return 0; }
+ int HostFunc(void) __attribute__((weak, alias("__HostFunc")));
+
+ // Device function alias
+ __device__ int __DeviceFunc(void) { return 1; }
+ __device__ int DeviceFunc(void) __attribute__((weak, alias("__DeviceFunc")));
+
+ // Host-device function alias
+ __host__ __device__ int __BothFunc(void) { return 2; }
+ __host__ __device__ int BothFunc(void) __attribute__((alias("__BothFunc")));
+
+ // Variable alias
+ int __host_var = 3;
+ extern int __attribute__((weak, alias("__host_var"))) host_var;
+}
+// Mangled / overload alias
+__host__ __device__ float __Four(float f) { return 2.0f * f; }
+__host__ __device__ int Four(void) __attribute__((weak, alias("_Z6__Fourv")));
+__host__ __device__ float Four(float f) __attribute__((weak, alias("_Z6__Fourf")));
+```
+
+## C++17 Class Template Argument Deduction (CTAD) Support
Clang supports C++17 Class Template Argument Deduction (CTAD) in both host and
device code for HIP. This allows you to omit template arguments when creating
class template instances, letting the compiler deduce them from constructor
arguments.
-.. code-block:: c++
+```c++
+#include <tuple>
- #include <tuple>
+__host__ __device__ void func() {
+ std::tuple<int, int> t = std::tuple(1, 1);
+}
+```
- __host__ __device__ void func() {
- std::tuple<int, int> t = std::tuple(1, 1);
- }
+In the above example, `std::tuple(1, 1)` automatically deduces the type to be
+`std::tuple<int, int>`.
-In the above example, ``std::tuple(1, 1)`` automatically deduces the type to be
-``std::tuple<int, int>``.
-
-Deduction Guides
-----------------
+### Deduction Guides
User-defined deduction guides are also supported. Since deduction guides are not
executable code and only participate in type deduction, they semantically behave
-as ``__host__ __device__``. This ensures they are available for deduction in both
+as `__host__ __device__`. This ensures they are available for deduction in both
host and device contexts, and CTAD continues to respect any constraints on the
corresponding constructors in the usual C++ way.
-.. code-block:: c++
-
- template <typename T>
- struct MyType {
- T value;
- __device__ MyType(T v) : value(v) {}
- };
+```c++
+template <typename T>
+struct MyType {
+ T value;
+ __device__ MyType(T v) : value(v) {}
+};
- MyType(float) -> MyType<double>;
+MyType(float) -> MyType<double>;
- __device__ void deviceFunc() {
- MyType m(1.0f); // Deduces MyType<double>
- }
+__device__ void deviceFunc() {
+ MyType m(1.0f); // Deduces MyType<double>
+}
+```
-.. note::
+:::{note}
+Explicit HIP target attributes such as `__host__` or `__device__`
+are currently only permitted on deduction guides when both are present
+(`__host__ __device__`). This usage is deprecated and will be rejected
+in a future version of Clang; prefer omitting HIP target attributes on
+deduction guides entirely. Clang treats all deduction guides as if they
+were `__host__ __device__`, so `__host__`-only, `__device__`-only,
+or `__global__` deduction guides are rejected as ill-formed.
+:::
- Explicit HIP target attributes such as ``__host__`` or ``__device__``
- are currently only permitted on deduction guides when both are present
- (``__host__ __device__``). This usage is deprecated and will be rejected
- in a future version of Clang; prefer omitting HIP target attributes on
- deduction guides entirely. Clang treats all deduction guides as if they
- were ``__host__ __device__``, so ``__host__``-only, ``__device__``-only,
- or ``__global__`` deduction guides are rejected as ill-formed.
-
-Host and Device Attributes of Default Destructors
-===================================================
+## Host and Device Attributes of Default Destructors
If a default destructor does not have explicit host or device attributes,
clang infers these attributes based on the destructors of its data members
@@ -502,113 +487,106 @@ non-constexpr function, which is by default a host function.
Users can override the inferred host and device attributes of default
destructors by adding explicit host and device attributes to them.
-Deferred Diagnostics
-====================
+## Deferred Diagnostics
-In HIP (and CUDA), a ``__host__ __device__`` function can be called from both
+In HIP (and CUDA), a `__host__ __device__` function can be called from both
host and device code. Certain operations may not be valid on one side (e.g.,
calling a host-only function from device code, or referencing a device-only
-function from host code). However, a ``__host__ __device__`` function
+function from host code). However, a `__host__ __device__` function
containing such operations is only ill-formed if the function is actually
reachable from a caller where the operation cannot be emitted.
Clang handles this through *deferred diagnostics*: errors and warnings in
-``__host__ __device__`` functions are recorded during parsing but not emitted
+`__host__ __device__` functions are recorded during parsing but not emitted
immediately. They are only emitted when a function whose linkage guarantees
-IR emission (e.g., a kernel, or an externally visible ``__host__`` or
-``__device__`` function) directly or indirectly calls the
-``__host__ __device__`` function containing the invalid operation.
+IR emission (e.g., a kernel, or an externally visible `__host__` or
+`__device__` function) directly or indirectly calls the
+`__host__ __device__` function containing the invalid operation.
-HD-Promoted Functions
----------------------
+### HD-Promoted Functions
An *HD-promoted function* is a function that is implicitly or explicitly
-``__host__ __device__`` and is only emitted because a caller requires it —
+`__host__ __device__` and is only emitted because a caller requires it —
it does not have standalone linkage that guarantees emission. HD-promoted
functions are the primary source of deferred diagnostics.
Common examples of HD-promoted functions:
-- Lambdas without explicit ``__host__`` or ``__device__`` attributes
-- ``inline __host__ __device__`` helper functions
-- ``__host__ __device__`` template instantiations
+- Lambdas without explicit `__host__` or `__device__` attributes
+- `inline __host__ __device__` helper functions
+- `__host__ __device__` template instantiations
When an HD-promoted function contains operations that are not valid on the
caller's side, clang emits the deferred diagnostics along with notes showing
how the function was reached.
-Example
-^^^^^^^
-
-.. code-block:: c++
+#### Example
- __host__ void host_only();
+```c++
+__host__ void host_only();
- // This lambda is implicitly __host__ __device__. It is HD-promoted
- // when called from a __device__ function.
- __device__ auto lambda = [] {
- host_only(); // error: only emitted if lambda is used from device code
- };
+// This lambda is implicitly __host__ __device__. It is HD-promoted
+// when called from a __device__ function.
+__device__ auto lambda = [] {
+ host_only(); // error: only emitted if lambda is used from device code
+};
- __device__ void df1() {
- lambda(); // triggers deferred diagnostic for lambda
- }
+__device__ void df1() {
+ lambda(); // triggers deferred diagnostic for lambda
+}
- __device__ void df2() {
- lambda(); // same lambda, same error — not duplicated
- }
+__device__ void df2() {
+ lambda(); // same lambda, same error — not duplicated
+}
+```
Clang emits the error once and lists all device callers:
-.. code-block:: text
+```text
+error: reference to __host__ function 'host_only' in __host__ __device__ function
+ note: 'host_only' declared here
+ note: called by 'df1'
+ note: called by 'df2'
+```
- error: reference to __host__ function 'host_only' in __host__ __device__ function
- note: 'host_only' declared here
- note: called by 'df1'
- note: called by 'df2'
-
-Call Chain Notes
-^^^^^^^^^^^^^^^^
+#### Call Chain Notes
When an HD-promoted function is reached through a chain of intermediate
functions, clang shows the full call chain. The first note in each chain uses
"called by" and subsequent notes use "which is called by":
-.. code-block:: text
-
- error: reference to __host__ function 'host_only' in __host__ __device__ function
- note: called by 'helper1'
- note: which is called by 'device_func1'
- note: called by 'helper2'
- note: which is called by 'device_func2'
+```text
+error: reference to __host__ function 'host_only' in __host__ __device__ function
+ note: called by 'helper1'
+ note: which is called by 'device_func1'
+ note: called by 'helper2'
+ note: which is called by 'device_func2'
+```
Each "called by" starts a new chain, and "which is called by" continues it.
This makes it clear which device function ultimately forced the code into
device context.
-C++ Standard Parallelism Offload Support: Compiler And Runtime
-==============================================================
+## C++ Standard Parallelism Offload Support: Compiler And Runtime
-Introduction
-============
+## Introduction
This section describes the implementation of support for offloading the
execution of standard C++ algorithms to accelerators that can be targeted via
HIP. Furthermore, it enumerates restrictions on user defined code, as well as
the interactions with runtimes.
-Algorithm Offload: What, Why, Where
-===================================
+## Algorithm Offload: What, Why, Where
C++17 introduced overloads
-`for most algorithms in the standard library <https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2016/p0024r2.html>`_
+[for most algorithms in the standard library](https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2016/p0024r2.html)
which allow the user to specify a desired
-`execution policy <https://en.cppreference.com/w/cpp/algorithm#Execution_policies>`_.
-The `parallel_unsequenced_policy <https://en.cppreference.com/w/cpp/algorithm/execution_policy_tag_t>`_
+[execution policy](https://en.cppreference.com/w/cpp/algorithm#Execution_policies).
+The [parallel_unsequenced_policy](https://en.cppreference.com/w/cpp/algorithm/execution_policy_tag_t)
maps relatively well to the execution model of AMD GPUs. This, coupled with the
the availability and maturity of GPU accelerated algorithm libraries that
implement most / all corresponding algorithms in the standard library
-(e.g. `rocThrust <https://github.com/ROCm/rocm-libraries/tree/develop/projects/rocthrust>`__), makes
+(e.g. [rocThrust](https://github.com/ROCm/rocm-libraries/tree/develop/projects/rocthrust)), makes
it feasible to provide seamless accelerator offload for supported algorithms,
when an accelerated version exists. Thus, it becomes possible to easily access
the computational resources of an AMD accelerator, via a well specified,
@@ -616,116 +594,115 @@ familiar, algorithmic interface, without having to delve into low-level hardware
specific details. Putting it all together:
- **What**: standard library algorithms, when invoked with the
- ``parallel_unsequenced_policy``
+ `parallel_unsequenced_policy`
- **Why**: democratise AMDGPU accelerator programming, without loss of user
familiarity
- **Where**: only AMDGPU accelerators targeted by Clang/LLVM via HIP
-Small Example
-=============
+## Small Example
Given the following C++ code:
-.. code-block:: C++
-
- bool has_the_answer(const std::vector<int>& v) {
- return std::find(std::execution::par_unseq, std::cbegin(v), std::cend(v), 42) != std::cend(v);
- }
+```C++
+bool has_the_answer(const std::vector<int>& v) {
+ return std::find(std::execution::par_unseq, std::cbegin(v), std::cend(v), 42) != std::cend(v);
+}
+```
-if Clang is invoked with the ``--hipstdpar --offload-arch=foo`` flags, the call
-to ``find`` will be offloaded to an accelerator that is part of the ``foo``
-target family. If either ``foo`` or its runtime environment do not support
+if Clang is invoked with the `--hipstdpar --offload-arch=foo` flags, the call
+to `find` will be offloaded to an accelerator that is part of the `foo`
+target family. If either `foo` or its runtime environment do not support
transparent on-demand paging (such as e.g. that provided in Linux via
-`HMM <https://docs.kernel.org/mm/hmm.html>`_), it is necessary to also include
-the ``--hipstdpar-interpose-alloc`` flag. If the accelerator specific algorithm
-library ``foo`` uses doesn't have an implementation of a particular algorithm,
+[HMM](https://docs.kernel.org/mm/hmm.html)), it is necessary to also include
+the `--hipstdpar-interpose-alloc` flag. If the accelerator specific algorithm
+library `foo` uses doesn't have an implementation of a particular algorithm,
execution seamlessly falls back to the host CPU. It is legal to specify multiple
-``--offload-arch``\s. All the flags we introduce, as well as a thorough view of
+`--offload-arch`s. All the flags we introduce, as well as a thorough view of
various restrictions an their implementations, will be provided below.
-Implementation - General View
-=============================
+## Implementation - General View
We built support for Algorithm Offload support atop the pre-existing HIP
-infrastructure. More specifically, when one requests offload via ``--hipstdpar``,
-compilation is switched to HIP compilation, as if ``-x hip`` was specified.
-Similarly, linking is also switched to HIP linking, as if ``--hip-link`` was
+infrastructure. More specifically, when one requests offload via `--hipstdpar`,
+compilation is switched to HIP compilation, as if `-x hip` was specified.
+Similarly, linking is also switched to HIP linking, as if `--hip-link` was
specified. Note that these are implicit, and one should not assume that any
-interop with HIP specific language constructs is available e.g. ``__device__``
+interop with HIP specific language constructs is available e.g. `__device__`
annotations are neither necessary nor guaranteed to work.
Since there are no language restriction mechanisms in place, it is necessary to
relax HIP language specific semantic checks performed by the FE; they would
identify otherwise valid, offloadable code, as invalid HIP code. Given that we
know that the user intended only for certain algorithms to be offloaded, and
-encoded this by specifying the ``parallel_unsequenced_policy``, we rely on a
+encoded this by specifying the `parallel_unsequenced_policy`, we rely on a
pass over IR to clean up any and all code that was not "meant" for offload. If
requested, allocation interposition is also handled via a separate pass over IR.
To interface with the client HIP runtime, and to forward offloaded algorithm
invocations to the corresponding accelerator specific library implementation, an
implementation detail forwarding header is implicitly included by the driver,
-when compiling with ``--hipstdpar``. In what follows, we will delve into each
+when compiling with `--hipstdpar`. In what follows, we will delve into each
component that contributes to implementing Algorithm Offload support.
-Implementation - Driver
-=======================
+## Implementation - Driver
-We augment the ``clang`` driver with the following flags:
+We augment the `clang` driver with the following flags:
-- ``--hipstdpar`` enables algorithm offload, which depending on phase, has the
+- `--hipstdpar` enables algorithm offload, which depending on phase, has the
following effects:
- when compiling:
- - ``-x hip`` gets prepended to enable HIP support;
- - the ``ROCmToolchain`` component checks for the ``hipstdpar_lib.hpp``
+ - `-x hip` gets prepended to enable HIP support;
+ - the `ROCmToolchain` component checks for the `hipstdpar_lib.hpp`
forwarding header,
- `rocThrust <https://rocm.docs.amd.com/projects/rocThrust/en/latest/>`_ and
- `rocPrim <https://rocm.docs.amd.com/projects/rocPRIM/en/latest/>`_ in
+ [rocThrust](https://rocm.docs.amd.com/projects/rocThrust/en/latest/) and
+ [rocPrim](https://rocm.docs.amd.com/projects/rocPRIM/en/latest/) in
their canonical locations, which can be overriden via flags found below;
if all are found, the forwarding header gets implicitly included,
otherwise an error listing the missing component is generated;
- - the ``LangOpts.HIPStdPar`` member is set.
+ - the `LangOpts.HIPStdPar` member is set.
- when linking:
- - ``--hip-link`` and ``-frtlib-add-rpath`` gets appended to enable HIP
+ - `--hip-link` and `-frtlib-add-rpath` gets appended to enable HIP
support.
-- ``--hipstdpar-interpose-alloc`` enables the interposition of standard
+- `--hipstdpar-interpose-alloc` enables the interposition of standard
allocation / deallocation functions with accelerator aware equivalents; the
- ``LangOpts.HIPStdParInterposeAlloc`` member is set;
-- ``--hipstdpar-path=`` specifies a non-canonical path for the forwarding
+ `LangOpts.HIPStdParInterposeAlloc` member is set;
+
+- `--hipstdpar-path=` specifies a non-canonical path for the forwarding
header; it must point to the folder where the header is located and not to the
header itself;
-- ``--hipstdpar-thrust-path=`` specifies a non-canonical path for
- `rocThrust <https://rocm.docs.amd.com/projects/rocThrust/en/latest/>`_; it
+
+- `--hipstdpar-thrust-path=` specifies a non-canonical path for
+ [rocThrust](https://rocm.docs.amd.com/projects/rocThrust/en/latest/); it
must point to the folder where the library is installed / built under a
- ``/thrust`` subfolder;
-- ``--hipstdpar-prim-path=`` specifies a non-canonical path for
- `rocPrim <https://rocm.docs.amd.com/projects/rocPRIM/en/latest/>`_; it must
+ `/thrust` subfolder;
+
+- `--hipstdpar-prim-path=` specifies a non-canonical path for
+ [rocPrim](https://rocm.docs.amd.com/projects/rocPRIM/en/latest/); it must
point to the folder where the library is installed / built under a
- ``/rocprim`` subfolder;
+ `/rocprim` subfolder;
-The `--offload-arch <https://llvm.org/docs/AMDGPUUsage.html#amdgpu-processors>`_
+The [--offload-arch](https://llvm.org/docs/AMDGPUUsage.html#amdgpu-processors)
flag can be used to specify the accelerator for which offload code is to be
generated.
-Implementation - Front-End
-==========================
+## Implementation - Front-End
-When ``LangOpts.HIPStdPar`` is set, we relax some of the HIP language specific
-``Sema`` checks to account for the fact that we want to consume pure unannotated
+When `LangOpts.HIPStdPar` is set, we relax some of the HIP language specific
+`Sema` checks to account for the fact that we want to consume pure unannotated
C++ code:
-1. ``__device__`` / ``__host__ __device__`` functions (which would originate in
+1. `__device__` / `__host__ __device__` functions (which would originate in
the accelerator specific algorithm library) are allowed to call implicitly
- ``__host__`` functions;
-2. ``__global__`` functions (which would originate in the accelerator specific
- algorithm library) are allowed to call implicitly ``__host__`` functions;
-3. resolving ``__builtin`` availability is deferred, because it is possible that
- a ``__builtin`` that is unavailable on the target accelerator is not
+ `__host__` functions;
+2. `__global__` functions (which would originate in the accelerator specific
+ algorithm library) are allowed to call implicitly `__host__` functions;
+3. resolving `__builtin` availability is deferred, because it is possible that
+ a `__builtin` that is unavailable on the target accelerator is not
reachable from any offloaded algorithm, and thus will be safely removed in
the middle-end;
4. ASM parsing / checking is deferred, because it is possible that an ASM block
@@ -733,19 +710,18 @@ C++ code:
accelerator is not reachable from any offloaded algorithm, and thus will be
safely removed in the middle-end.
-``CodeGen`` is similarly relaxed, with implicitly ``__host__`` functions being
+`CodeGen` is similarly relaxed, with implicitly `__host__` functions being
emitted as well.
-Implementation - Middle-End
-===========================
+## Implementation - Middle-End
-We add two ``opt`` passes:
+We add two `opt` passes:
-1. ``HipStdParAcceleratorCodeSelectionPass``
+1. `HipStdParAcceleratorCodeSelectionPass`
- - For all kernels in a ``Module``, compute reachability, where a function
- ``F`` is reachable from a kernel ``K`` if and only if there exists a direct
- call-chain rooted in ``F`` that includes ``K``;
+ - For all kernels in a `Module`, compute reachability, where a function
+ `F` is reachable from a kernel `K` if and only if there exists a direct
+ call-chain rooted in `F` that includes `K`;
- Remove all functions that are not reachable from kernels;
- This pass is only run when compiling for the accelerator.
@@ -757,19 +733,18 @@ effectively constitute the only roots for accelerator execution graphs. Both of
these assumptions are based on observing how widespread accelerators,
such as GPUs, work.
-1. ``HipStdParAllocationInterpositionPass``
+1. `HipStdParAllocationInterpositionPass`
- - Iterate through all functions in a ``Module``, and replace standard
+ - Iterate through all functions in a `Module`, and replace standard
allocation / deallocation functions with accelerator-aware equivalents,
based on a pre-established table; the list of functions that can be
interposed is available
- `here <https://github.com/ROCm/roc-stdpar#allocation--deallocation-interposition-status>`__;
+ [here](https://github.com/ROCm/roc-stdpar#allocation--deallocation-interposition-status);
- This is only run when compiling for the host.
The second pass is optional.
-Implementation - Forwarding Header
-==================================
+## Implementation - Forwarding Header
The forwarding header implements two pieces of functionality:
@@ -777,19 +752,19 @@ The forwarding header implements two pieces of functionality:
C++ language rules around overloading:
- overloads taking an explicit argument of type
- ``parallel_unsequenced_policy`` are introduced into the ``std`` namespace;
+ `parallel_unsequenced_policy` are introduced into the `std` namespace;
- these will get preferentially selected versus the master template;
- the body forwards to the equivalent algorithm from the accelerator specific
library
2. It provides allocation / deallocation functions that are equivalent to the
standard ones, but obtain memory by invoking
- `hipMallocManaged <https://rocm.docs.amd.com/projects/HIP/en/latest/.doxygen/docBin/html/group___memory_m.html#gab8cfa0e292193fa37e0cc2e4911fa90a>`_
- and release it via `hipFree <https://rocm.docs.amd.com/projects/HIP/en/latest/.doxygen/docBin/html/group___memory.html#ga740d08da65cae1441ba32f8fedb863d1>`_.
+ [hipMallocManaged](https://rocm.docs.amd.com/projects/HIP/en/latest/.doxygen/docBin/html/group___memory_m.html#gab8cfa0e292193fa37e0cc2e4911fa90a)
+ and release it via [hipFree](https://rocm.docs.amd.com/projects/HIP/en/latest/.doxygen/docBin/html/group___memory.html#ga740d08da65cae1441ba32f8fedb863d1).
-Predefined Macros
-=================
+## Predefined Macros
+```{eval-rst}
.. list-table::
:header-rows: 1
@@ -804,16 +779,16 @@ Predefined Macros
compiler option, indicating that all dynamic memory allocation /
deallocation functions should be replaced with accelerator aware
variants.
+```
-Restrictions
-============
+## Restrictions
We define two modes in which runtime execution can occur:
1. **HMM Mode** - this assumes that the
- `HMM <https://docs.kernel.org/mm/hmm.html>`_ subsystem of the Linux kernel
+ [HMM](https://docs.kernel.org/mm/hmm.html) subsystem of the Linux kernel
is used to provide transparent on-demand paging i.e. memory obtained from a
- system / OS allocator such as via a call to ``malloc`` or ``operator new`` is
+ system / OS allocator such as via a call to `malloc` or `operator new` is
directly accessible to the accelerator and it follows the C++ memory model;
2. **Interposition Mode** - this is a fallback mode for cases where transparent
on-demand paging is unavailable (e.g. in the Windows OS), which means that
@@ -825,39 +800,39 @@ The following restrictions imposed on user code apply to both modes:
1. Pointers to function, and all associated features, such as e.g. dynamic
polymorphism, cannot be used (directly or transitively) by the user provided
callable passed to an algorithm invocation;
-2. ``static`` (except for program-wide unique ones) / ``thread`` storage
+2. `static` (except for program-wide unique ones) / `thread` storage
duration variables cannot be used (directly or transitively) in name by the
user provided callable;
-3. User code must be compiled in ``-fgpu-rdc`` mode in order for global /
- namespace scope variables / program-wide unique ``static`` storage duration
+3. User code must be compiled in `-fgpu-rdc` mode in order for global /
+ namespace scope variables / program-wide unique `static` storage duration
variables to be usable in name by the user provided callable;
-4. Only algorithms that are invoked with the ``parallel_unsequenced_policy`` are
+4. Only algorithms that are invoked with the `parallel_unsequenced_policy` are
candidates for offload;
5. Only algorithms that are invoked with iterator arguments that model
- `random_access_iterator <https://en.cppreference.com/w/cpp/iterator/random_access_iterator>`_
+ [random_access_iterator](https://en.cppreference.com/w/cpp/iterator/random_access_iterator)
are candidates for offload;
-6. `Exceptions <https://en.cppreference.com/w/cpp/language/exceptions>`_ cannot
+6. [Exceptions](https://en.cppreference.com/w/cpp/language/exceptions) cannot
be used by the user provided callable;
-7. Dynamic memory allocation (e.g. ``operator new``) cannot be used by the user
+7. Dynamic memory allocation (e.g. `operator new`) cannot be used by the user
provided callable;
8. Selective offload is not possible i.e. it is not possible to indicate that
- only some algorithms invoked with the ``parallel_unsequenced_policy`` are to
+ only some algorithms invoked with the `parallel_unsequenced_policy` are to
be executed on the accelerator.
In addition to the above, using **Interposition Mode** imposes the following
additional restrictions:
1. All code that is expected to interoperate has to be recompiled with the
- ``--hipstdpar-interpose-alloc`` flag i.e. it is not safe to compose libraries
+ `--hipstdpar-interpose-alloc` flag i.e. it is not safe to compose libraries
that have been independently compiled;
-Current Support
-===============
+## Current Support
At the moment, C++ Standard Parallelism Offload is only available for AMD GPUs,
-when the `ROCm <https://rocm.docs.amd.com/en/latest/>`_ stack is used, on the
+when the [ROCm](https://rocm.docs.amd.com/en/latest/) stack is used, on the
Linux operating system. Support is synthesised in the following table:
+```{eval-rst}
.. list-table::
:header-rows: 1
@@ -879,21 +854,21 @@ Linux operating system. Support is synthesised in the following table:
* - GCN GFX12 (RDNA 4)
- *NO*
- YES
+```
The minimum Linux kernel version for running in HMM mode is 6.4.
The forwarding header is packaged by
-`ROCm <https://rocm.docs.amd.com/en/latest/>`_, and is obtainable by installing
+[ROCm](https://rocm.docs.amd.com/en/latest/), and is obtainable by installing
the `hipstdpar` packege. The list algorithms that can be offloaded is available
-`here <https://github.com/ROCm/roc-stdpar#algorithm-support-status>`_. More
+[here](https://github.com/ROCm/roc-stdpar#algorithm-support-status). More
details are available via the dedicated blog
-`<https://rocm.blogs.amd.com/software-tools-optimization/hipstdpar/README.html>`_.
+[https://rocm.blogs.amd.com/software-tools-optimization/hipstdpar/README.html](https://rocm.blogs.amd.com/software-tools-optimization/hipstdpar/README.html).
-HIP Specific Elements
----------------------
+### HIP Specific Elements
1. There is no defined interop with the
- `HIP kernel language <https://rocm.docs.amd.com/projects/HIP/en/latest/reference/kernel_language.html>`_;
+ [HIP kernel language](https://rocm.docs.amd.com/projects/HIP/en/latest/reference/kernel_language.html);
whilst things like using `__device__` annotations might accidentally "work",
they are not guaranteed to, and thus cannot be relied upon by user code;
@@ -903,266 +878,252 @@ HIP Specific Elements
in the future.
2. Combining explicit HIP, CUDA or OpenMP Offload compilation with
- ``--hipstdpar`` based offloading is not allowed or supported in any way.
+ `--hipstdpar` based offloading is not allowed or supported in any way.
+
3. There is no way to target different accelerators via a standard algorithm
- invocation (`this might be addressed in future C++ standards <https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2023/p2500r1.html>`_);
+ invocation ([this might be addressed in future C++ standards](https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2023/p2500r1.html));
an unsafe (per the point above) way of achieving this is to spawn new threads
- and invoke the `hipSetDevice <https://rocm.docs.amd.com/projects/HIP/en/latest/.doxygen/docBin/html/group___device.html#ga43c1e7f15925eeb762195ccb5e063eae>`_
+ and invoke the [hipSetDevice](https://rocm.docs.amd.com/projects/HIP/en/latest/.doxygen/docBin/html/group___device.html#ga43c1e7f15925eeb762195ccb5e063eae)
interface e.g.:
- .. code-block:: c++
+ ```c++
+ int accelerator_0 = ...;
+ int accelerator_1 = ...;
- int accelerator_0 = ...;
- int accelerator_1 = ...;
+ bool multiple_accelerators(const std::vector<int>& u, const std::vector<int>& v) {
+ std::atomic<unsigned int> r{0u};
- bool multiple_accelerators(const std::vector<int>& u, const std::vector<int>& v) {
- std::atomic<unsigned int> r{0u};
+ thread t0{[&]() {
+ hipSetDevice(accelerator_0);
- thread t0{[&]() {
- hipSetDevice(accelerator_0);
+ r += std::count(std::execution::par_unseq, std::cbegin(u), std::cend(u), 42);
+ }};
+ thread t1{[&]() {
+ hitSetDevice(accelerator_1);
- r += std::count(std::execution::par_unseq, std::cbegin(u), std::cend(u), 42);
- }};
- thread t1{[&]() {
- hitSetDevice(accelerator_1);
+ r += std::count(std::execution::par_unseq, std::cbegin(v), std::cend(v), 314152)
+ }};
- r += std::count(std::execution::par_unseq, std::cbegin(v), std::cend(v), 314152)
- }};
+ t0.join();
+ t1.join();
- t0.join();
- t1.join();
-
- return r;
- }
+ return r;
+ }
+ ```
Note that this is a temporary, unsafe workaround for a deficiency in the C++
Standard.
-Open Questions / Future Developments
-====================================
+## Open Questions / Future Developments
-1. The restriction on the use of ``static`` / ``thread`` storage duration
+1. The restriction on the use of `static` / `thread` storage duration
variables in offloaded algorithms might be lifted;
2. The restriction on the use of dynamic memory allocation in offloaded
algorithms will be lifted in the future.
3. The restriction on the use of pointers to function, and associated features
such as dynamic polymorphism might be lifted in the future, when running in
**HMM Mode**;
-4. Offload support might be extended to cases where the ``parallel_policy`` is
+4. Offload support might be extended to cases where the `parallel_policy` is
used for some or all targets.
-Profile-Guided Optimization for Device Code
-===========================================
+## Profile-Guided Optimization for Device Code
Clang supports IR-level profile-guided optimization (PGO) for HIP device
-code on AMD GPUs. ``-fprofile-generate`` instruments both host and
+code on AMD GPUs. `-fprofile-generate` instruments both host and
device code; running the instrumented binary writes separate host and
device raw profiles, which are merged independently and consumed by a
second build that passes the appropriate profile to each side.
-Prerequisites
--------------
+### Prerequisites
The toolchain must be built with the AMDGPU profile runtime enabled,
-which requires building ``compiler-rt`` for the ``amdgcn-amd-amdhsa``
+which requires building `compiler-rt` for the `amdgcn-amd-amdhsa`
target via the runtimes build. A minimal CMake configuration is:
-.. code-block:: console
-
- $ cmake <llvm-project>/llvm \
- -DLLVM_ENABLE_PROJECTS='clang;lld' \
- -DLLVM_ENABLE_RUNTIMES=compiler-rt \
- -DLLVM_RUNTIME_TARGETS='default;amdgcn-amd-amdhsa' \
- -DRUNTIMES_amdgcn-amd-amdhsa_CACHE_FILES=<llvm-project>/compiler-rt/cmake/caches/AMDGPU.cmake \
- -DRUNTIMES_amdgcn-amd-amdhsa_LLVM_ENABLE_RUNTIMES='compiler-rt;libc' \
- -DRUNTIMES_amdgcn-amd-amdhsa_RUNTIMES_USE_LIBC=llvm-libc
-
-``COMPILER_RT_BUILD_PROFILE_ROCM`` controls building the host-side
-ROCm/HIP device profile collection runtime, ``clang_rt.profile_rocm``.
+```console
+$ cmake <llvm-project>/llvm \
+ -DLLVM_ENABLE_PROJECTS='clang;lld' \
+ -DLLVM_ENABLE_RUNTIMES=compiler-rt \
+ -DLLVM_RUNTIME_TARGETS='default;amdgcn-amd-amdhsa' \
+ -DRUNTIMES_amdgcn-amd-amdhsa_CACHE_FILES=<llvm-project>/compiler-rt/cmake/caches/AMDGPU.cmake \
+ -DRUNTIMES_amdgcn-amd-amdhsa_LLVM_ENABLE_RUNTIMES='compiler-rt;libc' \
+ -DRUNTIMES_amdgcn-amd-amdhsa_RUNTIMES_USE_LIBC=llvm-libc
+```
+
+`COMPILER_RT_BUILD_PROFILE_ROCM` controls building the host-side
+ROCm/HIP device profile collection runtime, `clang_rt.profile_rocm`.
It is on by default for normal Linux and Windows compiler-rt builds,
and off for bare-metal profile builds; leave it enabled.
-``RUNTIMES_USE_LIBC=llvm-libc`` is required so the amdgcn profile
-compile picks up LLVM-libc's ``-isystem`` / ``-nostdlibinc`` headers.
+`RUNTIMES_USE_LIBC=llvm-libc` is required so the amdgcn profile
+compile picks up LLVM-libc's `-isystem` / `-nostdlibinc` headers.
-Generate phase
---------------
+### Generate phase
-The driver forwards ``-fprofile-generate`` to the device compiler and
+The driver forwards `-fprofile-generate` to the device compiler and
links the device profile runtime into the embedded device image.
-.. code-block:: console
-
- $ clang++ -x hip demo.hip \
- --offload-arch=gfx1100 --offload-arch=gfx1101 \
- -fprofile-generate=pgo_data \
- -o demo.instr
+```console
+$ clang++ -x hip demo.hip \
+ --offload-arch=gfx1100 --offload-arch=gfx1101 \
+ -fprofile-generate=pgo_data \
+ -o demo.instr
- $ ./demo.instr
+$ ./demo.instr
+```
When the instrumented binary exits, the runtime writes raw profile
-files into ``pgo_data/``. Host profiles use the standard LLVM profile
+files into `pgo_data/`. Host profiles use the standard LLVM profile
filename; device profiles use the same filename with the GPU
architecture name prepended to the basename, so each
-``--offload-arch=`` value produces its own set of device files. The
-usual ``LLVM_PROFILE_FILE`` substitutions (``%p`` for process ID,
-``%m`` for binary signature, etc.) apply to both, so multi-process
+`--offload-arch=` value produces its own set of device files. The
+usual `LLVM_PROFILE_FILE` substitutions (`%p` for process ID,
+`%m` for binary signature, etc.) apply to both, so multi-process
runs do not need a separate device-side naming scheme.
Merge the host profile and each device architecture's profile
separately:
-.. code-block:: console
+```console
+$ llvm-profdata merge -o host.profdata pgo_data/default_*.profraw
+$ llvm-profdata merge -o device.gfx1100.profdata pgo_data/gfx1100*.profraw
+$ llvm-profdata merge -o device.gfx1101.profdata pgo_data/gfx1101*.profraw
+```
- $ llvm-profdata merge -o host.profdata pgo_data/default_*.profraw
- $ llvm-profdata merge -o device.gfx1100.profdata pgo_data/gfx1100*.profraw
- $ llvm-profdata merge -o device.gfx1101.profdata pgo_data/gfx1101*.profraw
-
-Use phase
----------
+### Use phase
Host and device compilations consume different profiles, and each GPU
-architecture consumes its own. ``-Xarch_host`` selects the host
-profile and ``-Xarch_<gpu-arch>`` selects the per-architecture device
+architecture consumes its own. `-Xarch_host` selects the host
+profile and `-Xarch_<gpu-arch>` selects the per-architecture device
profile:
-.. code-block:: console
-
- $ clang++ -x hip demo.hip \
- --offload-arch=gfx1100 --offload-arch=gfx1101 \
- -Xarch_host -fprofile-use=host.profdata \
- -Xarch_gfx1100 -fprofile-use=device.gfx1100.profdata \
- -Xarch_gfx1101 -fprofile-use=device.gfx1101.profdata \
- -o demo
+```console
+$ clang++ -x hip demo.hip \
+ --offload-arch=gfx1100 --offload-arch=gfx1101 \
+ -Xarch_host -fprofile-use=host.profdata \
+ -Xarch_gfx1100 -fprofile-use=device.gfx1100.profdata \
+ -Xarch_gfx1101 -fprofile-use=device.gfx1101.profdata \
+ -o demo
+```
-For a single-arch build, ``-Xarch_device`` is a convenient shorthand
+For a single-arch build, `-Xarch_device` is a convenient shorthand
that applies the same profile to every offload architecture:
-.. code-block:: console
+```console
+$ clang++ -x hip demo.hip --offload-arch=gfx1101 \
+ -Xarch_host -fprofile-use=host.profdata \
+ -Xarch_device -fprofile-use=device.gfx1101.profdata \
+ -o demo
+```
- $ clang++ -x hip demo.hip --offload-arch=gfx1101 \
- -Xarch_host -fprofile-use=host.profdata \
- -Xarch_device -fprofile-use=device.gfx1101.profdata \
- -o demo
-
-Block uniformity profiles
--------------------------
+### Block uniformity profiles
On AMDGPU targets, device PGO also records a per-block uniformity
signal. For each instrumented block, the profile records whether the
block is usually entered with all lanes in the wave active. During the
use phase, Clang attaches this information to the corresponding IR
-terminators as ``!block.uniformity.profile`` metadata, which lets later
+terminators as `!block.uniformity.profile` metadata, which lets later
AMDGPU code generation distinguish blocks that are usually uniform from
blocks that are divergent.
No extra driver option is needed; use the same generate, merge, and use
-commands shown above. ``llvm-profdata show --counts`` prints the
+commands shown above. `llvm-profdata show --counts` prints the
uniformity information when it is present:
-.. code-block:: text
-
- Block uniformity: [U, U, D, U]
+```text
+Block uniformity: [U, U, D, U]
+```
-``U`` means the block was classified as uniform, and ``D`` means it was
+`U` means the block was classified as uniform, and `D` means it was
classified as divergent. Profiles produced by older toolchains or by
targets that do not emit this data can still be used for ordinary PGO,
but they do not provide block-uniformity guidance.
-Notes
------
+### Notes
- The instrumented build is slower than a normal build; only the use
phase produces the optimized binary intended for deployment.
-- Set ``LLVM_PROFILE_VERBOSE=1`` to print runtime diagnostics for
+- Set `LLVM_PROFILE_VERBOSE=1` to print runtime diagnostics for
profile file creation and device profile collection.
-Source-Based Code Coverage for Device Code
-==========================================
+## Source-Based Code Coverage for Device Code
Clang supports source-based code coverage for HIP device code on AMD GPUs.
-Device code is instrumented with the same ``-fprofile-instr-generate
--fcoverage-mapping`` flags used for host code; counters live in the device
-binary, are written to a ``.profraw`` file at process exit, and can be
-consumed by ``llvm-profdata`` and ``llvm-cov``.
+Device code is instrumented with the same `-fprofile-instr-generate
+-fcoverage-mapping` flags used for host code; counters live in the device
+binary, are written to a `.profraw` file at process exit, and can be
+consumed by `llvm-profdata` and `llvm-cov`.
-Prerequisites
--------------
+### Prerequisites
Source-based device coverage relies on the AMDGPU profile runtime, so
the toolchain must be built with the same CMake configuration used for
HIP offload PGO. See the *Prerequisites* subsection under
-`Profile-Guided Optimization for Device Code`_.
+[Profile-Guided Optimization for Device Code].
-Example
--------
+### Example
-Given a HIP program ``demo.hip``, the following commands produce an LCOV
+Given a HIP program `demo.hip`, the following commands produce an LCOV
report covering device code:
-.. code-block:: console
-
- $ clang++ -x hip demo.hip \
- --offload-arch=gfx1101 \
- -fprofile-instr-generate -fcoverage-mapping \
- -o demo
-
- $ llvm-objcopy --dump-section=.hip_fatbin=fatbin.bin demo
- $ clang-offload-bundler --type=o --input=fatbin.bin \
- --output=device.gfx1101.o \
- --targets=hip-amdgcn-amd-amdhsa--gfx1101 --unbundle
-
- $ LLVM_PROFILE_FILE="cov.%p.profraw" ./demo
- $ llvm-profdata merge -sparse -o cov.profdata cov.*.profraw
-
- $ llvm-cov report device.gfx1101.o -instr-profile=cov.profdata
- $ llvm-cov show device.gfx1101.o -instr-profile=cov.profdata
- $ llvm-cov export device.gfx1101.o -instr-profile=cov.profdata \
- -format=lcov > coverage.lcov
-
-The device ELF is extracted from the ``.hip_fatbin`` section of the host
-binary and then unbundled with ``clang-offload-bundler``. The unbundle
-target string uses the bundle ID ``hip-amdgcn-amd-amdhsa--<arch>``,
-which is the offload kind (``hip``) followed by the standard
-four-component target triple (``amdgcn-amd-amdhsa-``, with the empty
+```console
+$ clang++ -x hip demo.hip \
+ --offload-arch=gfx1101 \
+ -fprofile-instr-generate -fcoverage-mapping \
+ -o demo
+
+$ llvm-objcopy --dump-section=.hip_fatbin=fatbin.bin demo
+$ clang-offload-bundler --type=o --input=fatbin.bin \
+ --output=device.gfx1101.o \
+ --targets=hip-amdgcn-amd-amdhsa--gfx1101 --unbundle
+
+$ LLVM_PROFILE_FILE="cov.%p.profraw" ./demo
+$ llvm-profdata merge -sparse -o cov.profdata cov.*.profraw
+
+$ llvm-cov report device.gfx1101.o -instr-profile=cov.profdata
+$ llvm-cov show device.gfx1101.o -instr-profile=cov.profdata
+$ llvm-cov export device.gfx1101.o -instr-profile=cov.profdata \
+ -format=lcov > coverage.lcov
+```
+
+The device ELF is extracted from the `.hip_fatbin` section of the host
+binary and then unbundled with `clang-offload-bundler`. The unbundle
+target string uses the bundle ID `hip-amdgcn-amd-amdhsa--<arch>`,
+which is the offload kind (`hip`) followed by the standard
+four-component target triple (`amdgcn-amd-amdhsa-`, with the empty
environment field giving the trailing dash) and then the target ID
-(``<arch>``). See :doc:`ClangOffloadBundler` for the full bundle entry
-ID grammar. ``llvm-cov`` is invoked against the device object because
+(`<arch>`). See {doc}`ClangOffloadBundler` for the full bundle entry
+ID grammar. `llvm-cov` is invoked against the device object because
the coverage mapping for device functions is emitted there.
-SPIR-V Support on HIPAMD ToolChain
-==================================
+## SPIR-V Support on HIPAMD ToolChain
The HIPAMD ToolChain supports targeting
-`AMDGCN Flavoured SPIR-V <https://llvm.org/docs/SPIRVUsage.html#target-triples>`_.
+[AMDGCN Flavoured SPIR-V](https://llvm.org/docs/SPIRVUsage.html#target-triples).
The support for SPIR-V in the ROCm and HIPAMD ToolChain is under active
development.
-Compilation Process
--------------------
+### Compilation Process
When compiling HIP programs with the intent of utilizing SPIR-V, the process
diverges from the traditional compilation flow:
-Using ``--offload-arch=amdgcnspirv``
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+#### Using `--offload-arch=amdgcnspirv`
-- **Target Triple**: The ``--offload-arch=amdgcnspirv`` flag instructs the
- compiler to use the target triple ``spirv64-amd-amdhsa``. This approach does
+- **Target Triple**: The `--offload-arch=amdgcnspirv` flag instructs the
+ compiler to use the target triple `spirv64-amd-amdhsa`. This approach does
generates generic AMDGCN SPIR-V which retains architecture specific elements
without hardcoding them, thus allowing for optimal target specific code to be
generated at run time, when the concrete target is known.
-
- **LLVM IR Translation**: The program is compiled to LLVM Intermediate
Representation (IR), which is subsequently translated into SPIR-V. In the
future, this translation step will be replaced by direct SPIR-V emission via
the SPIR-V Back-end.
-
- **Clang Offload Bundler**: The resulting SPIR-V is embedded in the Clang
- offload bundler with the bundle ID ``hip-spirv64-amd-amdhsa--amdgcnspirv``.
+ offload bundler with the bundle ID `hip-spirv64-amd-amdhsa--amdgcnspirv`.
-Architecture Specific Macros
-----------------------------
+### Architecture Specific Macros
-None of the architecture specific :doc:`AMDGPU macros <AMDGPUSupport>` are
+None of the architecture specific {doc}`AMDGPU macros <AMDGPUSupport>` are
defined when targeting SPIR-V. An alternative, more flexible mechanism to enable
doing per target / per feature code selection will be added in the future.
+
diff --git a/clang/docs/HLSL/HLSLDocs.md b/clang/docs/HLSL/HLSLDocs.md
index 1e50a66d984b5..18a088e9f5639 100644
--- a/clang/docs/HLSL/HLSLDocs.md
+++ b/clang/docs/HLSL/HLSLDocs.md
@@ -1,19 +1,22 @@
-.. title:: Clang HLSL Documentation
+```{title} Clang HLSL Documentation
+```
-.. toctree::
- :maxdepth: 1
+```{toctree}
+:maxdepth: 1
- HLSLSupport
+HLSLSupport
+```
-HLSL Design and Implementation
-==============================
+# HLSL Design and Implementation
-.. toctree::
- :maxdepth: 1
+```{toctree}
+:maxdepth: 1
+
+ExpectedDifferences
+HLSLIRReference
+ResourceTypes
+EntryFunctions
+FunctionCalls
+AvailabilityDiagnostics
+```
- ExpectedDifferences
- HLSLIRReference
- ResourceTypes
- EntryFunctions
- FunctionCalls
- AvailabilityDiagnostics
diff --git a/clang/docs/LTOVisibility.md b/clang/docs/LTOVisibility.md
index ebc4cc906aa6c..93a34dd61eee6 100644
--- a/clang/docs/LTOVisibility.md
+++ b/clang/docs/LTOVisibility.md
@@ -1,6 +1,4 @@
-==============
-LTO Visibility
-==============
+# LTO Visibility
*LTO visibility* is a property of an entity that specifies whether it can be
referenced from outside the current LTO unit. A *linkage unit* is a set of
@@ -10,8 +8,8 @@ using link-time optimization; in the case where LTO is not being used, the
linkage unit's LTO unit is empty. Each linkage unit has only a single LTO unit.
The LTO visibility of a class is used by the compiler to determine which
-classes the whole-program devirtualization (``-fwhole-program-vtables``) and
-control flow integrity (``-fsanitize=cfi-vcall`` and ``-fsanitize=cfi-mfcall``)
+classes the whole-program devirtualization (`-fwhole-program-vtables`) and
+control flow integrity (`-fsanitize=cfi-vcall` and `-fsanitize=cfi-mfcall`)
features apply to. These features use whole-program information, so they
require the entire class hierarchy to be visible in order to work correctly.
@@ -26,7 +24,7 @@ of its definition, so it must be consistent between translation units.
In translation units built with LTO, LTO visibility is based on the
class's symbol visibility as expressed at the source level (i.e. the
-``__attribute__((visibility("...")))`` attribute, or the ``-fvisibility=``
+`__attribute__((visibility("...")))` attribute, or the `-fvisibility=`
flag) or, on the Windows platform, the dllimport and dllexport attributes. When
targeting non-Windows platforms, classes with a visibility other than hidden
visibility receive public LTO visibility. When targeting Windows, classes
@@ -36,11 +34,11 @@ other classes receive hidden LTO visibility. Classes with internal linkage
visibility.
During the LTO link, all classes with public LTO visibility but not marked with
-``[[clang::lto_visibility_public]]`` (see below) will be refined to hidden LTO
-visibility when the ``--lto-whole-program-visibility`` lld linker option is
-applied (``-plugin-opt=whole-program-visibility`` for gold). This flag can be
+`[[clang::lto_visibility_public]]` (see below) will be refined to hidden LTO
+visibility when the `--lto-whole-program-visibility` lld linker option is
+applied (`-plugin-opt=whole-program-visibility` for gold). This flag can be
used to defer specifying whether classes have hidden LTO visibility until link
-time, to allow bitcode objects to be shared by different LTO links. Due to an
+time, to allow bitcode objects to be shared by different LTO links. Due to an
implementation limitation, symbols associated with classes with hidden LTO
visibility may still be exported from the binary when using this flag. It is
unsafe to refer to these symbols, and their visibility may be relaxed to hidden
@@ -58,7 +56,6 @@ two cases where it may wrongly infer hidden LTO visibility.
visibility class defined in both a translation unit built with LTO and
a translation unit built without LTO must be defined with public LTO
visibility in order to avoid an ODR violation.
-
2. Some ABIs provide the ability to define an abstract base class without
visibility attributes in multiple linkage units and have virtual calls
to derived classes in other linkage units work correctly. One example of
@@ -66,60 +63,60 @@ two cases where it may wrongly infer hidden LTO visibility.
used in this way must be defined with public LTO visibility.
Classes that fall into either of these categories can be marked up with the
-``[[clang::lto_visibility_public]]`` attribute. To specifically handle the
-COM case, classes with the ``__declspec(uuid())`` attribute receive public
-LTO visibility. On Windows platforms, clang-cl's ``/MT`` and ``/MTd``
+`[[clang::lto_visibility_public]]` attribute. To specifically handle the
+COM case, classes with the `__declspec(uuid())` attribute receive public
+LTO visibility. On Windows platforms, clang-cl's `/MT` and `/MTd`
flags statically link the program against a prebuilt standard library;
these flags imply public LTO visibility for every class declared in the
-``std`` and ``stdext`` namespaces.
+`std` and `stdext` namespaces.
-Example
-=======
+## Example
The following example shows how LTO visibility works in practice in several
-cases involving two linkage units, ``main`` and ``dso.so``.
-
-.. code-block:: none
-
- +-----------------------------------------------------------+ +----------------------------------------------------+
- | main (clang++ -fvisibility=hidden): | | dso.so (clang++ -fvisibility=hidden): |
- | | | |
- | +-----------------------------------------------------+ | | struct __attribute__((visibility("default"))) C { |
- | | LTO unit (clang++ -fvisibility=hidden -flto): | | | virtual void f(); |
- | | | | | } |
- | | struct A { ... }; | | | void C::f() {} |
- | | struct [[clang::lto_visibility_public]] B { ... }; | | | struct D { |
- | | struct __attribute__((visibility("default"))) C { | | | virtual void g() = 0; |
- | | virtual void f(); | | | }; |
- | | }; | | | struct E : D { |
- | | struct [[clang::lto_visibility_public]] D { | | | virtual void g() { ... } |
- | | virtual void g() = 0; | | | }; |
- | | }; | | | __attribute__((visibility("default"))) D *mkE() { |
- | | | | | return new E; |
- | +-----------------------------------------------------+ | | } |
- | | | |
- | struct B { ... }; | +----------------------------------------------------+
- | |
- +-----------------------------------------------------------+
+cases involving two linkage units, `main` and `dso.so`.
+
+```none
++-----------------------------------------------------------+ +----------------------------------------------------+
+| main (clang++ -fvisibility=hidden): | | dso.so (clang++ -fvisibility=hidden): |
+| | | |
+| +-----------------------------------------------------+ | | struct __attribute__((visibility("default"))) C { |
+| | LTO unit (clang++ -fvisibility=hidden -flto): | | | virtual void f(); |
+| | | | | } |
+| | struct A { ... }; | | | void C::f() {} |
+| | struct [[clang::lto_visibility_public]] B { ... }; | | | struct D { |
+| | struct __attribute__((visibility("default"))) C { | | | virtual void g() = 0; |
+| | virtual void f(); | | | }; |
+| | }; | | | struct E : D { |
+| | struct [[clang::lto_visibility_public]] D { | | | virtual void g() { ... } |
+| | virtual void g() = 0; | | | }; |
+| | }; | | | __attribute__((visibility("default"))) D *mkE() { |
+| | | | | return new E; |
+| +-----------------------------------------------------+ | | } |
+| | | |
+| struct B { ... }; | +----------------------------------------------------+
+| |
++-----------------------------------------------------------+
+```
We will now describe the LTO visibility of each of the classes defined in
these linkage units.
-Class ``A`` is not defined outside of ``main``'s LTO unit, so it can have
+Class `A` is not defined outside of `main`'s LTO unit, so it can have
hidden LTO visibility. This is inferred from the object file visibility
specified on the command line.
-Class ``B`` is defined in ``main``, both inside and outside its LTO unit. The
+Class `B` is defined in `main`, both inside and outside its LTO unit. The
definition outside the LTO unit has public LTO visibility, so the definition
inside the LTO unit must also have public LTO visibility in order to avoid
an ODR violation.
-Class ``C`` is defined in both ``main`` and ``dso.so`` and therefore must
-have public LTO visibility. This is correctly inferred from the ``visibility``
+Class `C` is defined in both `main` and `dso.so` and therefore must
+have public LTO visibility. This is correctly inferred from the `visibility`
attribute.
-Class ``D`` is an abstract base class with a derived class ``E`` defined
-in ``dso.so``. This is an example of the COM scenario; the definition of
-``D`` in ``main``'s LTO unit must have public LTO visibility in order to be
-compatible with the definition of ``D`` in ``dso.so``, which is observable
-by calling the function ``mkE``.
+Class `D` is an abstract base class with a derived class `E` defined
+in `dso.so`. This is an example of the COM scenario; the definition of
+`D` in `main`'s LTO unit must have public LTO visibility in order to be
+compatible with the definition of `D` in `dso.so`, which is observable
+by calling the function `mkE`.
+
diff --git a/clang/docs/MSVCCompatibility.md b/clang/docs/MSVCCompatibility.md
index 43291ce261645..86dd32f4a7267 100644
--- a/clang/docs/MSVCCompatibility.md
+++ b/clang/docs/MSVCCompatibility.md
@@ -1,286 +1,276 @@
-.. raw:: html
-
- <style type="text/css">
- .none { background-color: #FFCCCC }
- .partial { background-color: #FFFF99 }
- .good { background-color: #CCFF99 }
- </style>
-
+```{raw} html
+<style type="text/css">
+ .none { background-color: #FFCCCC }
+ .partial { background-color: #FFFF99 }
+ .good { background-color: #CCFF99 }
+</style>
+```
+
+```{eval-rst}
.. role:: none
+```
+
+```{eval-rst}
.. role:: partial
+```
+
+```{eval-rst}
.. role:: good
+```
-==================
-MSVC compatibility
-==================
+# MSVC compatibility
When Clang compiles C++ code for Windows, it attempts to be compatible with
-MSVC. There are multiple dimensions to compatibility.
+MSVC. There are multiple dimensions to compatibility.
First, Clang attempts to be ABI-compatible, meaning that Clang-compiled code
-should be able to link against MSVC-compiled code successfully. However, C++
+should be able to link against MSVC-compiled code successfully. However, C++
ABIs are particularly large and complicated, and Clang's support for MSVC's C++
-ABI is a work in progress. If you don't require MSVC ABI compatibility or don't
+ABI is a work in progress. If you don't require MSVC ABI compatibility or don't
want to use Microsoft's C and C++ runtimes, the mingw32 toolchain might be a
better fit for your project.
Second, Clang implements many MSVC language extensions, such as
-``__declspec(dllexport)`` and a handful of pragmas. These are typically
-controlled by ``-fms-extensions``.
+`__declspec(dllexport)` and a handful of pragmas. These are typically
+controlled by `-fms-extensions`.
Third, MSVC accepts some C++ code that Clang will typically diagnose as
-invalid. When these constructs are present in widely included system headers,
-Clang attempts to recover and continue compiling the user's program. Most
+invalid. When these constructs are present in widely included system headers,
+Clang attempts to recover and continue compiling the user's program. Most
parsing and semantic compatibility tweaks are controlled by
-``-fms-compatibility`` and ``-fdelayed-template-parsing``, and they are a work
+`-fms-compatibility` and `-fdelayed-template-parsing`, and they are a work
in progress.
-Finally, there is :ref:`clang-cl`, a driver program for clang that attempts to
+Finally, there is {ref}`clang-cl`, a driver program for clang that attempts to
be compatible with MSVC's cl.exe.
-ABI features
-============
+## ABI features
The status of major ABI-impacting C++ features:
-* Record layout: :good:`Complete`. We've tested this with a fuzzer and have
+- Record layout: {good}`Complete`. We've tested this with a fuzzer and have
fixed all known bugs.
-
-* Class inheritance: :good:`Mostly complete`. This covers all of the standard
+- Class inheritance: {good}`Mostly complete`. This covers all of the standard
OO features you would expect: virtual method inheritance, multiple
- inheritance, and virtual inheritance. Every so often we uncover a bug where
- our tables are incompatible, but this is pretty well in hand. This feature
+ inheritance, and virtual inheritance. Every so often we uncover a bug where
+ our tables are incompatible, but this is pretty well in hand. This feature
has also been fuzz tested.
-
-* Name mangling: :good:`Ongoing`. Every new C++ feature generally needs its own
- mangling. For example, member pointer template arguments have an interesting
- and distinct mangling. Fortunately, incorrect manglings usually do not result
- in runtime errors. Non-inline functions with incorrect manglings usually
- result in link errors, which are relatively easy to diagnose. Incorrect
+- Name mangling: {good}`Ongoing`. Every new C++ feature generally needs its own
+ mangling. For example, member pointer template arguments have an interesting
+ and distinct mangling. Fortunately, incorrect manglings usually do not result
+ in runtime errors. Non-inline functions with incorrect manglings usually
+ result in link errors, which are relatively easy to diagnose. Incorrect
manglings for inline functions and templates result in multiple copies in the
- final image. The C++ standard requires that those addresses be equal, but few
+ final image. The C++ standard requires that those addresses be equal, but few
programs rely on this.
-
-* Member pointers: :good:`Mostly complete`. Standard C++ member pointers are
- fully implemented and should be ABI compatible. Both `#pragma
- pointers_to_members`_ and the `/vm`_ flags are supported. However, MSVC
- supports an extension to allow creating a `pointer to a member of a virtual
- base class`_. Clang does not yet support this.
-
-.. _#pragma pointers_to_members:
- https://msdn.microsoft.com/en-us/library/83cch5a6.aspx
-.. _/vm: https://msdn.microsoft.com/en-us/library/yad46a6z.aspx
-.. _pointer to a member of a virtual base class: https://llvm.org/PR15713
-
-* Debug info: :good:`Mostly complete`. Clang emits relatively complete CodeView
- debug information if ``/Z7`` or ``/Zi`` is passed. Microsoft's link.exe will
+- Member pointers: {good}`Mostly complete`. Standard C++ member pointers are
+ fully implemented and should be ABI compatible. Both [#pragma
+ pointers_to_members][#pragma pointers_to_members] and the [/vm] flags are supported. However, MSVC
+ supports an extension to allow creating a [pointer to a member of a virtual
+ base class][pointer to a member of a virtual base class]. Clang does not yet support this.
+
+* Debug info: {good}`Mostly complete`. Clang emits relatively complete CodeView
+ debug information if `/Z7` or `/Zi` is passed. Microsoft's link.exe will
transform the CodeView debug information into a PDB that works in Windows
debuggers and other tools that consume PDB files like ETW. Work to teach lld
about CodeView and PDBs is ongoing.
-
-* RTTI: :good:`Complete`. Generation of RTTI data structures has been
- finished, along with support for the ``/GR`` flag.
-
-* C++ Exceptions: :good:`Mostly complete`. Support for
- C++ exceptions (``try`` / ``catch`` / ``throw``) have been implemented for
- x86 and x64. Our implementation has been well tested but we still get the
+* RTTI: {good}`Complete`. Generation of RTTI data structures has been
+ finished, along with support for the `/GR` flag.
+* C++ Exceptions: {good}`Mostly complete`. Support for
+ C++ exceptions (`try` / `catch` / `throw`) have been implemented for
+ x86 and x64. Our implementation has been well tested but we still get the
odd bug report now and again.
- C++ exception specifications are ignored, but this is `consistent with Visual
- C++`_.
-
-.. _consistent with Visual C++:
- https://msdn.microsoft.com/en-us/library/wfa0edys.aspx
+ C++ exception specifications are ignored, but this is [consistent with Visual
+ C++][consistent with visual c++].
-* Asynchronous Exceptions (SEH): :partial:`Partial`.
- Structured exceptions (``__try`` / ``__except`` / ``__finally``) mostly
+- Asynchronous Exceptions (SEH): {partial}`Partial`.
+ Structured exceptions (`__try` / `__except` / `__finally`) mostly
work on x86 and x64.
LLVM does not model asynchronous exceptions, so it is currently impossible to
catch an asynchronous exception generated in the same frame as the catching
- ``__try``.
-
-* Thread-safe initialization of local statics: :good:`Complete`. MSVC 2015
+ `__try`.
+- Thread-safe initialization of local statics: {good}`Complete`. MSVC 2015
added support for thread-safe initialization of such variables by taking an
ABI break.
We are ABI compatible with both the MSVC 2013 and 2015 ABI for static local
variables.
-
-* Lambdas: :good:`Mostly complete`. Clang is compatible with Microsoft's
+- Lambdas: {good}`Mostly complete`. Clang is compatible with Microsoft's
implementation of lambdas except for providing overloads for conversion to
- function pointer for different calling conventions. However, Microsoft's
+ function pointer for different calling conventions. However, Microsoft's
extension is non-conforming.
-Template instantiation and name lookup
-======================================
+## Template instantiation and name lookup
MSVC allows many invalid constructs in class templates that Clang has
-historically rejected. In order to parse widely distributed headers for
+historically rejected. In order to parse widely distributed headers for
libraries such as the Active Template Library (ATL) and Windows Runtime Library
(WRL), some template rules have been relaxed or extended in Clang on Windows.
The first major semantic difference is that MSVC appears to defer all parsing
and analysis of inline method bodies in class templates until instantiation
-time. By default on Windows, Clang attempts to follow suit. This behavior is
-controlled by the ``-fdelayed-template-parsing`` flag. While Clang delays
+time. By default on Windows, Clang attempts to follow suit. This behavior is
+controlled by the `-fdelayed-template-parsing` flag. While Clang delays
parsing of method bodies, it still parses the bodies *before* template argument
-substitution, which is not what MSVC does. The following compatibility tweaks
+substitution, which is not what MSVC does. The following compatibility tweaks
are necessary to parse the template in those cases.
-MSVC allows some name lookup into dependent base classes. Even on other
-platforms, this has been a `frequently asked question`_ for Clang users. A
+MSVC allows some name lookup into dependent base classes. Even on other
+platforms, this has been a [frequently asked question] for Clang users. A
dependent base class is a base class that depends on the value of a template
-parameter. Clang cannot see any of the names inside dependent bases while it
+parameter. Clang cannot see any of the names inside dependent bases while it
is parsing your template, so the user is sometimes required to use the
-``typename`` keyword to assist the parser. On Windows, Clang attempts to
+`typename` keyword to assist the parser. On Windows, Clang attempts to
follow the normal lookup rules, but if lookup fails, it will assume that the
-user intended to find the name in a dependent base. While parsing the
+user intended to find the name in a dependent base. While parsing the
following program, Clang will recover as if the user had written the
commented-out code:
-.. _frequently asked question:
- https://clang.llvm.org/compatibility.html#dep_lookup
-
-.. code-block:: c++
-
- template <typename T>
- struct Foo : T {
- void f() {
- /*typename*/ T::UnknownType x = /*this->*/unknownMember;
- }
- };
+```c++
+template <typename T>
+struct Foo : T {
+ void f() {
+ /*typename*/ T::UnknownType x = /*this->*/unknownMember;
+ }
+};
+```
After recovery, Clang warns the user that this code is non-standard and issues
a hint suggesting how to fix the problem.
As of this writing, Clang is able to compile a simple ATL hello world
-application. There are still issues parsing WRL headers for modern Windows 8
+application. There are still issues parsing WRL headers for modern Windows 8
apps, but they should be addressed soon.
-__forceinline behavior
-======================
+## \_\_forceinline behavior
-``__forceinline`` behaves like ``[[clang::always_inline]]``.
+`__forceinline` behaves like `[[clang::always_inline]]`.
Inlining is always attempted regardless of optimization level.
-This differs from MSVC where ``__forceinline`` is only respected once inline expansion is enabled
-which allows any function marked implicitly or explicitly ``inline`` or ``__forceinline`` to be expanded.
-Therefore functions marked ``__forceinline`` will be expanded when the optimization level is ``/Od`` unlike
-MSVC where ``__forceinline`` will not be expanded under ``/Od``.
+This differs from MSVC where `__forceinline` is only respected once inline expansion is enabled
+which allows any function marked implicitly or explicitly `inline` or `__forceinline` to be expanded.
+Therefore functions marked `__forceinline` will be expanded when the optimization level is `/Od` unlike
+MSVC where `__forceinline` will not be expanded under `/Od`.
-SIMD and instruction set intrinsic behavior
-===========================================
+## SIMD and instruction set intrinsic behavior
Clang follows the GCC model for intrinsics and not the MSVC model.
There are currently no plans to support the MSVC model.
MSVC intrinsics always emit the machine instruction the intrinsic models regardless of the compile time options specified.
-For example ``__popcnt`` always emits the x86 popcnt instruction even if the compiler does not have the option enabled to emit popcnt on its own volition.
+For example `__popcnt` always emits the x86 popcnt instruction even if the compiler does not have the option enabled to emit popcnt on its own volition.
There are two common cases where code that compiles with MSVC will need reworking to build on clang.
Assume the examples are only built with `-msse2` so we do not have the intrinsics at compile time.
-.. code-block:: c++
-
- unsigned PopCnt(unsigned v) {
- if (HavePopCnt)
- return __popcnt(v);
- else
- return GenericPopCnt(v);
- }
-
-.. code-block:: c++
-
- __m128 dot4_sse3(__m128 v0, __m128 v1) {
- __m128 r = _mm_mul_ps(v0, v1);
- r = _mm_hadd_ps(r, r);
- r = _mm_hadd_ps(r, r);
- return r;
- }
+```c++
+unsigned PopCnt(unsigned v) {
+ if (HavePopCnt)
+ return __popcnt(v);
+ else
+ return GenericPopCnt(v);
+}
+```
+
+```c++
+__m128 dot4_sse3(__m128 v0, __m128 v1) {
+ __m128 r = _mm_mul_ps(v0, v1);
+ r = _mm_hadd_ps(r, r);
+ r = _mm_hadd_ps(r, r);
+ return r;
+}
+```
Clang expects that either you have compile time support for the target features, `-msse3` and `-mpopcnt`, you mark the function with the expected target feature or use runtime detection with an indirect call.
-.. code-block:: c++
-
- __attribute__((__target__("sse3"))) __m128 dot4_sse3(__m128 v0, __m128 v1) {
- __m128 r = _mm_mul_ps(v0, v1);
- r = _mm_hadd_ps(r, r);
- r = _mm_hadd_ps(r, r);
- return r;
- }
+```c++
+__attribute__((__target__("sse3"))) __m128 dot4_sse3(__m128 v0, __m128 v1) {
+ __m128 r = _mm_mul_ps(v0, v1);
+ r = _mm_hadd_ps(r, r);
+ r = _mm_hadd_ps(r, r);
+ return r;
+}
+```
The SSE3 dot product can be easily fixed by either building the translation unit with SSE3 support or using `__target__` to compile that specific function with SSE3 support.
-.. code-block:: c++
+```c++
+unsigned PopCnt(unsigned v) {
+ if (HavePopCnt)
+ return __popcnt(v);
+ else
+ return GenericPopCnt(v);
+}
+```
- unsigned PopCnt(unsigned v) {
- if (HavePopCnt)
- return __popcnt(v);
- else
- return GenericPopCnt(v);
- }
-
-The above ``PopCnt`` example must be changed to work with clang. If we mark the function with `__target__("popcnt")` then the compiler is free to emit popcnt at will which we do not want. While this isn't a concern in our small example it is a concern in larger functions with surrounding code around the intrinsics. Similar reasoning for compiling the translation unit with `-mpopcnt`.
+The above `PopCnt` example must be changed to work with clang. If we mark the function with `__target__("popcnt")` then the compiler is free to emit popcnt at will which we do not want. While this isn't a concern in our small example it is a concern in larger functions with surrounding code around the intrinsics. Similar reasoning for compiling the translation unit with `-mpopcnt`.
We must split each branch into its own function that can be called indirectly instead of using the intrinsic directly.
-.. code-block:: c++
-
- __attribute__((__target__("popcnt"))) unsigned hwPopCnt(unsigned v) { return __popcnt(v); }
- unsigned (*PopCnt)(unsigned) = HavePopCnt ? hwPopCnt : GenericPopCnt;
-
-.. code-block:: c++
-
- __attribute__((__target__("popcnt"))) unsigned hwPopCnt(unsigned v) { return __popcnt(v); }
- unsigned PopCnt(unsigned v) {
- if (HavePopCnt)
- return hwPopCnt(v);
- else
- return GenericPopCnt(v);
- }
-
-In the above example ``hwPopCnt`` will not be inlined into ``PopCnt`` since ``PopCnt`` doesn't have the popcnt target feature.
+```c++
+__attribute__((__target__("popcnt"))) unsigned hwPopCnt(unsigned v) { return __popcnt(v); }
+unsigned (*PopCnt)(unsigned) = HavePopCnt ? hwPopCnt : GenericPopCnt;
+```
+
+```c++
+__attribute__((__target__("popcnt"))) unsigned hwPopCnt(unsigned v) { return __popcnt(v); }
+unsigned PopCnt(unsigned v) {
+ if (HavePopCnt)
+ return hwPopCnt(v);
+ else
+ return GenericPopCnt(v);
+}
+```
+
+In the above example `hwPopCnt` will not be inlined into `PopCnt` since `PopCnt` doesn't have the popcnt target feature.
With a larger function that does real work the function call overhead is negligible. However in our popcnt example there is the function call
overhead. There is no analog for this specific MSVC behavior in clang.
For clang we effectively have to create the dispatch function ourselves to each specific implementation.
-SIMD vector types
-=================
+## SIMD vector types
Clang's simd vector types are builtin types and not user defined types as in MSVC. This does have some observable behavior changes.
We will look at the x86 `__m128` type for the examples below but the statements apply to all vector types including ARM's `float32x4_t`.
There are no members that can be accessed on the vector types. Vector types are not structs in clang.
-You cannot use ``__m128.m128_f32[0]`` to access the first element of the `__m128`.
-This also means struct initialization like ``__m128{ { 0.0f, 0.0f, 0.0f, 0.0f } }`` will not compile with clang.
+You cannot use `__m128.m128_f32[0]` to access the first element of the `__m128`.
+This also means struct initialization like `__m128{ { 0.0f, 0.0f, 0.0f, 0.0f } }` will not compile with clang.
Since vector types are builtin types, clang implements operators on them natively.
-.. code-block:: c++
-
- #ifdef _MSC_VER
- __m128 operator+(__m128 a, __m128 b) { return _mm_add_ps(a, b); }
- #endif
+```c++
+#ifdef _MSC_VER
+__m128 operator+(__m128 a, __m128 b) { return _mm_add_ps(a, b); }
+#endif
+```
The above code will fail to compile since overloaded 'operator+' must have at least one parameter of class or enumeration type.
-You will need to fix such code to have the check ``#if defined(_MSC_VER) && !defined(__clang__)``.
+You will need to fix such code to have the check `#if defined(_MSC_VER) && !defined(__clang__)`.
Since `__m128` is not a class type in clang any overloads after a template definition will not be considered.
-.. code-block:: c++
+```c++
+template<class T>
+void foo(T) {}
- template<class T>
- void foo(T) {}
+template<class T>
+void bar(T t) {
+ foo(t);
+}
- template<class T>
- void bar(T t) {
- foo(t);
- }
+void foo(__m128) {}
- void foo(__m128) {}
+int main() {
+ bar(_mm_setzero_ps());
+}
+```
- int main() {
- bar(_mm_setzero_ps());
- }
-
-With MSVC ``foo(__m128)`` will be selected but with clang ``foo<__m128>()`` will be selected since on clang `__m128` is a builtin type.
+With MSVC `foo(__m128)` will be selected but with clang `foo<__m128>()` will be selected since on clang `__m128` is a builtin type.
In general the takeaway is `__m128` is a builtin type on clang while a class type on MSVC.
+
+[#pragma pointers_to_members]: https://msdn.microsoft.com/en-us/library/83cch5a6.aspx
+[/vm]: https://msdn.microsoft.com/en-us/library/yad46a6z.aspx
+[consistent with visual c++]: https://msdn.microsoft.com/en-us/library/wfa0edys.aspx
+[frequently asked question]: https://clang.llvm.org/compatibility.html#dep_lookup
+[pointer to a member of a virtual base class]: https://llvm.org/PR15713
+
diff --git a/clang/docs/MisExpect.md b/clang/docs/MisExpect.md
index 3c67d58545218..8a29223f8cf3c 100644
--- a/clang/docs/MisExpect.md
+++ b/clang/docs/MisExpect.md
@@ -1,28 +1,29 @@
-===================
-Misexpect
-===================
-.. contents::
+# Misexpect
-.. toctree::
- :maxdepth: 1
+```{contents}
+```
-When developers use ``llvm.expect`` intrinsics, i.e., through use of
-``__builtin_expect(...)``, they are trying to communicate how their code is
+```{toctree}
+:maxdepth: 1
+```
+
+When developers use `llvm.expect` intrinsics, i.e., through use of
+`__builtin_expect(...)`, they are trying to communicate how their code is
expected to behave at runtime to the optimizer. These annotations, however, can
be incorrect for a variety of reasons: changes to the code base invalidate them
-silently, the developer mis-annotated them (e.g., using ``LIKELY`` instead of
-``UNLIKELY``), or perhaps they assumed something incorrectly when they wrote
+silently, the developer mis-annotated them (e.g., using `LIKELY` instead of
+`UNLIKELY`), or perhaps they assumed something incorrectly when they wrote
the annotation. Regardless of why, it is useful to detect these situations so
that the optimizer can make more useful decisions about the code.
MisExpect diagnostics are intended to help developers identify and address
-these situations, by comparing the branch weights added by the ``llvm.expect``
+these situations, by comparing the branch weights added by the `llvm.expect`
intrinsic to those collected through profiling. Whenever these values are
mismatched, a diagnostic is surfaced to the user. Details on how the checks
operate in the LLVM backend can be found in LLVM's documentation.
By default MisExpect checking is quite strict, because the use of the
-``llvm.expect`` intrinsic is designed for specialized cases, where the outcome
+`llvm.expect` intrinsic is designed for specialized cases, where the outcome
of a condition is severely skewed. As a result, the optimizer can be extremely
aggressive, which can result in performance degradation if the outcome is less
predictable than the annotation suggests. Even when the annotation is correct
@@ -31,44 +32,46 @@ a different intrinsic that can communicate the probability more directly.
Because this may be too strict, MisExpect diagnostics are not enabled by
default, and support an additional flag to tolerate some deviation from the
-exact thresholds. The ``-fdiagnostic-misexpect-tolerance=N`` accepts
-deviations when comparing branch weights within ``N%`` of the expected values.
-So passing ``-fdiagnostic-misexpect-tolerance=5`` will not report diagnostic messages
+exact thresholds. The `-fdiagnostic-misexpect-tolerance=N` accepts
+deviations when comparing branch weights within `N%` of the expected values.
+So passing `-fdiagnostic-misexpect-tolerance=5` will not report diagnostic messages
if the branch weight from the profile is within 5% of the weight added by
-the ``llvm.expect`` intrinsic.
+the `llvm.expect` intrinsic.
MisExpect diagnostics are also available in the form of optimization remarks,
-which can be serialized and processed through the ``opt-viewer.py``
+which can be serialized and processed through the `opt-viewer.py`
scripts in LLVM.
+```{eval-rst}
.. option:: -Rpass=misexpect
Enables optimization remarks for misexpect when profiling data conflicts with
use of ``llvm.expect`` intrinsics.
+```
+```{eval-rst}
.. option:: -Wmisexpect
Enables misexpect warnings when profiling data conflicts with use of
``llvm.expect`` intrinsics.
+```
+```{eval-rst}
.. option:: -fdiagnostic-misexpect-tolerance=N
Relaxes misexpect checking to tolerate profiling values within N% of the
expected branch weight. e.g., a value of ``N=5`` allows misexpect to check against
``0.95 * Threshold``
+```
LLVM supports 4 types of profile formats: Frontend, IR, CS-IR, and
Sampling. MisExpect Diagnostics are compatible with all Profiling formats.
-+----------------+--------------------------------------------------------------------------------------+
-| Profile Type | Description |
-+================+======================================================================================+
-| Frontend | Profiling instrumentation added during compilation by the frontend, i.e. ``clang`` |
-+----------------+--------------------------------------------------------------------------------------+
-| IR | Profiling instrumentation added during by the LLVM backend |
-+----------------+--------------------------------------------------------------------------------------+
-| CS-IR | Context Sensitive IR based profiles |
-+----------------+--------------------------------------------------------------------------------------+
-| Sampling | Profiles collected through sampling with external tools, such as ``perf`` on Linux |
-+----------------+--------------------------------------------------------------------------------------+
+| Profile Type | Description |
+| ------------ | -------------------------------------------------------------------------------- |
+| Frontend | Profiling instrumentation added during compilation by the frontend, i.e. `clang` |
+| IR | Profiling instrumentation added during by the LLVM backend |
+| CS-IR | Context Sensitive IR based profiles |
+| Sampling | Profiles collected through sampling with external tools, such as `perf` on Linux |
+
diff --git a/clang/docs/Modules.md b/clang/docs/Modules.md
index 379f62ebf548c..3404157d677a2 100644
--- a/clang/docs/Modules.md
+++ b/clang/docs/Modules.md
@@ -1,27 +1,26 @@
-=======
-Modules
-=======
+# Modules
-.. contents::
- :local:
+```{contents}
+:local: true
+```
-Introduction
-============
-Most software is built using a number of software libraries, including libraries supplied by the platform, internal libraries built as part of the software itself to provide structure, and third-party libraries. For each library, one needs to access both its interface (API) and its implementation. In the C family of languages, the interface to a library is accessed by including the appropriate header files(s):
+## Introduction
-.. code-block:: c
+Most software is built using a number of software libraries, including libraries supplied by the platform, internal libraries built as part of the software itself to provide structure, and third-party libraries. For each library, one needs to access both its interface (API) and its implementation. In the C family of languages, the interface to a library is accessed by including the appropriate header files(s):
- #include <SomeLib.h>
+```c
+#include <SomeLib.h>
+```
-The implementation is handled separately by linking against the appropriate library. For example, by passing ``-lSomeLib`` to the linker.
+The implementation is handled separately by linking against the appropriate library. For example, by passing `-lSomeLib` to the linker.
Modules provide an alternative, simpler way to use software libraries that provides better compile-time scalability and eliminates many of the problems inherent to using the C preprocessor to access the API of a library.
-Problems with the current model
--------------------------------
-The ``#include`` mechanism provided by the C preprocessor is a very poor way to access the API of a library, for a number of reasons:
+### Problems with the current model
-* **Compile-time scalability**: Each time a header is included, the
+The `#include` mechanism provided by the C preprocessor is a very poor way to access the API of a library, for a number of reasons:
+
+- **Compile-time scalability**: Each time a header is included, the
compiler must preprocess and parse the text in that header and every
header it includes, transitively. This process must be repeated for
every translation unit in the application, which involves a huge
@@ -31,35 +30,32 @@ The ``#include`` mechanism provided by the C preprocessor is a very poor way to
shared among multiple translation units. C++ is particularly bad,
because the compilation model for templates forces a huge amount of
code into headers.
-
-* **Fragility**: ``#include`` directives are treated as textual
+- **Fragility**: `#include` directives are treated as textual
inclusion by the preprocessor, and are therefore subject to any
active macro definitions at the time of inclusion. If any of the
active macro definitions happens to collide with a name in the
library, it can break the library API or cause compilation failures
in the library header itself. For an extreme example,
- ``#define std "The C++ Standard"`` and then include a standard
+ `#define std "The C++ Standard"` and then include a standard
library header: the result is a horrific cascade of failures in the
C++ Standard Library's implementation. More subtle real-world
problems occur when the headers for two different libraries interact
due to macro collisions, and users are forced to reorder
- ``#include`` directives or introduce ``#undef`` directives to break
+ `#include` directives or introduce `#undef` directives to break
the (unintended) dependency.
-
-* **Conventional workarounds**: C programmers have
+- **Conventional workarounds**: C programmers have
adopted a number of conventions to work around the fragility of the
C preprocessor model. Include guards, for example, are required for
the vast majority of headers to ensure that multiple inclusion
doesn't break the compile. Macro names are written with
- ``LONG_PREFIXED_UPPERCASE_IDENTIFIERS`` to avoid collisions, and some
- library/framework developers even use ``__underscored`` names
+ `LONG_PREFIXED_UPPERCASE_IDENTIFIERS` to avoid collisions, and some
+ library/framework developers even use `__underscored` names
in headers to avoid collisions with "normal" names that (by
convention) shouldn't even be macros. These conventions are a
barrier to entry for developers coming from non-C languages, are
boilerplate for more experienced developers, and make our headers
far uglier than they should be.
-
-* **Tool confusion**: In a C-based language, it is hard to build tools
+- **Tool confusion**: In a C-based language, it is hard to build tools
that work well with software libraries, because the boundaries of
the libraries are not clear. Which headers belong to a particular
library, and in what order should those headers be included to
@@ -69,356 +65,370 @@ The ``#include`` mechanism provided by the C preprocessor is a very poor way to
API, and what declarations are present only because they had to be
written as part of the header file?
-Semantic import
----------------
-Modules improve access to the API of software libraries by replacing the textual preprocessor inclusion model with a more robust, more efficient semantic model. From the user's perspective, the code looks only slightly different, because one uses an ``import`` declaration rather than a ``#include`` preprocessor directive:
+### Semantic import
-.. code-block:: c
+Modules improve access to the API of software libraries by replacing the textual preprocessor inclusion model with a more robust, more efficient semantic model. From the user's perspective, the code looks only slightly different, because one uses an `import` declaration rather than a `#include` preprocessor directive:
- import std.io; // pseudo-code; see below for syntax discussion
+```c
+import std.io; // pseudo-code; see below for syntax discussion
+```
-However, this module import behaves quite differently from the corresponding ``#include <stdio.h>``: when the compiler sees the module import above, it loads a binary representation of the ``std.io`` module and makes its API available to the application directly. Preprocessor definitions that precede the import declaration have no impact on the API provided by ``std.io``, because the module itself was compiled as a separate, standalone module. Additionally, any linker flags required to use the ``std.io`` module will automatically be provided when the module is imported [#]_
+However, this module import behaves quite differently from the corresponding `#include <stdio.h>`: when the compiler sees the module import above, it loads a binary representation of the `std.io` module and makes its API available to the application directly. Preprocessor definitions that precede the import declaration have no impact on the API provided by `std.io`, because the module itself was compiled as a separate, standalone module. Additionally, any linker flags required to use the `std.io` module will automatically be provided when the module is imported [^footnote-1]
This semantic import model addresses many of the problems of the preprocessor inclusion model:
-* **Compile-time scalability**: The ``std.io`` module is only compiled once, and importing the module into a translation unit is a constant-time operation (independent of module system). Thus, the API of each software library is only parsed once, reducing the *M x N* compilation problem to an *M + N* problem.
+- **Compile-time scalability**: The `std.io` module is only compiled once, and importing the module into a translation unit is a constant-time operation (independent of module system). Thus, the API of each software library is only parsed once, reducing the *M x N* compilation problem to an *M + N* problem.
+- **Fragility**: Each module is parsed as a standalone entity, so it has a consistent preprocessor environment. This completely eliminates the need for `__underscored` names and similarly defensive tricks. Moreover, the current preprocessor definitions when an import declaration is encountered are ignored, so one software library can not affect how another software library is compiled, eliminating include-order dependencies.
+- **Tool confusion**: Modules describe the API of software libraries, and tools can reason about and present a module as a representation of that API. Because modules can only be built standalone, tools can rely on the module definition to ensure that they get the complete API for the library. Moreover, modules can specify which languages they work with, so, e.g., one can not accidentally attempt to load a C++ module into a C program.
-* **Fragility**: Each module is parsed as a standalone entity, so it has a consistent preprocessor environment. This completely eliminates the need for ``__underscored`` names and similarly defensive tricks. Moreover, the current preprocessor definitions when an import declaration is encountered are ignored, so one software library can not affect how another software library is compiled, eliminating include-order dependencies.
+### Problems modules do not solve
-* **Tool confusion**: Modules describe the API of software libraries, and tools can reason about and present a module as a representation of that API. Because modules can only be built standalone, tools can rely on the module definition to ensure that they get the complete API for the library. Moreover, modules can specify which languages they work with, so, e.g., one can not accidentally attempt to load a C++ module into a C program.
-
-Problems modules do not solve
------------------------------
Many programming languages have a module or package system, and because of the variety of features provided by these languages it is important to define what modules do *not* do. In particular, all of the following are considered out-of-scope for modules:
-* **Rewrite the world's code**: It is not realistic to require applications or software libraries to make drastic or non-backward-compatible changes, nor is it feasible to completely eliminate headers. Modules must interoperate with existing software libraries and allow a gradual transition.
+- **Rewrite the world's code**: It is not realistic to require applications or software libraries to make drastic or non-backward-compatible changes, nor is it feasible to completely eliminate headers. Modules must interoperate with existing software libraries and allow a gradual transition.
+- **Versioning**: Modules have no notion of version information. Programmers must still rely on the existing versioning mechanisms of the underlying language (if any exist) to version software libraries.
+- **Namespaces**: Unlike in some languages, modules do not imply any notion of namespaces. Thus, a struct declared in one module will still conflict with a struct of the same name declared in a different module, just as they would if declared in two different headers. This aspect is important for backward compatibility, because (for example) the mangled names of entities in software libraries must not change when introducing modules.
+- **Binary distribution of modules**: Headers (particularly C++ headers) expose the full complexity of the language. Maintaining a stable binary module format across architectures, compiler versions, and compiler vendors is technically infeasible.
-* **Versioning**: Modules have no notion of version information. Programmers must still rely on the existing versioning mechanisms of the underlying language (if any exist) to version software libraries.
+## Using Modules
-* **Namespaces**: Unlike in some languages, modules do not imply any notion of namespaces. Thus, a struct declared in one module will still conflict with a struct of the same name declared in a different module, just as they would if declared in two different headers. This aspect is important for backward compatibility, because (for example) the mangled names of entities in software libraries must not change when introducing modules.
+To enable modules, pass the command-line flag `-fmodules`. This will make any modules-enabled software libraries available as modules as well as introducing any modules-specific syntax. Additional [command-line parameters] are described in a separate section later.
-* **Binary distribution of modules**: Headers (particularly C++ headers) expose the full complexity of the language. Maintaining a stable binary module format across architectures, compiler versions, and compiler vendors is technically infeasible.
+### Standard C++ Modules
-Using Modules
-=============
-To enable modules, pass the command-line flag ``-fmodules``. This will make any modules-enabled software libraries available as modules as well as introducing any modules-specific syntax. Additional `command-line parameters`_ are described in a separate section later.
+:::{note}
+Modules are adopted into C++20 Standard. And its semantic and command line interface are very different from the Clang C++ modules. See [StandardCPlusPlusModules](StandardCPlusPlusModules.html) for details.
+:::
-Standard C++ Modules
---------------------
-.. note::
- Modules are adopted into C++20 Standard. And its semantic and command line interface are very different from the Clang C++ modules. See `StandardCPlusPlusModules <StandardCPlusPlusModules.html>`_ for details.
+### Objective-C Import declaration
-Objective-C Import declaration
-------------------------------
Objective-C provides syntax for importing a module via an *@import declaration*, which imports the named module:
+```{eval-rst}
.. parsed-literal::
@import std;
+```
-The ``@import`` declaration above imports the entire contents of the ``std`` module (which would contain, e.g., the entire C or C++ standard library) and make its API available within the current translation unit. To import only part of a module, one may use dot syntax to specify a particular submodule, e.g.,
+The `@import` declaration above imports the entire contents of the `std` module (which would contain, e.g., the entire C or C++ standard library) and make its API available within the current translation unit. To import only part of a module, one may use dot syntax to specify a particular submodule, e.g.,
+```{eval-rst}
.. parsed-literal::
@import std.io;
+```
Redundant import declarations are ignored, and one is free to import modules at any point within the translation unit, so long as the import declaration is at global scope.
At present, there is no C or C++ syntax for import declarations. Clang
will track the modules proposal in the C++ committee. See the section
-`Includes as imports`_ to see how modules get imported today.
-
-Includes as imports
--------------------
-The primary user-level feature of modules is the import operation, which provides access to the API of software libraries. However, today's programs make extensive use of ``#include``, and it is unrealistic to assume that all of this code will change overnight. Instead, modules automatically translate ``#include`` directives into the corresponding module import. For example, the include directive
+[Includes as imports] to see how modules get imported today.
-.. code-block:: c
+### Includes as imports
- #include <stdio.h>
+The primary user-level feature of modules is the import operation, which provides access to the API of software libraries. However, today's programs make extensive use of `#include`, and it is unrealistic to assume that all of this code will change overnight. Instead, modules automatically translate `#include` directives into the corresponding module import. For example, the include directive
-will be automatically mapped to an import of the module ``std.io``. Even with specific ``import`` syntax in the language, this particular feature is important for both adoption and backward compatibility: automatic translation of ``#include`` to ``import`` allows an application to get the benefits of modules (for all modules-enabled libraries) without any changes to the application itself. Thus, users can easily use modules with one compiler while falling back to the preprocessor-inclusion mechanism with other compilers.
+```c
+#include <stdio.h>
+```
-.. note::
+will be automatically mapped to an import of the module `std.io`. Even with specific `import` syntax in the language, this particular feature is important for both adoption and backward compatibility: automatic translation of `#include` to `import` allows an application to get the benefits of modules (for all modules-enabled libraries) without any changes to the application itself. Thus, users can easily use modules with one compiler while falling back to the preprocessor-inclusion mechanism with other compilers.
- The automatic mapping of ``#include`` to ``import`` also solves an implementation problem: importing a module with a definition of some entity (say, a ``struct Point``) and then parsing a header containing another definition of ``struct Point`` would cause a redefinition error, even if it is the same ``struct Point``. By mapping ``#include`` to ``import``, the compiler can guarantee that it always sees just the already-parsed definition from the module.
+:::{note}
+The automatic mapping of `#include` to `import` also solves an implementation problem: importing a module with a definition of some entity (say, a `struct Point`) and then parsing a header containing another definition of `struct Point` would cause a redefinition error, even if it is the same `struct Point`. By mapping `#include` to `import`, the compiler can guarantee that it always sees just the already-parsed definition from the module.
+:::
-While building a module, ``#include_next`` is also supported, with one caveat.
-The usual behavior of ``#include_next`` is to search for the specified filename
+While building a module, `#include_next` is also supported, with one caveat.
+The usual behavior of `#include_next` is to search for the specified filename
in the list of include paths, starting from the path *after* the one
in which the current file was found.
Because files listed in module maps are not found through include paths, a
-different strategy is used for ``#include_next`` directives in such files: the
+different strategy is used for `#include_next` directives in such files: the
list of include paths is searched for the specified header name, to find the
-first include path that would refer to the current file. ``#include_next`` is
+first include path that would refer to the current file. `#include_next` is
interpreted as if the current file had been found in that path.
-If this search finds a file named by a module map, the ``#include_next``
-directive is translated into an import, just like for a ``#include``
+If this search finds a file named by a module map, the `#include_next`
+directive is translated into an import, just like for a `#include`
directive.
-Module maps
------------
-The crucial link between modules and headers is described by a *module map*, which describes how a collection of existing headers maps on to the (logical) structure of a module. For example, one could imagine a module ``std`` covering the C standard library. Each of the C standard library headers (``<stdio.h>``, ``<stdlib.h>``, ``<math.h>``, etc.) would contribute to the ``std`` module, by placing their respective APIs into the corresponding submodule (``std.io``, ``std.lib``, ``std.math``, etc.). Having a list of the headers that are part of the ``std`` module allows the compiler to build the ``std`` module as a standalone entity, and having the mapping from header names to (sub)modules allows the automatic translation of ``#include`` directives to module imports.
+### Module maps
-Module maps are specified as separate files (each named ``module.modulemap``) alongside the headers they describe, which allows them to be added to existing software libraries without having to change the library headers themselves (in most cases [#]_). The actual `Module map language`_ is described in a later section.
+The crucial link between modules and headers is described by a *module map*, which describes how a collection of existing headers maps on to the (logical) structure of a module. For example, one could imagine a module `std` covering the C standard library. Each of the C standard library headers (`<stdio.h>`, `<stdlib.h>`, `<math.h>`, etc.) would contribute to the `std` module, by placing their respective APIs into the corresponding submodule (`std.io`, `std.lib`, `std.math`, etc.). Having a list of the headers that are part of the `std` module allows the compiler to build the `std` module as a standalone entity, and having the mapping from header names to (sub)modules allows the automatic translation of `#include` directives to module imports.
-.. note::
+Module maps are specified as separate files (each named `module.modulemap`) alongside the headers they describe, which allows them to be added to existing software libraries without having to change the library headers themselves (in most cases [^footnote-2]). The actual [Module map language] is described in a later section.
- To actually see any benefits from modules, one first has to introduce module maps for the underlying C standard library and the libraries and headers on which it depends. The section `Modularizing a Platform`_ describes the steps one must take to write these module maps.
+:::{note}
+To actually see any benefits from modules, one first has to introduce module maps for the underlying C standard library and the libraries and headers on which it depends. The section [Modularizing a Platform] describes the steps one must take to write these module maps.
+:::
-One can use module maps without modules to check the integrity of the use of header files. To do this, use the ``-fimplicit-module-maps`` option instead of the ``-fmodules`` option, or use ``-fmodule-map-file=`` option to explicitly specify the module map files to load.
+One can use module maps without modules to check the integrity of the use of header files. To do this, use the `-fimplicit-module-maps` option instead of the `-fmodules` option, or use `-fmodule-map-file=` option to explicitly specify the module map files to load.
-Compilation model
------------------
-The binary representation of modules is automatically generated by the compiler on an as-needed basis. When a module is imported (e.g., by an ``#include`` of one of the module's headers), the compiler will spawn a second instance of itself [#]_, with a fresh preprocessing context [#]_, to parse just the headers in that module. The resulting Abstract Syntax Tree (AST) is then persisted into the binary representation of the module that is then loaded into translation unit where the module import was encountered.
+### Compilation model
+
+The binary representation of modules is automatically generated by the compiler on an as-needed basis. When a module is imported (e.g., by an `#include` of one of the module's headers), the compiler will spawn a second instance of itself [^footnote-3], with a fresh preprocessing context [^footnote-4], to parse just the headers in that module. The resulting Abstract Syntax Tree (AST) is then persisted into the binary representation of the module that is then loaded into translation unit where the module import was encountered.
The binary representation of modules is persisted in the *module cache*. Imports of a module will first query the module cache and, if a binary representation of the required module is already available, will load that representation directly. Thus, a module's headers will only be parsed once per language configuration, rather than once per translation unit that uses the module.
Modules maintain references to each of the headers that were part of the module build. If any of those headers changes, or if any of the modules on which a module depends change, then the module will be (automatically) recompiled. The process should never require any user intervention.
-Command-line parameters
------------------------
-``-fmodules``
- Enable the modules feature.
-
-``-fbuiltin-module-map``
- Load the Clang builtins module map file. (Equivalent to ``-fmodule-map-file=<resource dir>/include/module.modulemap``)
+### Command-line parameters
-``-fimplicit-module-maps``
- Enable implicit search for module map files named ``module.modulemap`` and similar. This option is implied by ``-fmodules``. If this is disabled with ``-fno-implicit-module-maps``, module map files will only be loaded if they are explicitly specified via ``-fmodule-map-file`` or transitively used by another module map file.
+`-fmodules`
-``-fmodules-cache-path=<directory>``
- Specify the path to the modules cache. If not provided, Clang will select a system-appropriate default.
+: Enable the modules feature.
-``-fno-autolink``
- Disable automatic linking against the libraries associated with imported modules.
+`-fbuiltin-module-map`
-``-fmodules-ignore-macro=macroname``
- Instruct modules to ignore the named macro when selecting an appropriate module variant. Use this for macros defined on the command line that don't affect how modules are built, to improve sharing of compiled module files.
+: Load the Clang builtins module map file. (Equivalent to `-fmodule-map-file=<resource dir>/include/module.modulemap`)
-``-fmodules-prune-interval=seconds``
- Specify the minimum delay (in seconds) between attempts to prune the module cache. Module cache pruning attempts to clear out old, unused module files so that the module cache itself does not grow without bound. The default delay is large (604,800 seconds, or 7 days) because this is an expensive operation. Set this value to 0 to turn off pruning.
+`-fimplicit-module-maps`
-``-fmodules-prune-after=seconds``
- Specify the minimum time (in seconds) for which a file in the module cache must be unused (according to access time) before module pruning will remove it. The default delay is large (2,678,400 seconds, or 31 days) to avoid excessive module rebuilding.
+: Enable implicit search for module map files named `module.modulemap` and similar. This option is implied by `-fmodules`. If this is disabled with `-fno-implicit-module-maps`, module map files will only be loaded if they are explicitly specified via `-fmodule-map-file` or transitively used by another module map file.
-``-module-file-info <module file name>``
- Debugging aid that prints information about a given module file (with a ``.pcm`` extension), including the language and preprocessor options that particular module variant was built with.
+`-fmodules-cache-path=<directory>`
-``-fmodules-decluse``
- Enable checking of module ``use`` declarations.
+: Specify the path to the modules cache. If not provided, Clang will select a system-appropriate default.
-``-fmodule-name=module-id``
- Consider a source file as a part of the given module.
+`-fno-autolink`
-``-fmodule-map-file=<file>``
- Load the given module map file if a header from its directory or one of its subdirectories is loaded.
+: Disable automatic linking against the libraries associated with imported modules.
-``-fmodules-search-all``
- If a symbol is not found, search modules referenced in the current module maps but not imported for symbols, so the error message can reference the module by name. Note that if the global module index has not been built before, this might take some time as it needs to build all the modules. Note that this option doesn't apply in module builds, to avoid the recursion.
+`-fmodules-ignore-macro=macroname`
-``-fno-implicit-modules``
- All modules used by the build must be specified with ``-fmodule-file``.
+: Instruct modules to ignore the named macro when selecting an appropriate module variant. Use this for macros defined on the command line that don't affect how modules are built, to improve sharing of compiled module files.
-``-fmodule-file=[<name>=]<file>``
- Specify the mapping of module names to precompiled module files. If the
- name is omitted, then the module file is loaded whether actually required
- or not. If the name is specified, then the mapping is treated as another
- prebuilt module search mechanism (in addition to ``-fprebuilt-module-path``)
- and the module is only loaded if required. Note that in this case the
- specified file also overrides this module's paths that might be embedded
- in other precompiled module files.
+`-fmodules-prune-interval=seconds`
-``-fprebuilt-module-path=<directory>``
- Specify the path to the prebuilt modules. If specified, we will look for modules in this directory for a given top-level module name. We don't need a module map for loading prebuilt modules in this directory and the compiler will not try to rebuild these modules. This can be specified multiple times.
+: Specify the minimum delay (in seconds) between attempts to prune the module cache. Module cache pruning attempts to clear out old, unused module files so that the module cache itself does not grow without bound. The default delay is large (604,800 seconds, or 7 days) because this is an expensive operation. Set this value to 0 to turn off pruning.
-``-fprebuilt-implicit-modules``
- Enable prebuilt implicit modules. If a prebuilt module is not found in the
- prebuilt modules paths (specified via ``-fprebuilt-module-path``), we will
- look for a matching implicit module in the prebuilt modules paths.
+`-fmodules-prune-after=seconds`
--cc1 Options
-~~~~~~~~~~~~
+: Specify the minimum time (in seconds) for which a file in the module cache must be unused (according to access time) before module pruning will remove it. The default delay is large (2,678,400 seconds, or 31 days) to avoid excessive module rebuilding.
-``-fmodules-strict-context-hash``
- Enables hashing of all compiler options that could impact the semantics of a
- module in an implicit build. This includes things such as header search paths
- and diagnostics. Using this option may lead to an excessive number of modules
- being built if the command line arguments are not homogeneous across your
- build.
+`-module-file-info <module file name>`
-Using Prebuilt Modules
-----------------------
+: Debugging aid that prints information about a given module file (with a `.pcm` extension), including the language and preprocessor options that particular module variant was built with.
-Below are a few examples illustrating uses of prebuilt modules via the different options.
+`-fmodules-decluse`
-First, let's set up files for our examples.
+: Enable checking of module `use` declarations.
-.. code-block:: c
+`-fmodule-name=module-id`
- /* A.h */
- #ifdef ENABLE_A
- void a() {}
- #endif
+: Consider a source file as a part of the given module.
-.. code-block:: c
+`-fmodule-map-file=<file>`
- /* B.h */
- #include "A.h"
+: Load the given module map file if a header from its directory or one of its subdirectories is loaded.
-.. code-block:: c
+`-fmodules-search-all`
- /* use.c */
- #include "B.h"
- void use() {
- #ifdef ENABLE_A
- a();
- #endif
- }
+: If a symbol is not found, search modules referenced in the current module maps but not imported for symbols, so the error message can reference the module by name. Note that if the global module index has not been built before, this might take some time as it needs to build all the modules. Note that this option doesn't apply in module builds, to avoid the recursion.
-.. code-block:: c
+`-fno-implicit-modules`
- /* module.modulemap */
- module A {
- header "A.h"
- }
- module B {
- header "B.h"
- export *
- }
+: All modules used by the build must be specified with `-fmodule-file`.
-In the examples below, the compilation of ``use.c`` can be done without ``-cc1``, but the commands used to prebuild the modules would need to be updated to take into account the default options passed to ``clang -cc1``. (See ``clang use.c -v``)
-Note also that, since we use ``-cc1``, we specify the ``-fmodule-map-file=`` or ``-fimplicit-module-maps`` options explicitly. When using the clang driver, ``-fimplicit-module-maps`` is implied by ``-fmodules``.
+`-fmodule-file=[<name>=]<file>`
-First let us use an explicit mapping from modules to files.
+: Specify the mapping of module names to precompiled module files. If the
+ name is omitted, then the module file is loaded whether actually required
+ or not. If the name is specified, then the mapping is treated as another
+ prebuilt module search mechanism (in addition to `-fprebuilt-module-path`)
+ and the module is only loaded if required. Note that in this case the
+ specified file also overrides this module's paths that might be embedded
+ in other precompiled module files.
-.. code-block:: sh
+`-fprebuilt-module-path=<directory>`
- rm -rf prebuilt ; mkdir prebuilt
- clang -cc1 -emit-module -o prebuilt/A.pcm -fmodules module.modulemap -fmodule-name=A
- clang -cc1 -emit-module -o prebuilt/B.pcm -fmodules module.modulemap -fmodule-name=B -fmodule-file=A=prebuilt/A.pcm
- clang -cc1 -emit-obj use.c -fmodules -fmodule-map-file=module.modulemap -fmodule-file=A=prebuilt/A.pcm -fmodule-file=B=prebuilt/B.pcm
+: Specify the path to the prebuilt modules. If specified, we will look for modules in this directory for a given top-level module name. We don't need a module map for loading prebuilt modules in this directory and the compiler will not try to rebuild these modules. This can be specified multiple times.
-Instead of specifying the mappings manually, it can be convenient to use the ``-fprebuilt-module-path`` option. Let's also use ``-fimplicit-module-maps`` instead of manually pointing to our module map.
+`-fprebuilt-implicit-modules`
-.. code-block:: sh
+: Enable prebuilt implicit modules. If a prebuilt module is not found in the
+ prebuilt modules paths (specified via `-fprebuilt-module-path`), we will
+ look for a matching implicit module in the prebuilt modules paths.
- rm -rf prebuilt; mkdir prebuilt
- clang -cc1 -emit-module -o prebuilt/A.pcm -fmodules module.modulemap -fmodule-name=A
- clang -cc1 -emit-module -o prebuilt/B.pcm -fmodules module.modulemap -fmodule-name=B -fprebuilt-module-path=prebuilt
- clang -cc1 -emit-obj use.c -fmodules -fimplicit-module-maps -fprebuilt-module-path=prebuilt
+#### -cc1 Options
-A trick to prebuild all modules required for our source file in one command is to generate implicit modules while using the ``-fdisable-module-hash`` option.
+`-fmodules-strict-context-hash`
-.. code-block:: sh
+: Enables hashing of all compiler options that could impact the semantics of a
+ module in an implicit build. This includes things such as header search paths
+ and diagnostics. Using this option may lead to an excessive number of modules
+ being built if the command line arguments are not homogeneous across your
+ build.
- rm -rf prebuilt ; mkdir prebuilt
- clang -cc1 -emit-obj use.c -fmodules -fimplicit-module-maps -fmodules-cache-path=prebuilt -fdisable-module-hash
- ls prebuilt/*.pcm
- # prebuilt/A.pcm prebuilt/B.pcm
+### Using Prebuilt Modules
-Note that with explicit or prebuilt modules, we are responsible for, and should be particularly careful about the compatibility of our modules.
-Using mismatching compilation options and modules may lead to issues.
+Below are a few examples illustrating uses of prebuilt modules via the different options.
-.. code-block:: sh
+First, let's set up files for our examples.
- clang -cc1 -emit-obj use.c -fmodules -fimplicit-module-maps -fprebuilt-module-path=prebuilt -DENABLE_A
- # use.c:4:10: warning: implicit declaration of function 'a' is invalid in C99 [-Wimplicit-function-declaration]
- # return a(x);
- # ^
- # 1 warning generated.
+```c
+/* A.h */
+#ifdef ENABLE_A
+void a() {}
+#endif
+```
+
+```c
+/* B.h */
+#include "A.h"
+```
+
+```c
+/* use.c */
+#include "B.h"
+void use() {
+#ifdef ENABLE_A
+ a();
+#endif
+}
+```
+
+```c
+/* module.modulemap */
+module A {
+ header "A.h"
+}
+module B {
+ header "B.h"
+ export *
+}
+```
+
+In the examples below, the compilation of `use.c` can be done without `-cc1`, but the commands used to prebuild the modules would need to be updated to take into account the default options passed to `clang -cc1`. (See `clang use.c -v`)
+Note also that, since we use `-cc1`, we specify the `-fmodule-map-file=` or `-fimplicit-module-maps` options explicitly. When using the clang driver, `-fimplicit-module-maps` is implied by `-fmodules`.
-So we need to maintain multiple versions of prebuilt modules. We can do so using a manual module mapping, or pointing to a different prebuilt module cache path. For example:
+First let us use an explicit mapping from modules to files.
-.. code-block:: sh
+```sh
+rm -rf prebuilt ; mkdir prebuilt
+clang -cc1 -emit-module -o prebuilt/A.pcm -fmodules module.modulemap -fmodule-name=A
+clang -cc1 -emit-module -o prebuilt/B.pcm -fmodules module.modulemap -fmodule-name=B -fmodule-file=A=prebuilt/A.pcm
+clang -cc1 -emit-obj use.c -fmodules -fmodule-map-file=module.modulemap -fmodule-file=A=prebuilt/A.pcm -fmodule-file=B=prebuilt/B.pcm
+```
- rm -rf prebuilt ; mkdir prebuilt ; rm -rf prebuilt_a ; mkdir prebuilt_a
- clang -cc1 -emit-obj use.c -fmodules -fimplicit-module-maps -fmodules-cache-path=prebuilt -fdisable-module-hash
- clang -cc1 -emit-obj use.c -fmodules -fimplicit-module-maps -fmodules-cache-path=prebuilt_a -fdisable-module-hash -DENABLE_A
- clang -cc1 -emit-obj use.c -fmodules -fimplicit-module-maps -fprebuilt-module-path=prebuilt
- clang -cc1 -emit-obj use.c -fmodules -fimplicit-module-maps -fprebuilt-module-path=prebuilt_a -DENABLE_A
+Instead of specifying the mappings manually, it can be convenient to use the `-fprebuilt-module-path` option. Let's also use `-fimplicit-module-maps` instead of manually pointing to our module map.
+```sh
+rm -rf prebuilt; mkdir prebuilt
+clang -cc1 -emit-module -o prebuilt/A.pcm -fmodules module.modulemap -fmodule-name=A
+clang -cc1 -emit-module -o prebuilt/B.pcm -fmodules module.modulemap -fmodule-name=B -fprebuilt-module-path=prebuilt
+clang -cc1 -emit-obj use.c -fmodules -fimplicit-module-maps -fprebuilt-module-path=prebuilt
+```
-Instead of managing the different module versions manually, we can build implicit modules in a given cache path (using ``-fmodules-cache-path``), and reuse them as prebuilt implicit modules by passing ``-fprebuilt-module-path`` and ``-fprebuilt-implicit-modules``.
+A trick to prebuild all modules required for our source file in one command is to generate implicit modules while using the `-fdisable-module-hash` option.
-.. code-block:: sh
+```sh
+rm -rf prebuilt ; mkdir prebuilt
+clang -cc1 -emit-obj use.c -fmodules -fimplicit-module-maps -fmodules-cache-path=prebuilt -fdisable-module-hash
+ls prebuilt/*.pcm
+# prebuilt/A.pcm prebuilt/B.pcm
+```
- rm -rf prebuilt; mkdir prebuilt
- clang -cc1 -emit-obj -o use.o use.c -fmodules -fimplicit-module-maps -fmodules-cache-path=prebuilt
- clang -cc1 -emit-obj -o use.o use.c -fmodules -fimplicit-module-maps -fmodules-cache-path=prebuilt -DENABLE_A
- find prebuilt -name "*.pcm"
- # prebuilt/1AYBIGPM8R2GA/A-3L1K4LUA6O31.pcm
- # prebuilt/1AYBIGPM8R2GA/B-3L1K4LUA6O31.pcm
- # prebuilt/VH0YZMF1OIRK/A-3L1K4LUA6O31.pcm
- # prebuilt/VH0YZMF1OIRK/B-3L1K4LUA6O31.pcm
- clang -cc1 -emit-obj -o use.o use.c -fmodules -fimplicit-module-maps -fprebuilt-module-path=prebuilt -fprebuilt-implicit-modules
- clang -cc1 -emit-obj -o use.o use.c -fmodules -fimplicit-module-maps -fprebuilt-module-path=prebuilt -fprebuilt-implicit-modules -DENABLE_A
+Note that with explicit or prebuilt modules, we are responsible for, and should be particularly careful about the compatibility of our modules.
+Using mismatching compilation options and modules may lead to issues.
-Finally we want to allow implicit modules for configurations that were not prebuilt. When using the clang driver a module cache path is implicitly selected. Using ``-cc1``, we simply add use the ``-fmodules-cache-path`` option.
+```sh
+clang -cc1 -emit-obj use.c -fmodules -fimplicit-module-maps -fprebuilt-module-path=prebuilt -DENABLE_A
+# use.c:4:10: warning: implicit declaration of function 'a' is invalid in C99 [-Wimplicit-function-declaration]
+# return a(x);
+# ^
+# 1 warning generated.
+```
-.. code-block:: sh
+So we need to maintain multiple versions of prebuilt modules. We can do so using a manual module mapping, or pointing to a different prebuilt module cache path. For example:
- clang -cc1 -emit-obj -o use.o use.c -fmodules -fimplicit-module-maps -fprebuilt-module-path=prebuilt -fprebuilt-implicit-modules -fmodules-cache-path=cache
- clang -cc1 -emit-obj -o use.o use.c -fmodules -fimplicit-module-maps -fprebuilt-module-path=prebuilt -fprebuilt-implicit-modules -fmodules-cache-path=cache -DENABLE_A
- clang -cc1 -emit-obj -o use.o use.c -fmodules -fimplicit-module-maps -fprebuilt-module-path=prebuilt -fprebuilt-implicit-modules -fmodules-cache-path=cache -DENABLE_A -DOTHER_OPTIONS
+```sh
+rm -rf prebuilt ; mkdir prebuilt ; rm -rf prebuilt_a ; mkdir prebuilt_a
+clang -cc1 -emit-obj use.c -fmodules -fimplicit-module-maps -fmodules-cache-path=prebuilt -fdisable-module-hash
+clang -cc1 -emit-obj use.c -fmodules -fimplicit-module-maps -fmodules-cache-path=prebuilt_a -fdisable-module-hash -DENABLE_A
+clang -cc1 -emit-obj use.c -fmodules -fimplicit-module-maps -fprebuilt-module-path=prebuilt
+clang -cc1 -emit-obj use.c -fmodules -fimplicit-module-maps -fprebuilt-module-path=prebuilt_a -DENABLE_A
+```
+
+Instead of managing the different module versions manually, we can build implicit modules in a given cache path (using `-fmodules-cache-path`), and reuse them as prebuilt implicit modules by passing `-fprebuilt-module-path` and `-fprebuilt-implicit-modules`.
+
+```sh
+rm -rf prebuilt; mkdir prebuilt
+clang -cc1 -emit-obj -o use.o use.c -fmodules -fimplicit-module-maps -fmodules-cache-path=prebuilt
+clang -cc1 -emit-obj -o use.o use.c -fmodules -fimplicit-module-maps -fmodules-cache-path=prebuilt -DENABLE_A
+find prebuilt -name "*.pcm"
+# prebuilt/1AYBIGPM8R2GA/A-3L1K4LUA6O31.pcm
+# prebuilt/1AYBIGPM8R2GA/B-3L1K4LUA6O31.pcm
+# prebuilt/VH0YZMF1OIRK/A-3L1K4LUA6O31.pcm
+# prebuilt/VH0YZMF1OIRK/B-3L1K4LUA6O31.pcm
+clang -cc1 -emit-obj -o use.o use.c -fmodules -fimplicit-module-maps -fprebuilt-module-path=prebuilt -fprebuilt-implicit-modules
+clang -cc1 -emit-obj -o use.o use.c -fmodules -fimplicit-module-maps -fprebuilt-module-path=prebuilt -fprebuilt-implicit-modules -DENABLE_A
+```
+
+Finally we want to allow implicit modules for configurations that were not prebuilt. When using the clang driver a module cache path is implicitly selected. Using `-cc1`, we simply add use the `-fmodules-cache-path` option.
+
+```sh
+clang -cc1 -emit-obj -o use.o use.c -fmodules -fimplicit-module-maps -fprebuilt-module-path=prebuilt -fprebuilt-implicit-modules -fmodules-cache-path=cache
+clang -cc1 -emit-obj -o use.o use.c -fmodules -fimplicit-module-maps -fprebuilt-module-path=prebuilt -fprebuilt-implicit-modules -fmodules-cache-path=cache -DENABLE_A
+clang -cc1 -emit-obj -o use.o use.c -fmodules -fimplicit-module-maps -fprebuilt-module-path=prebuilt -fprebuilt-implicit-modules -fmodules-cache-path=cache -DENABLE_A -DOTHER_OPTIONS
+```
This way, a single directory containing multiple variants of modules can be prepared and reused. The options configuring the module cache are independent of other options.
-Module Semantics
-================
+## Module Semantics
Modules are modeled as if each submodule were a separate translation unit, and a module import makes names from the other translation unit visible. Each submodule starts with a new preprocessor state and an empty translation unit.
-.. note::
-
- This behavior is currently only approximated when building a module with submodules. Entities within a submodule that has already been built are visible when building later submodules in that module. This can lead to fragile modules that depend on the build order used for the submodules of the module, and should not be relied upon. This behavior is subject to change.
+:::{note}
+This behavior is currently only approximated when building a module with submodules. Entities within a submodule that has already been built are visible when building later submodules in that module. This can lead to fragile modules that depend on the build order used for the submodules of the module, and should not be relied upon. This behavior is subject to change.
+:::
As an example, in C, this implies that if two structs are defined in different submodules with the same name, those two types are distinct types (but may be *compatible* types if their definitions match). In C++, two structs defined with the same name in different submodules are the *same* type, and must be equivalent under C++'s One Definition Rule.
-.. note::
-
- Clang currently only performs minimal checking for violations of the One Definition Rule.
+:::{note}
+Clang currently only performs minimal checking for violations of the One Definition Rule.
+:::
If any submodule of a module is imported into any part of a program, the entire top-level module is considered to be part of the program. As a consequence of this, Clang may diagnose conflicts between an entity declared in an unimported submodule and an entity declared in the current translation unit, and Clang may inline or devirtualize based on knowledge from unimported submodules.
-Macros
-------
+### Macros
-The C and C++ preprocessor assumes that the input text is a single linear buffer, but with modules this is not the case. It is possible to import two modules that have conflicting definitions for a macro (or where one ``#define``\s a macro and the other ``#undef``\ines it). The rules for handling macro definitions in the presence of modules are as follows:
+The C and C++ preprocessor assumes that the input text is a single linear buffer, but with modules this is not the case. It is possible to import two modules that have conflicting definitions for a macro (or where one `#define`s a macro and the other `#undef`ines it). The rules for handling macro definitions in the presence of modules are as follows:
-* Each definition and undefinition of a macro is considered to be a distinct entity.
-* Such entities are *visible* if they are from the current submodule or translation unit, or if they were exported from a submodule that has been imported.
-* A ``#define X`` or ``#undef X`` directive *overrides* all definitions of ``X`` that are visible at the point of the directive.
-* A ``#define`` or ``#undef`` directive is *active* if it is visible and no visible directive overrides it.
-* A set of macro directives is *consistent* if it consists of only ``#undef`` directives, or if all ``#define`` directives in the set define the macro name to the same sequence of tokens (following the usual rules for macro redefinitions).
-* If a macro name is used and the set of active directives is not consistent, the program is ill-formed. Otherwise, the (unique) meaning of the macro name is used.
+- Each definition and undefinition of a macro is considered to be a distinct entity.
+- Such entities are *visible* if they are from the current submodule or translation unit, or if they were exported from a submodule that has been imported.
+- A `#define X` or `#undef X` directive *overrides* all definitions of `X` that are visible at the point of the directive.
+- A `#define` or `#undef` directive is *active* if it is visible and no visible directive overrides it.
+- A set of macro directives is *consistent* if it consists of only `#undef` directives, or if all `#define` directives in the set define the macro name to the same sequence of tokens (following the usual rules for macro redefinitions).
+- If a macro name is used and the set of active directives is not consistent, the program is ill-formed. Otherwise, the (unique) meaning of the macro name is used.
For example, suppose:
-* ``<stdio.h>`` defines a macro ``getc`` (and exports its ``#define``)
-* ``<cstdio>`` imports the ``<stdio.h>`` module and undefines the macro (and exports its ``#undef``)
+- `<stdio.h>` defines a macro `getc` (and exports its `#define`)
+- `<cstdio>` imports the `<stdio.h>` module and undefines the macro (and exports its `#undef`)
-The ``#undef`` overrides the ``#define``, and a source file that imports both modules *in any order* will not see ``getc`` defined as a macro.
+The `#undef` overrides the `#define`, and a source file that imports both modules *in any order* will not see `getc` defined as a macro.
-Module Map Language
-===================
+## Module Map Language
-.. warning::
-
- The module map language is not currently guaranteed to be stable between major revisions of Clang.
+:::{warning}
+The module map language is not currently guaranteed to be stable between major revisions of Clang.
+:::
The module map language describes the mapping from header files to the
logical structure of modules. To enable support for using a library as
-a module, one must write a ``module.modulemap`` file for that library. The
-``module.modulemap`` file is placed alongside the header files themselves,
+a module, one must write a `module.modulemap` file for that library. The
+`module.modulemap` file is placed alongside the header files themselves,
and is written in the module map language described below.
-.. note::
- For compatibility with previous releases, if a module map file named
- ``module.modulemap`` is not found, Clang will also search for a file named
- ``module.map``. This behavior is deprecated and we plan to eventually
- remove it.
+:::{note}
+For compatibility with previous releases, if a module map file named
+`module.modulemap` is not found, Clang will also search for a file named
+`module.map`. This behavior is deprecated and we plan to eventually
+remove it.
+:::
As an example, the module map file for the C standard library might look a bit like this:
+```{eval-rst}
.. parsed-literal::
module std [system] {
@@ -444,13 +454,15 @@ As an example, the module map file for the C standard library might look a bit l
// ...more headers follow...
}
+```
+
+Here, the top-level module `std` encompasses the whole C standard library. It has a number of submodules containing different parts of the standard library: `complex` for complex numbers, `ctype` for character types, etc. Each submodule lists one of more headers that provide the contents for that submodule. Finally, the `export *` command specifies that anything included by that submodule will be automatically re-exported.
-Here, the top-level module ``std`` encompasses the whole C standard library. It has a number of submodules containing different parts of the standard library: ``complex`` for complex numbers, ``ctype`` for character types, etc. Each submodule lists one of more headers that provide the contents for that submodule. Finally, the ``export *`` command specifies that anything included by that submodule will be automatically re-exported.
+### Lexical structure
-Lexical structure
------------------
-Module map files use a simplified form of the C99 lexer, with the same rules for identifiers, tokens, string literals, ``/* */`` and ``//`` comments. The module map language has the following reserved words; all other C identifiers are valid identifiers.
+Module map files use a simplified form of the C99 lexer, with the same rules for identifiers, tokens, string literals, `/* */` and `//` comments. The module map language has the following reserved words; all other C identifiers are valid identifiers.
+```{eval-rst}
.. parsed-literal::
``config_macros`` ``export_as`` ``private``
@@ -459,39 +471,47 @@ Module map files use a simplified form of the C99 lexer, with the same rules for
``explicit`` ``link`` ``umbrella``
``extern`` ``module`` ``use``
``export``
+```
+
+### Module map file
-Module map file
----------------
A module map file consists of a series of module declarations:
+```{eval-rst}
.. parsed-literal::
*module-map-file*:
*module-declaration**
+```
Within a module map file, modules are referred to by a *module-id*, which uses periods to separate each part of a module's name:
+```{eval-rst}
.. parsed-literal::
*module-id*:
*identifier* ('.' *identifier*)*
+```
+
+### Module declaration
-Module declaration
-------------------
A module declaration describes a module, including the headers that contribute to that module, its submodules, and other aspects of the module.
+```{eval-rst}
.. parsed-literal::
*module-declaration*:
``explicit``:sub:`opt` ``framework``:sub:`opt` ``module`` *module-id* *attributes*:sub:`opt` '{' *module-member** '}'
``extern`` ``module`` *module-id* *string-literal*
+```
The *module-id* should consist of only a single *identifier*, which provides the name of the module being defined. Each module shall have a single definition.
-The ``explicit`` qualifier can only be applied to a submodule, i.e., a module that is nested within another module. The contents of explicit submodules are only made available when the submodule itself was explicitly named in an import declaration or was re-exported from an imported module.
+The `explicit` qualifier can only be applied to a submodule, i.e., a module that is nested within another module. The contents of explicit submodules are only made available when the submodule itself was explicitly named in an import declaration or was re-exported from an imported module.
-The ``framework`` qualifier specifies that this module corresponds to a Darwin-style framework. A Darwin-style framework (used primarily on macOS and iOS) is contained entirely in directory ``Name.framework``, where ``Name`` is the name of the framework (and, therefore, the name of the module). That directory has the following layout:
+The `framework` qualifier specifies that this module corresponds to a Darwin-style framework. A Darwin-style framework (used primarily on macOS and iOS) is contained entirely in directory `Name.framework`, where `Name` is the name of the framework (and, therefore, the name of the module). That directory has the following layout:
+```{eval-rst}
.. parsed-literal::
Name.framework/
@@ -501,15 +521,17 @@ The ``framework`` qualifier specifies that this module corresponds to a Darwin-s
Frameworks/ Subdirectory containing embedded frameworks
Resources/ Subdirectory containing additional resources
Name Symbolic link to the shared library for the framework
+```
-The ``system`` attribute specifies that the module is a system module. When a system module is rebuilt, all of the module's headers will be considered system headers, which suppresses warnings. This is equivalent to placing ``#pragma GCC system_header`` in each of the module's headers. The form of attributes is described in the section Attributes_, below.
+The `system` attribute specifies that the module is a system module. When a system module is rebuilt, all of the module's headers will be considered system headers, which suppresses warnings. This is equivalent to placing `#pragma GCC system_header` in each of the module's headers. The form of attributes is described in the section [Attributes], below.
-The ``extern_c`` attribute specifies that the module contains C code that can be used from within C++. When such a module is built for use in C++ code, all of the module's headers will be treated as if they were contained within an implicit ``extern "C"`` block. An import for a module with this attribute can appear within an ``extern "C"`` block. No other restrictions are lifted, however: the module currently cannot be imported within an ``extern "C"`` block in a namespace.
+The `extern_c` attribute specifies that the module contains C code that can be used from within C++. When such a module is built for use in C++ code, all of the module's headers will be treated as if they were contained within an implicit `extern "C"` block. An import for a module with this attribute can appear within an `extern "C"` block. No other restrictions are lifted, however: the module currently cannot be imported within an `extern "C"` block in a namespace.
-The ``no_undeclared_includes`` attribute specifies that the module can only reach non-modular headers and headers from used modules. Since some headers could be present in more than one search path and map to different modules in each path, this mechanism helps clang to find the right header, i.e., prefer the one for the current module or in a submodule instead of the first usual match in the search paths.
+The `no_undeclared_includes` attribute specifies that the module can only reach non-modular headers and headers from used modules. Since some headers could be present in more than one search path and map to different modules in each path, this mechanism helps clang to find the right header, i.e., prefer the one for the current module or in a submodule instead of the first usual match in the search paths.
Modules can have a number of different kinds of members, each of which is described below:
+```{eval-rst}
.. parsed-literal::
*module-member*:
@@ -523,13 +545,15 @@ Modules can have a number of different kinds of members, each of which is descri
*link-declaration*
*config-macros-declaration*
*conflict-declaration*
+```
An extern module references a module defined by the *module-id* in a file given by the *string-literal*. The file can be referenced either by an absolute path or by a path relative to the current map file.
-Requires declaration
-~~~~~~~~~~~~~~~~~~~~
+#### Requires declaration
+
A *requires-declaration* specifies the requirements that an importing translation unit must satisfy to use the module.
+```{eval-rst}
.. parsed-literal::
*requires-declaration*:
@@ -540,79 +564,103 @@ A *requires-declaration* specifies the requirements that an importing translatio
*feature*:
``!``:sub:`opt` *identifier*
+```
-The requirements clause allows specific modules or submodules to specify that they are only accessible with certain language dialects, platforms, environments and target specific features. The feature list is a set of identifiers, defined below. If any of the features is not available in a given translation unit, that translation unit shall not import the module. When building a module for use by a compilation, submodules requiring unavailable features are ignored. The optional ``!`` indicates that a feature is incompatible with the module.
+The requirements clause allows specific modules or submodules to specify that they are only accessible with certain language dialects, platforms, environments and target specific features. The feature list is a set of identifiers, defined below. If any of the features is not available in a given translation unit, that translation unit shall not import the module. When building a module for use by a compilation, submodules requiring unavailable features are ignored. The optional `!` indicates that a feature is incompatible with the module.
The following features are defined:
altivec
- The target supports AltiVec.
+
+: The target supports AltiVec.
blocks
- The "blocks" language feature is available.
+
+: The "blocks" language feature is available.
coroutines
- Support for the coroutines TS is available.
+
+: Support for the coroutines TS is available.
cplusplus
- C++ support is available.
+
+: C++ support is available.
cplusplus11
- C++11 support is available.
+
+: C++11 support is available.
cplusplus14
- C++14 support is available.
+
+: C++14 support is available.
cplusplus17
- C++17 support is available.
+
+: C++17 support is available.
cplusplus20
- C++20 support is available.
+
+: C++20 support is available.
cplusplus23
- C++23 support is available.
+
+: C++23 support is available.
c99
- C99 support is available.
+
+: C99 support is available.
c11
- C11 support is available.
+
+: C11 support is available.
c17
- C17 support is available.
+
+: C17 support is available.
c23
- C23 support is available.
+
+: C23 support is available.
freestanding
- A freestanding environment is available.
+
+: A freestanding environment is available.
gnuinlineasm
- GNU inline ASM is available.
+
+: GNU inline ASM is available.
objc
- Objective-C support is available.
+
+: Objective-C support is available.
objc_arc
- Objective-C Automatic Reference Counting (ARC) is available
+
+: Objective-C Automatic Reference Counting (ARC) is available
opencl
- OpenCL is available
+
+: OpenCL is available
tls
- Thread local storage is available.
+
+: Thread local storage is available.
*target feature*
- A specific target feature (e.g., ``sse4``, ``avx``, ``neon``) is available.
+
+: A specific target feature (e.g., `sse4`, `avx`, `neon`) is available.
*platform/os*
- An os/platform variant (e.g. ``freebsd``, ``win32``, ``windows``, ``linux``, ``ios``, ``macos``, ``iossimulator``) is available.
+
+: An os/platform variant (e.g. `freebsd`, `win32`, `windows`, `linux`, `ios`, `macos`, `iossimulator`) is available.
*environment*
- An environment variant (e.g. ``gnu``, ``gnueabi``, ``android``, ``msvc``) is available.
-**Example:** The ``std`` module can be extended to also include C++ and C++11 headers using a *requires-declaration*:
+: An environment variant (e.g. `gnu`, `gnueabi`, `android`, `msvc`) is available.
+
+**Example:** The `std` module can be extended to also include C++ and C++11 headers using a *requires-declaration*:
+```{eval-rst}
.. parsed-literal::
module std {
@@ -628,11 +676,13 @@ tls
header "type_traits"
}
}
+```
+
+#### Header declaration
-Header declaration
-~~~~~~~~~~~~~~~~~~
A header declaration specifies that a particular header is associated with the enclosing module.
+```{eval-rst}
.. parsed-literal::
*header-declaration*:
@@ -646,96 +696,105 @@ A header declaration specifies that a particular header is associated with the e
*header-attr*:
``size`` *integer-literal*
``mtime`` *integer-literal*
+```
-A header declaration that does not contain ``exclude`` nor ``textual`` specifies a header that contributes to the enclosing module. Specifically, when the module is built, the named header will be parsed and its declarations will be (logically) placed into the enclosing submodule.
+A header declaration that does not contain `exclude` nor `textual` specifies a header that contributes to the enclosing module. Specifically, when the module is built, the named header will be parsed and its declarations will be (logically) placed into the enclosing submodule.
-A header with the ``umbrella`` specifier is called an umbrella header. An umbrella header includes all of the headers within its directory (and any subdirectories), and is typically used (in the ``#include`` world) to easily access the full API provided by a particular library. With modules, an umbrella header is a convenient shortcut that eliminates the need to write out ``header`` declarations for every library header. A given directory can only contain a single umbrella header.
+A header with the `umbrella` specifier is called an umbrella header. An umbrella header includes all of the headers within its directory (and any subdirectories), and is typically used (in the `#include` world) to easily access the full API provided by a particular library. With modules, an umbrella header is a convenient shortcut that eliminates the need to write out `header` declarations for every library header. A given directory can only contain a single umbrella header.
-.. note::
- Any headers not included by the umbrella header should have
- explicit ``header`` declarations. Use the
- ``-Wincomplete-umbrella`` warning option to ask Clang to complain
- about headers not covered by the umbrella header or the module map.
+:::{note}
+Any headers not included by the umbrella header should have
+explicit `header` declarations. Use the
+`-Wincomplete-umbrella` warning option to ask Clang to complain
+about headers not covered by the umbrella header or the module map.
+:::
-A header with the ``private`` specifier may not be included from outside the module itself.
+A header with the `private` specifier may not be included from outside the module itself.
-A header with the ``textual`` specifier will not be compiled when the module is
-built, and will be textually included if it is named by a ``#include``
+A header with the `textual` specifier will not be compiled when the module is
+built, and will be textually included if it is named by a `#include`
directive. However, it is considered to be part of the module for the purpose
-of checking *use-declaration*\s, and must still be a lexically-valid header
+of checking *use-declaration*s, and must still be a lexically-valid header
file. In the future, we intend to pre-tokenize such headers and include the
token sequence within the prebuilt module representation.
-A header with the ``exclude`` specifier is excluded from the module. It will not be included when the module is built, nor will it be considered to be part of the module, even if an ``umbrella`` directory would otherwise make it part of the module.
-
-.. note::
+A header with the `exclude` specifier is excluded from the module. It will not be included when the module is built, nor will it be considered to be part of the module, even if an `umbrella` directory would otherwise make it part of the module.
- Header paths that use ``..`` to refer to files outside of the module
- directory are deprecated in module maps that are found via implicit search
- (``-fimplicit-module-maps``). Use ``-Wmodule-map-path-outside-directory``
- to warn on such paths. Future versions of Clang may reject these paths
- in implicitly discovered module maps.
+:::{note}
+Header paths that use `..` to refer to files outside of the module
+directory are deprecated in module maps that are found via implicit search
+(`-fimplicit-module-maps`). Use `-Wmodule-map-path-outside-directory`
+to warn on such paths. Future versions of Clang may reject these paths
+in implicitly discovered module maps.
+:::
**Example:** A "X macro" header is an excellent candidate for a textual header, because it is can't be compiled standalone, and by itself does not contain any declarations.
+```{eval-rst}
.. parsed-literal::
module MyLib [system] {
textual header "xmacros.h"
}
+```
A given header shall not be referenced by more than one *header-declaration*.
-Two *header-declaration*\s, or a *header-declaration* and a ``#include``, are
+Two *header-declaration*s, or a *header-declaration* and a `#include`, are
considered to refer to the same file if the paths resolve to the same file
-and the specified *header-attr*\s (if any) match the attributes of that file,
+and the specified *header-attr*s (if any) match the attributes of that file,
even if the file is named differently (for instance, by a relative path or
via symlinks).
-.. note::
- The use of *header-attr*\s avoids the need for Clang to speculatively
- ``stat`` every header referenced by a module map. It is recommended that
- *header-attr*\s only be used in machine-generated module maps, to avoid
- mismatches between attribute values and the corresponding files.
+:::{note}
+The use of *header-attr*s avoids the need for Clang to speculatively
+`stat` every header referenced by a module map. It is recommended that
+*header-attr*s only be used in machine-generated module maps, to avoid
+mismatches between attribute values and the corresponding files.
+:::
+
+#### Umbrella directory declaration
-Umbrella directory declaration
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
An umbrella directory declaration specifies that all of the headers in the specified directory should be included within the module.
+```{eval-rst}
.. parsed-literal::
*umbrella-dir-declaration*:
``umbrella`` *string-literal*
+```
The *string-literal* refers to a directory. When the module is built, all of the header files in that directory (and its subdirectories) are included in the module.
-.. note::
-
- Umbrella directory paths that use ``..`` to refer to directories outside of
- the module directory are deprecated in implicitly discovered module maps.
- See the note in `Header declaration`_ for details.
+:::{note}
+Umbrella directory paths that use `..` to refer to directories outside of
+the module directory are deprecated in implicitly discovered module maps.
+See the note in [Header declaration] for details.
+:::
An *umbrella-dir-declaration* shall not refer to the same directory as the location of an umbrella *header-declaration*. In other words, only a single kind of umbrella can be specified for a given directory.
-.. note::
+:::{note}
+Umbrella directories are useful for libraries that have a large number of headers but do not have an umbrella header.
+:::
- Umbrella directories are useful for libraries that have a large number of headers but do not have an umbrella header.
+#### Submodule declaration
-
-Submodule declaration
-~~~~~~~~~~~~~~~~~~~~~
Submodule declarations describe modules that are nested within their enclosing module.
+```{eval-rst}
.. parsed-literal::
*submodule-declaration*:
*module-declaration*
*inferred-submodule-declaration*
+```
-A *submodule-declaration* that is a *module-declaration* is a nested module. If the *module-declaration* has a ``framework`` specifier, the enclosing module shall have a ``framework`` specifier; the submodule's contents shall be contained within the subdirectory ``Frameworks/SubName.framework``, where ``SubName`` is the name of the submodule.
+A *submodule-declaration* that is a *module-declaration* is a nested module. If the *module-declaration* has a `framework` specifier, the enclosing module shall have a `framework` specifier; the submodule's contents shall be contained within the subdirectory `Frameworks/SubName.framework`, where `SubName` is the name of the submodule.
A *submodule-declaration* that is an *inferred-submodule-declaration* describes a set of submodules that correspond to any headers that are part of the module but are not explicitly described by a *header-declaration*.
+```{eval-rst}
.. parsed-literal::
*inferred-submodule-declaration*:
@@ -743,21 +802,23 @@ A *submodule-declaration* that is an *inferred-submodule-declaration* describes
*inferred-submodule-member*:
``export`` '*'
+```
A module containing an *inferred-submodule-declaration* shall have either an umbrella header or an umbrella directory. The headers to which the *inferred-submodule-declaration* applies are exactly those headers included by the umbrella header (transitively) or included in the module because they reside within the umbrella directory (or its subdirectories).
For each header included by the umbrella header or in the umbrella directory that is not named by a *header-declaration*, a module declaration is implicitly generated from the *inferred-submodule-declaration*. The module will:
-* Have the same name as the header (without the file extension)
-* Have the ``explicit`` specifier, if the *inferred-submodule-declaration* has the ``explicit`` specifier
-* Have the ``framework`` specifier, if the
- *inferred-submodule-declaration* has the ``framework`` specifier
-* Have the attributes specified by the \ *inferred-submodule-declaration*
-* Contain a single *header-declaration* naming that header
-* Contain a single *export-declaration* ``export *``, if the \ *inferred-submodule-declaration* contains the \ *inferred-submodule-member* ``export *``
+- Have the same name as the header (without the file extension)
+- Have the `explicit` specifier, if the *inferred-submodule-declaration* has the `explicit` specifier
+- Have the `framework` specifier, if the
+ *inferred-submodule-declaration* has the `framework` specifier
+- Have the attributes specified by the *inferred-submodule-declaration*
+- Contain a single *header-declaration* naming that header
+- Contain a single *export-declaration* `export *`, if the *inferred-submodule-declaration* contains the *inferred-submodule-member* `export *`
-**Example:** If the subdirectory "MyLib" contains the headers ``A.h`` and ``B.h``, then the following module map:
+**Example:** If the subdirectory "MyLib" contains the headers `A.h` and `B.h`, then the following module map:
+```{eval-rst}
.. parsed-literal::
module MyLib {
@@ -766,9 +827,11 @@ For each header included by the umbrella header or in the umbrella directory tha
export *
}
}
+```
is equivalent to the (more verbose) module map:
+```{eval-rst}
.. parsed-literal::
module MyLib {
@@ -782,11 +845,13 @@ is equivalent to the (more verbose) module map:
export *
}
}
+```
+
+#### Export declaration
-Export declaration
-~~~~~~~~~~~~~~~~~~
An *export-declaration* specifies which imported modules will automatically be re-exported as part of a given module's API.
+```{eval-rst}
.. parsed-literal::
*export-declaration*:
@@ -796,11 +861,13 @@ An *export-declaration* specifies which imported modules will automatically be r
*identifier*
'*'
*identifier* '.' *wildcard-module-id*
+```
-The *export-declaration* names a module or a set of modules that will be re-exported to any translation unit that imports the enclosing module. Each imported module that matches the *wildcard-module-id* up to, but not including, the first ``*`` will be re-exported.
+The *export-declaration* names a module or a set of modules that will be re-exported to any translation unit that imports the enclosing module. Each imported module that matches the *wildcard-module-id* up to, but not including, the first `*` will be re-exported.
-**Example:** In the following example, importing ``MyLib.Derived`` also provides the API for ``MyLib.Base``:
+**Example:** In the following example, importing `MyLib.Derived` also provides the API for `MyLib.Base`:
+```{eval-rst}
.. parsed-literal::
module MyLib {
@@ -813,9 +880,11 @@ The *export-declaration* names a module or a set of modules that will be re-expo
export Base
}
}
+```
-Note that, if ``Derived.h`` includes ``Base.h``, one can simply use a wildcard export to re-export everything ``Derived.h`` includes:
+Note that, if `Derived.h` includes `Base.h`, one can simply use a wildcard export to re-export everything `Derived.h` includes:
+```{eval-rst}
.. parsed-literal::
module MyLib {
@@ -828,56 +897,64 @@ Note that, if ``Derived.h`` includes ``Base.h``, one can simply use a wildcard e
export *
}
}
+```
+
+:::{note}
+The wildcard export syntax `export *` re-exports all of the
+modules that were imported in the actual header file. Because
+`#include` directives are automatically mapped to module imports,
+`export *` provides the same transitive-inclusion behavior
+provided by the C preprocessor, e.g., importing a given module
+implicitly imports all of the modules on which it depends.
+Therefore, liberal use of `export *` provides excellent backward
+compatibility for programs that rely on transitive inclusion (i.e.,
+all of them).
+:::
+
+#### Re-export Declaration
-.. note::
-
- The wildcard export syntax ``export *`` re-exports all of the
- modules that were imported in the actual header file. Because
- ``#include`` directives are automatically mapped to module imports,
- ``export *`` provides the same transitive-inclusion behavior
- provided by the C preprocessor, e.g., importing a given module
- implicitly imports all of the modules on which it depends.
- Therefore, liberal use of ``export *`` provides excellent backward
- compatibility for programs that rely on transitive inclusion (i.e.,
- all of them).
-
-Re-export Declaration
-~~~~~~~~~~~~~~~~~~~~~
An *export-as-declaration* specifies that the current module will have
its interface re-exported by the named module.
+```{eval-rst}
.. parsed-literal::
*export-as-declaration*:
``export_as`` *identifier*
+```
The *export-as-declaration* names the module that the current
module will be re-exported through. Only top-level modules
can be re-exported, and any given module may only be re-exported
through a single module.
-**Example:** In the following example, the module ``MyFrameworkCore``
-will be re-exported via the module ``MyFramework``:
+**Example:** In the following example, the module `MyFrameworkCore`
+will be re-exported via the module `MyFramework`:
+```{eval-rst}
.. parsed-literal::
module MyFrameworkCore {
export_as MyFramework
}
+```
+
+#### Use declaration
-Use declaration
-~~~~~~~~~~~~~~~
A *use-declaration* specifies another module that the current top-level module
intends to use. When the option *-fmodules-decluse* is specified, a module can
only use other modules that are explicitly specified in this way.
+```{eval-rst}
.. parsed-literal::
*use-declaration*:
``use`` *module-id*
+```
**Example:** In the following example, use of A from C is not declared, so will trigger a warning.
+```{eval-rst}
.. parsed-literal::
module A {
@@ -892,37 +969,41 @@ only use other modules that are explicitly specified in this way.
header "c.h"
use B
}
+```
When compiling a source file that implements a module, use the option
-``-fmodule-name=module-id`` to indicate that the source file is logically part
+`-fmodule-name=module-id` to indicate that the source file is logically part
of that module.
The compiler at present only applies restrictions to the module directly being built.
-Link declaration
-~~~~~~~~~~~~~~~~
+#### Link declaration
+
A *link-declaration* specifies a library or framework against which a program should be linked if the enclosing module is imported in any translation unit in that program.
+```{eval-rst}
.. parsed-literal::
*link-declaration*:
``link`` ``framework``:sub:`opt` *string-literal*
+```
-The *string-literal* specifies the name of the library or framework against which the program should be linked. For example, specifying "clangBasic" would instruct the linker to link with ``-lclangBasic`` for a Unix-style linker.
+The *string-literal* specifies the name of the library or framework against which the program should be linked. For example, specifying "clangBasic" would instruct the linker to link with `-lclangBasic` for a Unix-style linker.
-A *link-declaration* with the ``framework`` specifies that the linker should link against the named framework, e.g., with ``-framework MyFramework``.
+A *link-declaration* with the `framework` specifies that the linker should link against the named framework, e.g., with `-framework MyFramework`.
-.. note::
+:::{note}
+Automatic linking with the `link` directive is not yet widely
+implemented, because it requires support from both the object file
+format and the linker. The notion is similar to Microsoft Visual
+Studio's `#pragma comment(lib...)`.
+:::
- Automatic linking with the ``link`` directive is not yet widely
- implemented, because it requires support from both the object file
- format and the linker. The notion is similar to Microsoft Visual
- Studio's ``#pragma comment(lib...)``.
+#### Configuration macros declaration
-Configuration macros declaration
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The *config-macros-declaration* specifies the set of configuration macros that have an effect on the API of the enclosing module.
+```{eval-rst}
.. parsed-literal::
*config-macros-declaration*:
@@ -930,61 +1011,67 @@ The *config-macros-declaration* specifies the set of configuration macros that h
*config-macro-list*:
*identifier* (',' *identifier*)*
+```
Each *identifier* in the *config-macro-list* specifies the name of a macro. The compiler is required to maintain different variants of the given module for differing definitions of any of the named macros.
A *config-macros-declaration* shall only be present on a top-level module, i.e., a module that is not nested within an enclosing module.
-The ``exhaustive`` attribute specifies that the list of macros in the *config-macros-declaration* is exhaustive, meaning that no other macro definition is intended to have an effect on the API of that module.
+The `exhaustive` attribute specifies that the list of macros in the *config-macros-declaration* is exhaustive, meaning that no other macro definition is intended to have an effect on the API of that module.
-.. note::
-
- The ``exhaustive`` attribute implies that any macro definitions
- for macros not listed as configuration macros should be ignored
- completely when building the module. As an optimization, the
- compiler could reduce the number of unique module variants by not
- considering these non-configuration macros. This optimization is not
- yet implemented in Clang.
+:::{note}
+The `exhaustive` attribute implies that any macro definitions
+for macros not listed as configuration macros should be ignored
+completely when building the module. As an optimization, the
+compiler could reduce the number of unique module variants by not
+considering these non-configuration macros. This optimization is not
+yet implemented in Clang.
+:::
A translation unit shall not import the same module under different definitions of the configuration macros.
-.. note::
-
- Clang implements a weak form of this requirement: the definitions
- used for configuration macros are fixed based on the definitions
- provided by the command line. If an import occurs and the definition
- of any configuration macro has changed, the compiler will produce a
- warning (under the control of ``-Wconfig-macros``).
+:::{note}
+Clang implements a weak form of this requirement: the definitions
+used for configuration macros are fixed based on the definitions
+provided by the command line. If an import occurs and the definition
+of any configuration macro has changed, the compiler will produce a
+warning (under the control of `-Wconfig-macros`).
+:::
-**Example:** A logging library might provide different API (e.g., in the form of different definitions for a logging macro) based on the ``NDEBUG`` macro setting:
+**Example:** A logging library might provide different API (e.g., in the form of different definitions for a logging macro) based on the `NDEBUG` macro setting:
+```{eval-rst}
.. parsed-literal::
module MyLogger {
umbrella header "MyLogger.h"
config_macros [exhaustive] NDEBUG
}
+```
+
+#### Conflict declarations
-Conflict declarations
-~~~~~~~~~~~~~~~~~~~~~
A *conflict-declaration* describes a case where the presence of two different modules in the same translation unit is likely to cause a problem. For example, two modules may provide similar-but-incompatible functionality.
+```{eval-rst}
.. parsed-literal::
*conflict-declaration*:
``conflict`` *module-id* ',' *string-literal*
+```
The *module-id* of the *conflict-declaration* specifies the module with which the enclosing module conflicts. The specified module shall not have been imported in the translation unit when the enclosing module is imported.
The *string-literal* provides a message to be provided as part of the compiler diagnostic when two modules conflict.
-.. note::
-
- Clang emits a warning (under the control of ``-Wmodule-conflict``)
- when a module conflict is discovered.
+:::{note}
+Clang emits a warning (under the control of `-Wmodule-conflict`)
+when a module conflict is discovered.
+:::
**Example:**
+```{eval-rst}
.. parsed-literal::
module Conflicts {
@@ -998,11 +1085,13 @@ The *string-literal* provides a message to be provided as part of the compiler d
}
}
+```
+
+### Attributes
-Attributes
-----------
Attributes are used in a number of places in the grammar to describe specific behavior of other declarations. The format of attributes is fairly simple.
+```{eval-rst}
.. parsed-literal::
*attributes*:
@@ -1010,12 +1099,13 @@ Attributes are used in a number of places in the grammar to describe specific be
*attribute*:
'[' *identifier* ']'
+```
Any *identifier* can be used as an attribute, and each declaration specifies what attributes can be applied to it.
-Private Module Map Files
-------------------------
-Module map files are typically named ``module.modulemap`` and live
+### Private Module Map Files
+
+Module map files are typically named `module.modulemap` and live
either alongside the headers they describe or in a parent directory of
the headers they describe. These module maps typically describe all of
the API for the library.
@@ -1023,11 +1113,12 @@ the API for the library.
However, in some cases, the presence or absence of particular headers
is used to distinguish between the "public" and "private" APIs of a
particular library. For example, a library may contain the headers
-``Foo.h`` and ``Foo_Private.h``, providing public and private APIs,
-respectively. Additionally, ``Foo_Private.h`` may only be available on
+`Foo.h` and `Foo_Private.h`, providing public and private APIs,
+respectively. Additionally, `Foo_Private.h` may only be available on
some versions of library, and absent in others. One cannot easily
express this with a single module map file in the library:
+```{eval-rst}
.. parsed-literal::
module Foo {
@@ -1040,114 +1131,129 @@ express this with a single module map file in the library:
...
}
+```
-because the header ``Foo_Private.h`` won't always be available. The
+because the header `Foo_Private.h` won't always be available. The
module map file could be customized based on whether
-``Foo_Private.h`` is available or not, but doing so requires custom
+`Foo_Private.h` is available or not, but doing so requires custom
build machinery.
-Private module map files, which are named ``module.private.modulemap``
-(or, for backward compatibility, ``module_private.map``), allow one to
+Private module map files, which are named `module.private.modulemap`
+(or, for backward compatibility, `module_private.map`), allow one to
augment the primary module map file with an additional modules. For
example, we would split the module map file above into two module map
files:
-.. code-block:: c
-
- /* module.modulemap */
- module Foo {
- header "Foo.h"
- }
-
- /* module.private.modulemap */
- module Foo_Private {
- header "Foo_Private.h"
- }
-
-
-When a ``module.private.modulemap`` file is found alongside a
-``module.modulemap`` file, it is loaded after the ``module.modulemap``
-file. In our example library, the ``module.private.modulemap`` file
-would be available when ``Foo_Private.h`` is available, making it
+```c
+/* module.modulemap */
+module Foo {
+ header "Foo.h"
+}
+
+/* module.private.modulemap */
+module Foo_Private {
+ header "Foo_Private.h"
+}
+```
+
+When a `module.private.modulemap` file is found alongside a
+`module.modulemap` file, it is loaded after the `module.modulemap`
+file. In our example library, the `module.private.modulemap` file
+would be available when `Foo_Private.h` is available, making it
easier to split a library's public and private APIs along header
boundaries.
When writing a private module as part of a *framework*, it's recommended that:
-* Headers for this module are present in the ``PrivateHeaders`` framework
+- Headers for this module are present in the `PrivateHeaders` framework
subdirectory.
-* The private module is defined as a *top level module* with the name of the
- public framework prefixed, like ``Foo_Private`` above. Clang has extra logic
- to work with this naming, using ``FooPrivate`` or ``Foo.Private`` (submodule)
+- The private module is defined as a *top level module* with the name of the
+ public framework prefixed, like `Foo_Private` above. Clang has extra logic
+ to work with this naming, using `FooPrivate` or `Foo.Private` (submodule)
trigger warnings and might not work as expected.
-Modularizing a Platform
-=======================
-To get any benefit out of modules, one needs to introduce module maps for software libraries starting at the bottom of the stack. This typically means introducing a module map covering the operating system's headers and the C standard library headers (in ``/usr/include``, for a Unix system).
+## Modularizing a Platform
+
+To get any benefit out of modules, one needs to introduce module maps for software libraries starting at the bottom of the stack. This typically means introducing a module map covering the operating system's headers and the C standard library headers (in `/usr/include`, for a Unix system).
-The module maps will be written using the `module map language`_, which provides the tools necessary to describe the mapping between headers and modules. Because the set of headers differs from one system to the next, the module map will likely have to be somewhat customized for, e.g., a particular distribution and version of the operating system. Moreover, the system headers themselves may require some modification, if they exhibit any anti-patterns that break modules. Such common patterns are described below.
+The module maps will be written using the [module map language], which provides the tools necessary to describe the mapping between headers and modules. Because the set of headers differs from one system to the next, the module map will likely have to be somewhat customized for, e.g., a particular distribution and version of the operating system. Moreover, the system headers themselves may require some modification, if they exhibit any anti-patterns that break modules. Such common patterns are described below.
**Macro-guarded copy-and-pasted definitions**
- System headers vend core types such as ``size_t`` for users. These types are often needed in a number of system headers, and are almost trivial to write. Hence, it is fairly common to see a definition such as the following copy-and-pasted throughout the headers:
+: System headers vend core types such as `size_t` for users. These types are often needed in a number of system headers, and are almost trivial to write. Hence, it is fairly common to see a definition such as the following copy-and-pasted throughout the headers:
+
+ ```{eval-rst}
.. parsed-literal::
#ifndef _SIZE_T
#define _SIZE_T
typedef __SIZE_TYPE__ size_t;
#endif
+ ```
- Unfortunately, when modules compiles all of the C library headers together into a single module, only the first actual type definition of ``size_t`` will be visible, and then only in the submodule corresponding to the lucky first header. Any other headers that have copy-and-pasted versions of this pattern will *not* have a definition of ``size_t``. Importing the submodule corresponding to one of those headers will therefore not yield ``size_t`` as part of the API, because it wasn't there when the header was parsed. The fix for this problem is either to pull the copied declarations into a common header that gets included everywhere ``size_t`` is part of the API, or to eliminate the ``#ifndef`` and redefine the ``size_t`` type. The latter works for C++ headers and C11, but will cause an error for non-modules C90/C99, where redefinition of ``typedefs`` is not permitted.
+ Unfortunately, when modules compiles all of the C library headers together into a single module, only the first actual type definition of `size_t` will be visible, and then only in the submodule corresponding to the lucky first header. Any other headers that have copy-and-pasted versions of this pattern will *not* have a definition of `size_t`. Importing the submodule corresponding to one of those headers will therefore not yield `size_t` as part of the API, because it wasn't there when the header was parsed. The fix for this problem is either to pull the copied declarations into a common header that gets included everywhere `size_t` is part of the API, or to eliminate the `#ifndef` and redefine the `size_t` type. The latter works for C++ headers and C11, but will cause an error for non-modules C90/C99, where redefinition of `typedefs` is not permitted.
**Conflicting definitions**
- Different system headers may provide conflicting definitions for various macros, functions, or types. These conflicting definitions don't tend to cause problems in a pre-modules world unless someone happens to include both headers in one translation unit. Since the fix is often simply "don't do that", such problems persist. Modules requires that the conflicting definitions be eliminated or that they be placed in separate modules (the former is generally the better answer).
+
+: Different system headers may provide conflicting definitions for various macros, functions, or types. These conflicting definitions don't tend to cause problems in a pre-modules world unless someone happens to include both headers in one translation unit. Since the fix is often simply "don't do that", such problems persist. Modules requires that the conflicting definitions be eliminated or that they be placed in separate modules (the former is generally the better answer).
**Missing includes**
- Headers are often missing ``#include`` directives for headers that they actually depend on. As with the problem of conflicting definitions, this only affects unlucky users who don't happen to include headers in the right order. With modules, the headers of a particular module will be parsed in isolation, so the module may fail to build if there are missing includes.
+
+: Headers are often missing `#include` directives for headers that they actually depend on. As with the problem of conflicting definitions, this only affects unlucky users who don't happen to include headers in the right order. With modules, the headers of a particular module will be parsed in isolation, so the module may fail to build if there are missing includes.
**Headers that vend multiple APIs at different times**
- Some systems have headers that contain a number of different kinds of API definitions, only some of which are made available with a given include. For example, the header may vend ``size_t`` only when the macro ``__need_size_t`` is defined before that header is included, and also vend ``wchar_t`` only when the macro ``__need_wchar_t`` is defined. Such headers are often included many times in a single translation unit, and will have no include guards. There is no sane way to map this header to a submodule. One can either eliminate the header (e.g., by splitting it into separate headers, one per actual API) or simply ``exclude`` it in the module map.
-To detect and help address some of these problems, the ``clang-tools-extra`` repository contains a ``modularize`` tool that parses a set of given headers and attempts to detect these problems and produce a report. See the tool's in-source documentation for information on how to check your system or library headers.
+: Some systems have headers that contain a number of different kinds of API definitions, only some of which are made available with a given include. For example, the header may vend `size_t` only when the macro `__need_size_t` is defined before that header is included, and also vend `wchar_t` only when the macro `__need_wchar_t` is defined. Such headers are often included many times in a single translation unit, and will have no include guards. There is no sane way to map this header to a submodule. One can either eliminate the header (e.g., by splitting it into separate headers, one per actual API) or simply `exclude` it in the module map.
+
+To detect and help address some of these problems, the `clang-tools-extra` repository contains a `modularize` tool that parses a set of given headers and attempts to detect these problems and produce a report. See the tool's in-source documentation for information on how to check your system or library headers.
+
+## Future Directions
-Future Directions
-=================
Modules support is under active development, and there are many opportunities remaining to improve it. Here are a few ideas:
**Detect unused module imports**
- Unlike with ``#include`` directives, it should be fairly simple to track whether a directly-imported module has ever been used. By doing so, Clang can emit ``unused import`` or ``unused #include`` diagnostics, including Fix-Its to remove the useless imports/includes.
+
+: Unlike with `#include` directives, it should be fairly simple to track whether a directly-imported module has ever been used. By doing so, Clang can emit `unused import` or `unused #include` diagnostics, including Fix-Its to remove the useless imports/includes.
**Fix-Its for missing imports**
- It's fairly common for one to make use of some API while writing code, only to get a compiler error about "unknown type" or "no function named" because the corresponding header has not been included. Clang can detect such cases and auto-import the required module, but should provide a Fix-It to add the import.
+
+: It's fairly common for one to make use of some API while writing code, only to get a compiler error about "unknown type" or "no function named" because the corresponding header has not been included. Clang can detect such cases and auto-import the required module, but should provide a Fix-It to add the import.
**Improve modularize**
- The modularize tool is both extremely important (for deployment) and extremely crude. It needs better UI, better detection of problems (especially for C++), and perhaps an assistant mode to help write module maps for you.
-Where To Learn More About Modules
-=================================
+: The modularize tool is both extremely important (for deployment) and extremely crude. It needs better UI, better detection of problems (especially for C++), and perhaps an assistant mode to help write module maps for you.
+
+## Where To Learn More About Modules
+
The Clang source code provides additional information about modules:
-``clang/lib/Headers/module.modulemap``
- Module map for Clang's compiler-specific header files.
+`clang/lib/Headers/module.modulemap`
+
+: Module map for Clang's compiler-specific header files.
+
+`clang/test/Modules/`
+
+: Tests specifically related to modules functionality.
+
+`clang/include/clang/Basic/Module.h`
+
+: The `Module` class in this header describes a module, and is used throughout the compiler to implement modules.
+
+`clang/include/clang/Lex/ModuleMap.h`
-``clang/test/Modules/``
- Tests specifically related to modules functionality.
+: The `ModuleMap` class in this header describes the full module map, consisting of all of the module map files that have been parsed, and providing facilities for looking up module maps and mapping between modules and headers (in both directions).
-``clang/include/clang/Basic/Module.h``
- The ``Module`` class in this header describes a module, and is used throughout the compiler to implement modules.
+[PCHInternals]
-``clang/include/clang/Lex/ModuleMap.h``
- The ``ModuleMap`` class in this header describes the full module map, consisting of all of the module map files that have been parsed, and providing facilities for looking up module maps and mapping between modules and headers (in both directions).
+: Information about the serialized AST format used for precompiled headers and modules. The actual implementation is in the `clangSerialization` library.
-PCHInternals_
- Information about the serialized AST format used for precompiled headers and modules. The actual implementation is in the ``clangSerialization`` library.
+[^footnote-1]: Automatic linking against the libraries of modules requires specific linker support, which is not widely available.
-.. [#] Automatic linking against the libraries of modules requires specific linker support, which is not widely available.
+[^footnote-2]: There are certain anti-patterns that occur in headers, particularly system headers, that cause problems for modules. The section [Modularizing a Platform] describes some of them.
-.. [#] There are certain anti-patterns that occur in headers, particularly system headers, that cause problems for modules. The section `Modularizing a Platform`_ describes some of them.
+[^footnote-3]: The second instance is actually a new thread within the current process, not a separate process. However, the original compiler instance is blocked on the execution of this thread.
-.. [#] The second instance is actually a new thread within the current process, not a separate process. However, the original compiler instance is blocked on the execution of this thread.
+[^footnote-4]: The preprocessing context in which the modules are parsed is actually dependent on the command-line options provided to the compiler, including the language dialect and any `-D` options. However, the compiled modules for different command-line options are kept distinct, and any preprocessor directives that occur within the translation unit are ignored. See the section on the [Configuration macros declaration] for more information.
-.. [#] The preprocessing context in which the modules are parsed is actually dependent on the command-line options provided to the compiler, including the language dialect and any ``-D`` options. However, the compiled modules for different command-line options are kept distinct, and any preprocessor directives that occur within the translation unit are ignored. See the section on the `Configuration macros declaration`_ for more information.
+[pchinternals]: PCHInternals.html
-.. _PCHInternals: PCHInternals.html
diff --git a/clang/docs/OpenCLSupport.md b/clang/docs/OpenCLSupport.md
index 6ffb646fe0246..87cf6df434af1 100644
--- a/clang/docs/OpenCLSupport.md
+++ b/clang/docs/OpenCLSupport.md
@@ -1,205 +1,200 @@
-.. raw:: html
-
- <style type="text/css">
- .none { background-color: #FFCCCC }
- .part { background-color: #FFFF99 }
- .good { background-color: #CCFF99 }
- </style>
-
+```{raw} html
+<style type="text/css">
+ .none { background-color: #FFCCCC }
+ .part { background-color: #FFFF99 }
+ .good { background-color: #CCFF99 }
+</style>
+```
+
+```{eval-rst}
.. role:: none
+```
+
+```{eval-rst}
.. role:: part
+```
+
+```{eval-rst}
.. role:: good
+```
-.. contents::
- :local:
+```{contents}
+:local: true
+```
-==================
-OpenCL Support
-==================
+# OpenCL Support
Clang has complete support of OpenCL C versions from 1.0 to 3.0.
-Support for OpenCL 3.0 is in experimental phase (:ref:`OpenCL 3.0 <opencl_300>`).
+Support for OpenCL 3.0 is in experimental phase ({ref}`OpenCL 3.0 <opencl_300>`).
-Clang also supports :ref:`the C++ for OpenCL kernel language <cxx_for_opencl_impl>`.
+Clang also supports {ref}`the C++ for OpenCL kernel language <cxx_for_opencl_impl>`.
-There are also other :ref:`new and experimental features <opencl_experimenal>`
+There are also other {ref}`new and experimental features <opencl_experimenal>`
available.
-Details about usage of clang for OpenCL can be found in :doc:`UsersManual`.
-
-Missing features or with limited support
-========================================
+Details about usage of clang for OpenCL can be found in {doc}`UsersManual`.
-- For general issues and bugs with OpenCL in clang refer to `the GitHub issue
- list
- <https://github.com/llvm/llvm-project/issues?q=is%3Aopen+is%3Aissue+label%3Aopencl>`__.
+## Missing features or with limited support
-- Command-line flag :option:`-cl-ext` (used to override extensions/
+- For general issues and bugs with OpenCL in clang refer to [the GitHub issue
+ list](https://github.com/llvm/llvm-project/issues?q=is%3Aopen+is%3Aissue+label%3Aopencl).
+- Command-line flag {option}`-cl-ext` (used to override extensions/
features supported by a target) is missing support of some functionality i.e. that is
- implemented fully through libraries (see :ref:`library-based features and
+ implemented fully through libraries (see {ref}`library-based features and
extensions <opencl_ext_libs>`).
-Internals Manual
-================
+## Internals Manual
This section acts as internal documentation for OpenCL features design
as well as some important implementation aspects. It is primarily targeted
at the advanced users and the toolchain developers integrating frontend
functionality as a component.
-OpenCL Metadata
----------------
+### OpenCL Metadata
Clang uses metadata to provide additional OpenCL semantics in IR needed for
backends and OpenCL runtime.
Each kernel will have function metadata attached to it, specifying the arguments.
Kernel argument metadata is used to provide source level information for querying
-at runtime, for example using the `clGetKernelArgInfo
-<https://www.khronos.org/registry/OpenCL/specs/opencl-1.2.pdf#167>`_
+at runtime, for example using the [clGetKernelArgInfo](https://www.khronos.org/registry/OpenCL/specs/opencl-1.2.pdf#167)
call.
-Note that ``-cl-kernel-arg-info`` enables more information about the original
+Note that `-cl-kernel-arg-info` enables more information about the original
kernel code to be added e.g. kernel parameter names will appear in the OpenCL
metadata along with other information.
The IDs used to encode the OpenCL's logical address spaces in the argument info
metadata follows the SPIR address space mapping as defined in the SPIR
-specification `section 2.2
-<https://www.khronos.org/registry/spir/specs/spir_spec-2.0.pdf#18>`_
+specification [section 2.2](https://www.khronos.org/registry/spir/specs/spir_spec-2.0.pdf#18)
-OpenCL Specific Options
------------------------
+### OpenCL Specific Options
-In addition to the options described in :doc:`UsersManual` there are the
+In addition to the options described in {doc}`UsersManual` there are the
following options specific to the OpenCL frontend.
All the options in this section are frontend-only and therefore if used
-with regular clang driver they require frontend forwarding, e.g. ``-cc1``
-or ``-Xclang``.
+with regular clang driver they require frontend forwarding, e.g. `-cc1`
+or `-Xclang`.
-.. _opencl_finclude_default_header:
+(opencl-finclude-default-header)=
+```{eval-rst}
.. option:: -finclude-default-header
+```
Adds most of builtin types and function declarations during compilations. By
default the OpenCL headers are not loaded by the frontend and therefore certain
builtin types and most of builtin functions are not declared. To load them
-automatically this flag can be passed to the frontend (see also :ref:`the
+automatically this flag can be passed to the frontend (see also {ref}`the
section on the OpenCL Header <opencl_header>`):
- .. code-block:: console
-
- $ clang -Xclang -finclude-default-header test.cl
+> ```console
+> $ clang -Xclang -finclude-default-header test.cl
+> ```
Alternatively the internal header `opencl-c.h` containing the declarations
-can be included manually using ``-include`` or ``-I`` followed by the path
+can be included manually using `-include` or `-I` followed by the path
to the header location. The header can be found in the clang source tree or
installation directory.
- .. code-block:: console
-
- $ clang -I<path to clang sources>/lib/Headers/opencl-c.h test.cl
- $ clang -I<path to clang installation>/lib/clang/<llvm version>/include/opencl-c.h/opencl-c.h test.cl
+> ```console
+> $ clang -I<path to clang sources>/lib/Headers/opencl-c.h test.cl
+> $ clang -I<path to clang installation>/lib/clang/<llvm version>/include/opencl-c.h/opencl-c.h test.cl
+> ```
In this example it is assumed that the kernel code contains
-``#include <opencl-c.h>`` just as a regular C include.
+`#include <opencl-c.h>` just as a regular C include.
-Because the header is very large and long to parse, PCH (:doc:`PCHInternals`)
-and modules (:doc:`Modules`) can be used internally to improve the compilation
+Because the header is very large and long to parse, PCH ({doc}`PCHInternals`)
+and modules ({doc}`Modules`) can be used internally to improve the compilation
speed.
To enable modules for OpenCL:
- .. code-block:: console
-
- $ clang --target=spir-unknown-unknown -c -emit-llvm -Xclang -finclude-default-header -fmodules -fimplicit-module-maps -fmodules-cache-path=<path to the generated module> test.cl
+> ```console
+> $ clang --target=spir-unknown-unknown -c -emit-llvm -Xclang -finclude-default-header -fmodules -fimplicit-module-maps -fmodules-cache-path=<path to the generated module> test.cl
+> ```
Another way to circumvent long parsing latency for the OpenCL builtin
-declarations is to use mechanism enabled by :ref:`-fdeclare-opencl-builtins
+declarations is to use mechanism enabled by {ref}`-fdeclare-opencl-builtins
<opencl_fdeclare_opencl_builtins>` flag that is available as an alternative
feature.
-.. _opencl_fdeclare_opencl_builtins:
+(opencl-fdeclare-opencl-builtins)=
+```{eval-rst}
.. option:: -fdeclare-opencl-builtins
+```
In addition to regular header includes with builtin types and functions using
-:ref:`-finclude-default-header <opencl_finclude_default_header>`, clang
+{ref}`-finclude-default-header <opencl_finclude_default_header>`, clang
supports a fast mechanism to declare builtin functions with
-``-fdeclare-opencl-builtins``. This does not declare the builtin types and
-therefore it has to be used in combination with ``-finclude-default-header``
+`-fdeclare-opencl-builtins`. This does not declare the builtin types and
+therefore it has to be used in combination with `-finclude-default-header`
if full functionality is required.
**Example of Use**:
- .. code-block:: console
-
- $ clang -Xclang -fdeclare-opencl-builtins test.cl
+> ```console
+> $ clang -Xclang -fdeclare-opencl-builtins test.cl
+> ```
-.. _opencl_fake_address_space_map:
+(opencl-fake-address-space-map)=
+```{eval-rst}
.. option:: -ffake-address-space-map
+```
Overrides the target address space map with a fake map.
This allows adding explicit address space IDs to the bitcode for non-segmented
memory architectures that do not have separate IDs for each of the OpenCL
-logical address spaces by default. Passing ``-ffake-address-space-map`` will
+logical address spaces by default. Passing `-ffake-address-space-map` will
add/override address spaces of the target compiled for with the following values:
-``1-global``, ``2-constant``, ``3-local``, ``4-generic``. The private address
+`1-global`, `2-constant`, `3-local`, `4-generic`. The private address
space is represented by the absence of an address space attribute in the IR (see
-also :ref:`the section on the address space attribute <opencl_addrsp>`).
+also {ref}`the section on the address space attribute <opencl_addrsp>`).
- .. code-block:: console
+> ```console
+> $ clang -cc1 -ffake-address-space-map test.cl
+> ```
- $ clang -cc1 -ffake-address-space-map test.cl
+(opencl-builtins)=
-.. _opencl_builtins:
-
-OpenCL builtins
----------------
+### OpenCL builtins
**Clang builtins**
There are some standard OpenCL functions that are implemented as Clang builtins:
-- All pipe functions from `section 6.13.16.2/6.13.16.3
- <https://www.khronos.org/registry/cl/specs/opencl-2.0-openclc.pdf#160>`_ of
+- All pipe functions from [section 6.13.16.2/6.13.16.3](https://www.khronos.org/registry/cl/specs/opencl-2.0-openclc.pdf#160) of
the OpenCL v2.0 kernel language specification.
-
-- Address space qualifier conversion functions ``to_global``/``to_local``/``to_private``
- from `section 6.13.9
- <https://www.khronos.org/registry/cl/specs/opencl-2.0-openclc.pdf#101>`_.
-
-- All the ``enqueue_kernel`` functions from `section 6.13.17.1
- <https://www.khronos.org/registry/cl/specs/opencl-2.0-openclc.pdf#164>`_ and
- enqueue query functions from `section 6.13.17.5
- <https://www.khronos.org/registry/cl/specs/opencl-2.0-openclc.pdf#171>`_.
+- Address space qualifier conversion functions `to_global`/`to_local`/`to_private`
+ from [section 6.13.9](https://www.khronos.org/registry/cl/specs/opencl-2.0-openclc.pdf#101).
+- All the `enqueue_kernel` functions from [section 6.13.17.1](https://www.khronos.org/registry/cl/specs/opencl-2.0-openclc.pdf#164) and
+ enqueue query functions from [section 6.13.17.5](https://www.khronos.org/registry/cl/specs/opencl-2.0-openclc.pdf#171).
**Fast builtin function declarations**
The implementation of the fast builtin function declarations (available via the
-:ref:`-fdeclare-opencl-builtins option <opencl_fdeclare_opencl_builtins>`) consists
+{ref}`-fdeclare-opencl-builtins option <opencl_fdeclare_opencl_builtins>`) consists
of the following main components:
-- A TableGen definitions file ``OpenCLBuiltins.td``. This contains a compact
- representation of the supported builtin functions. When adding new builtin
+- A TableGen definitions file `OpenCLBuiltins.td`. This contains a compact
+ representation of the supported builtin functions. When adding new builtin
function declarations, this is normally the only file that needs modifying.
-
-- A Clang TableGen emitter defined in ``ClangOpenCLBuiltinEmitter.cpp``. During
+- A Clang TableGen emitter defined in `ClangOpenCLBuiltinEmitter.cpp`. During
Clang build time, the emitter reads the TableGen definition file and
- generates ``OpenCLBuiltins.inc``. This generated file contains various tables
+ generates `OpenCLBuiltins.inc`. This generated file contains various tables
and functions that capture the builtin function data from the TableGen
definitions in a compact manner.
-
-- OpenCL specific code in ``SemaLookup.cpp``. When ``Sema::LookupBuiltin``
+- OpenCL specific code in `SemaLookup.cpp`. When `Sema::LookupBuiltin`
encounters a potential builtin function, it will check if the name corresponds
- to a valid OpenCL builtin function. If so, all overloads of the function are
- inserted using ``InsertOCLBuiltinDeclarationsFromTable`` and overload
+ to a valid OpenCL builtin function. If so, all overloads of the function are
+ inserted using `InsertOCLBuiltinDeclarationsFromTable` and overload
resolution takes place.
-OpenCL Extensions and Features
-------------------------------
+### OpenCL Extensions and Features
Clang implements various extensions to OpenCL kernel languages.
@@ -210,8 +205,7 @@ assessment of complexity for C/C++ based compilers. Alternatively, the
documentation can be accepted in a format of a draft that can be further
refined during the implementation.
-Implementation guidelines
-^^^^^^^^^^^^^^^^^^^^^^^^^
+#### Implementation guidelines
This section explains how to extend clang with the new functionality.
@@ -222,42 +216,41 @@ code. This also means that the associated macro indicating the presence of the
extension should be added to clang.
The default flow for adding a new extension into the frontend is to
-modify `OpenCLExtensions.def
-<https://github.com/llvm/llvm-project/blob/main/clang/include/clang/Basic/OpenCLExtensions.def>`__,
+modify [OpenCLExtensions.def](https://github.com/llvm/llvm-project/blob/main/clang/include/clang/Basic/OpenCLExtensions.def),
containing the list of all extensions and optional features supported by
the frontend.
This will add the macro automatically and also add a field in the target
-options ``clang::TargetOptions::OpenCLFeaturesMap`` to control the exposure
+options `clang::TargetOptions::OpenCLFeaturesMap` to control the exposure
of the new extension during the compilation.
Note that by default targets like `SPIR-V`, `SPIR` or `X86` expose all the OpenCL
extensions. For all other targets the configuration has to be made explicitly.
Note that the target extension support performed by clang can be overridden
-with :option:`-cl-ext` command-line flags.
+with {option}`-cl-ext` command-line flags.
-.. _opencl_ext_libs:
+(opencl-ext-libs)=
**Library functionality**
If an extension adds functionality that does not modify standard language
parsing it may not require modifying anything other than header files and
-``OpenCLBuiltins.td`` detailed in :ref:`OpenCL builtins <opencl_builtins>`.
+`OpenCLBuiltins.td` detailed in {ref}`OpenCL builtins <opencl_builtins>`.
Most commonly such extensions add functionality via libraries (by adding
non-native types or functions) parsed regularly. Similar to other languages this
is the most common way to add new functionality.
Clang has standard headers where new types and functions are being added,
for more details refer to
-:ref:`the section on the OpenCL Header <opencl_header>`.
+{ref}`the section on the OpenCL Header <opencl_header>`.
**Pragmas**
Some extensions alter standard parsing dynamically via pragmas.
Clang provides a mechanism to add the standard extension pragma
-``OPENCL EXTENSION`` by setting a dedicated flag in the extension list entry of
-``OpenCLExtensions.def``. Note that there is no default behavior for the
+`OPENCL EXTENSION` by setting a dedicated flag in the extension list entry of
+`OpenCLExtensions.def`. Note that there is no default behavior for the
standard extension pragmas as it is not specified (for the standards up to and
including version 3.0) in a sufficient level of detail and, therefore,
there is no default functionality provided by clang.
@@ -274,19 +267,18 @@ the use of types or functions. This functionality is not guaranteed to remain in
future releases. However, any future changes should not affect backward
compatibility.
-.. _opencl_addrsp:
+(opencl-addrsp)=
-Address spaces attribute
-------------------------
+### Address spaces attribute
-Clang has arbitrary address space support using the ``address_space(N)``
-attribute, where ``N`` is an integer number in the range specified in the
+Clang has arbitrary address space support using the `address_space(N)`
+attribute, where `N` is an integer number in the range specified in the
Clang source code. This addresses spaces can be used along with the OpenCL
address spaces however when such addresses spaces converted to/from OpenCL
address spaces the behavior is not governed by OpenCL specification.
An OpenCL implementation provides a list of standard address spaces using
-keywords: ``private``, ``local``, ``global``, and ``generic``. In the AST and
+keywords: `private`, `local`, `global`, and `generic`. In the AST and
in the IR each of the address spaces will be represented by unique number
provided in the Clang source code. The specific IDs for an address space do not
have to match between the AST and the IR. Typically in the AST address space
@@ -300,63 +292,52 @@ to keep it and only lower to reflect physical memory segments in the late
machine passes. The mapping between logical and target address spaces is
specified in the Clang's source code.
-.. _cxx_for_opencl_impl:
+(cxx-for-opencl-impl)=
-C++ for OpenCL Implementation Status
-====================================
+## C++ for OpenCL Implementation Status
-Clang implements language versions 1.0 and 2021 published in `the official
-release of C++ for OpenCL Documentation
-<https://github.com/KhronosGroup/OpenCL-Docs/releases/tag/cxxforopencl-docrev2021.12>`_.
+Clang implements language versions 1.0 and 2021 published in [the official
+release of C++ for OpenCL Documentation](https://github.com/KhronosGroup/OpenCL-Docs/releases/tag/cxxforopencl-docrev2021.12).
-Limited support of experimental C++ libraries is described in the :ref:`experimental features <opencl_experimenal>`.
+Limited support of experimental C++ libraries is described in the {ref}`experimental features <opencl_experimenal>`.
GitHub issues for this functionality are typically prefixed
-with '[C++4OpenCL]' - click `here
-<https://github.com/llvm/llvm-project/issues?q=is%3Aissue+is%3Aopen+%5BC%2B%2B4OpenCL%5D>`__
+with '[C++4OpenCL]' - click [here](https://github.com/llvm/llvm-project/issues?q=is%3Aissue+is%3Aopen+%5BC%2B%2B4OpenCL%5D)
to view the full bug list.
-
-Missing features or with limited support
-----------------------------------------
+### Missing features or with limited support
- Support of C++ for OpenCL 2021 is currently in experimental phase. Refer to
- :ref:`OpenCL 3.0 status <opencl_300>` for details of common missing
+ {ref}`OpenCL 3.0 status <opencl_300>` for details of common missing
functionality from OpenCL 3.0.
-
- IR generation for non-trivial global destructors is incomplete (See:
- `PR48047 <https://llvm.org/PR48047>`_).
-
-- Support of `destructors with non-default address spaces
- <https://www.khronos.org/opencl/assets/CXX_for_OpenCL.html#_construction_initialization_and_destruction>`_
- is incomplete (See: `D109609 <https://reviews.llvm.org/D109609>`_).
+ [PR48047](https://llvm.org/PR48047)).
+- Support of [destructors with non-default address spaces](https://www.khronos.org/opencl/assets/CXX_for_OpenCL.html#_construction_initialization_and_destruction)
+ is incomplete (See: [D109609](https://reviews.llvm.org/D109609)).
-.. _opencl_300:
+(opencl-300)=
-OpenCL C 3.0 Usage
-==================
+## OpenCL C 3.0 Usage
OpenCL C 3.0 language standard makes most OpenCL C 2.0 features optional. Optional
functionality in OpenCL C 3.0 is indicated with the presence of feature-test macros
-(list of feature-test macros is `here <https://www.khronos.org/registry/OpenCL/specs/3.0-unified/html/OpenCL_C.html#features>`__).
-Command-line flag :option:`-cl-ext` can be used to override features supported by a target.
+(list of feature-test macros is [here](https://www.khronos.org/registry/OpenCL/specs/3.0-unified/html/OpenCL_C.html#features)).
+Command-line flag {option}`-cl-ext` can be used to override features supported by a target.
For cases when there is an associated extension for a specific feature (fp64 and 3d image writes)
user should specify both (extension and feature) in command-line flag:
- .. code-block:: console
-
- $ clang -cl-std=CL3.0 -cl-ext=+cl_khr_fp64,+__opencl_c_fp64 ...
- $ clang -cl-std=CL3.0 -cl-ext=-cl_khr_fp64,-__opencl_c_fp64 ...
+> ```console
+> $ clang -cl-std=CL3.0 -cl-ext=+cl_khr_fp64,+__opencl_c_fp64 ...
+> $ clang -cl-std=CL3.0 -cl-ext=-cl_khr_fp64,-__opencl_c_fp64 ...
+> ```
-
-
-OpenCL C 3.0 Implementation Status
-----------------------------------
+### OpenCL C 3.0 Implementation Status
The following table provides an overview of features in OpenCL C 3.0 and their
implementation status.
+```{eval-rst}
+------------------------------+-------------------------+-----------------------------------------+----------------------+--------------------------------------------------------------------------------------------------------------------------------+
| Category | Feature | Status | Reviews |
+==============================+=========================+=========================================+======================+================================================================================================================================+
@@ -394,30 +375,26 @@ implementation status.
+------------------------------+-------------------------+-----------------------------------------+----------------------+--------------------------------------------------------------------------------------------------------------------------------+
| New functionality | Atomic mem scopes: subgroup, all devices including functions | :good:`done` | https://reviews.llvm.org/D103241 |
+------------------------------+-------------------------+-----------------------------------------+----------------------+--------------------------------------------------------------------------------------------------------------------------------+
+```
-.. _opencl_experimenal:
+(opencl-experimenal)=
-Experimental features
-=====================
+## Experimental features
Clang provides the following new WIP features for the developers to experiment
and provide early feedback or contribute with further improvements.
-Feel free to contact us on `the Discourse forums (Clang Frontend category)
-<https://discourse.llvm.org/c/clang/6>`_ or file `a GitHub issue
-<https://github.com/llvm/llvm-project/issues/new>`_.
+Feel free to contact us on [the Discourse forums (Clang Frontend category)](https://discourse.llvm.org/c/clang/6) or file [a GitHub issue](https://github.com/llvm/llvm-project/issues/new).
-.. _opencl_experimental_cxxlibs:
+(opencl-experimental-cxxlibs)=
-C++ libraries for OpenCL
-------------------------
+### C++ libraries for OpenCL
-There is ongoing work to support C++ standard libraries from `LLVM's libcxx
-<https://libcxx.llvm.org/>`_ in OpenCL kernel code using C++ for OpenCL mode.
+There is ongoing work to support C++ standard libraries from [LLVM's libcxx](https://libcxx.llvm.org/) in OpenCL kernel code using C++ for OpenCL mode.
It is currently possible to include `type_traits` from C++17 in the kernel
sources when the following clang extensions are enabled
-``__cl_clang_function_pointers`` and ``__cl_clang_variadic_functions``,
-see :doc:`LanguageExtensions` for more details. The use of non-conformant
+`__cl_clang_function_pointers` and `__cl_clang_variadic_functions`,
+see {doc}`LanguageExtensions` for more details. The use of non-conformant
features enabled by the extensions does not expose non-conformant behavior
beyond the compilation i.e. does not get generated in IR or binary.
The extension only appear in metaprogramming
@@ -430,30 +407,31 @@ after the header include.
The example of kernel code with `type_traits` is illustrated here.
-.. code-block:: c++
-
- #pragma OPENCL EXTENSION __cl_clang_function_pointers : enable
- #pragma OPENCL EXTENSION __cl_clang_variadic_functions : enable
- #include <type_traits>
- #pragma OPENCL EXTENSION __cl_clang_function_pointers : disable
- #pragma OPENCL EXTENSION __cl_clang_variadic_functions : disable
+```c++
+#pragma OPENCL EXTENSION __cl_clang_function_pointers : enable
+#pragma OPENCL EXTENSION __cl_clang_variadic_functions : enable
+#include <type_traits>
+#pragma OPENCL EXTENSION __cl_clang_function_pointers : disable
+#pragma OPENCL EXTENSION __cl_clang_variadic_functions : disable
- using sint_type = std::make_signed<unsigned int>::type;
+using sint_type = std::make_signed<unsigned int>::type;
- __kernel void foo() {
- static_assert(!std::is_same<sint_type, unsigned int>::value);
- }
+__kernel void foo() {
+ static_assert(!std::is_same<sint_type, unsigned int>::value);
+}
+```
The possible clang invocation to compile the example is as follows:
- .. code-block:: console
-
- $ clang -I<path to libcxx checkout or installation>/include test.clcpp
+> ```console
+> $ clang -I<path to libcxx checkout or installation>/include test.clcpp
+> ```
Note that `type_traits` is a header only library and therefore no extra
linking step against the standard libraries is required. See full example
-in `Compiler Explorer <https://godbolt.org/z/5WbnTfb65>`_.
+in [Compiler Explorer](https://godbolt.org/z/5WbnTfb65).
More OpenCL specific C++ library implementations built on top of libcxx
-are available in `libclcxx <https://github.com/KhronosGroup/libclcxx>`_
+are available in [libclcxx](https://github.com/KhronosGroup/libclcxx)
project.
+
diff --git a/clang/docs/OpenMPSupport.md b/clang/docs/OpenMPSupport.md
index 0c21aa41ff269..501da6ca5b413 100644
--- a/clang/docs/OpenMPSupport.md
+++ b/clang/docs/OpenMPSupport.md
@@ -1,21 +1,28 @@
-.. raw:: html
-
- <style type="text/css">
- .none { background-color: #FFCCCC }
- .part { background-color: #FFFF99 }
- .good { background-color: #CCFF99 }
- </style>
-
+```{raw} html
+<style type="text/css">
+ .none { background-color: #FFCCCC }
+ .part { background-color: #FFFF99 }
+ .good { background-color: #CCFF99 }
+</style>
+```
+
+```{eval-rst}
.. role:: none
+```
+
+```{eval-rst}
.. role:: part
+```
+
+```{eval-rst}
.. role:: good
+```
-.. contents::
- :local:
+```{contents}
+:local: true
+```
-==============
-OpenMP Support
-==============
+# OpenMP Support
Clang fully supports OpenMP 4.5, almost all of 5.0 and most of 5.1/2.
Clang supports offloading to X86_64, AArch64, PPC64[LE], NVIDIA GPUs (all models) and AMD GPUs (all models).
@@ -25,15 +32,14 @@ Interface (OMPT) on x86, x86_64, AArch64, and PPC64 on Linux, Windows, and macOS
OMPT is also supported for NVIDIA and AMD GPUs.
For the list of supported features from OpenMP 5.0 and 5.1
-see `OpenMP implementation details`_ and `OpenMP 51 implementation details`_.
+see [OpenMP implementation details] and [OpenMP 51 implementation details].
+
+## General improvements
-General improvements
-====================
- New collapse clause scheme to avoid expensive remainder operations.
Compute loop index variables after collapsing a loop nest via the
collapse clause by replacing the expensive remainder operation with
multiplications and additions.
-
- When using the collapse clause on a loop nest the default behavior
is to automatically extend the representation of the loop counter to
64 bits for the cases where the sizes of the collapsed loops are not
@@ -41,12 +47,9 @@ General improvements
at most 32 bits, compile your program with the
`-fopenmp-optimistic-collapse`.
+## GPU devices support
-GPU devices support
-===================
-
-Data-sharing modes
-------------------
+### Data-sharing modes
Clang supports two data-sharing models for Cuda devices: `Generic` and `Cuda`
modes. The default mode is `Generic`. `Cuda` mode can give an additional
@@ -58,657 +61,273 @@ between the threads in the parallel regions. Often, the optimizer is able to
reduce the cost of `Generic` mode to the level of `Cuda` mode, but the flag,
as well as other assumption flags, can be used for tuning.
-Features not supported or with limited support for Cuda devices
----------------------------------------------------------------
+### Features not supported or with limited support for Cuda devices
- Cancellation constructs are not supported.
-
- Doacross loop nest is not supported.
-
- User-defined reductions are supported only for trivial types.
-
- Nested parallelism: inner parallel regions are executed sequentially.
-
- Debug information for OpenMP target regions is supported, but sometimes it may
be required to manually specify the address class of the inspected variables.
In some cases the local variables are actually allocated in the global memory,
but the debug info may be not aware of it.
+(openmp-implementation-details)=
-.. _OpenMP implementation details:
-
-OpenMP 5.0 Implementation Details
-=================================
+## OpenMP 5.0 Implementation Details
The following table provides a quick overview over various OpenMP 5.0 features
and their implementation status. Please post on the
-`Discourse forums (Runtimes - OpenMP category)`_ for more
+[Discourse forums (Runtimes - OpenMP category)] for more
information or if you want to help with the
implementation.
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-|Category | Feature | Status | Reviews |
-+==============================+==============================================================+==========================+=======================================================================+
-| loop | support != in the canonical loop form | :good:`done` | D54441 |
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-| loop | #pragma omp loop (directive) | :part:`partial` | D145823 (combined forms) |
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-| loop | #pragma omp loop bind | :part:`worked on` | D144634 (needs review) |
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-| loop | collapse imperfectly nested loop | :good:`done` | |
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-| loop | collapse non-rectangular nested loop | :good:`done` | |
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-| loop | C++ range-base for loop | :good:`done` | |
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-| loop | clause: if for SIMD directives | :good:`done` | |
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-| loop | inclusive scan (matching C++17 PSTL) | :good:`done` | |
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-| memory management | memory allocators | :good:`done` | r341687,r357929 |
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-| memory management | allocate directive and allocate clause | :good:`done` | r355614,r335952 |
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-| OMPD | OMPD interfaces | :good:`done` | https://reviews.llvm.org/D99914 (Supports only HOST(CPU) and Linux |
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-| OMPT | OMPT interfaces (callback support) | :good:`done` | |
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-| thread affinity | thread affinity | :good:`done` | |
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-| task | taskloop reduction | :good:`done` | |
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-| task | task affinity | :part:`not upstream` | https://github.com/jklinkenberg/openmp/tree/task-affinity |
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-| task | clause: depend on the taskwait construct | :good:`done` | D113540 (regular codegen only) |
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-| task | depend objects and detachable tasks | :good:`done` | |
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-| task | mutexinoutset dependence-type for tasks | :good:`done` | D53380,D57576 |
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-| task | combined taskloop constructs | :good:`done` | |
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-| task | master taskloop | :good:`done` | |
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-| task | parallel master taskloop | :good:`done` | |
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-| task | master taskloop simd | :good:`done` | |
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-| task | parallel master taskloop simd | :good:`done` | |
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-| SIMD | atomic and simd constructs inside SIMD code | :good:`done` | |
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-| SIMD | SIMD nontemporal | :good:`done` | |
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-| device | infer target functions from initializers | :part:`worked on` | |
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-| device | infer target variables from initializers | :good:`done` | D146418 |
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-| device | OMP_TARGET_OFFLOAD environment variable | :good:`done` | D50522 |
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-| device | support full 'defaultmap' functionality | :good:`done` | D69204 |
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-| device | device specific functions | :good:`done` | |
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-| device | clause: device_type | :good:`done` | |
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-| device | clause: extended device | :good:`done` | |
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-| device | clause: uses_allocators clause | :good:`done` | https://github.com/llvm/llvm-project/pull/157025 |
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-| device | clause: in_reduction | :part:`worked on` | r308768 |
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-| device | omp_get_device_num() | :good:`done` | D54342,D128347 |
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-| device | structure mapping of references | :none:`unclaimed` | |
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-| device | nested target declare | :good:`done` | D51378 |
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-| device | implicitly map 'this' (this[:1]) | :good:`done` | D55982 |
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-| device | allow access to the reference count (omp_target_is_present) | :good:`done` | |
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-| device | requires directive | :good:`done` | |
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-| device | clause: unified_shared_memory | :good:`done` | D52625,D52359 |
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-| device | clause: unified_address | :part:`partial` | |
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-| device | clause: reverse_offload | :part:`partial` | D52780,D155003 |
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-| device | clause: atomic_default_mem_order | :good:`done` | D53513 |
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-| device | clause: dynamic_allocators | :part:`unclaimed parts` | D53079 |
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-| device | user-defined mappers | :good:`done` | D56326,D58638,D58523,D58074,D60972,D59474 |
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-| device | map array-section with implicit mapper | :good:`done` | https://github.com/llvm/llvm-project/pull/101101 |
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-| device | mapping lambda expression | :good:`done` | D51107 |
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-| device | clause: use_device_addr for target data | :good:`done` | |
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-| device | support close modifier on map clause | :good:`done` | D55719,D55892 |
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-| device | teams construct on the host device | :good:`done` | r371553 |
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-| device | support non-contiguous array sections for target update | :good:`done` | https://github.com/llvm/llvm-project/pull/144635 |
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-| device | pointer attachment | :part:`being repaired` | @abhinavgaba (https://github.com/llvm/llvm-project/pull/153683) |
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-| atomic | hints for the atomic construct | :good:`done` | D51233 |
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-| base language | C11 support | :good:`done` | |
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-| base language | C++11/14/17 support | :good:`done` | |
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-| base language | lambda support | :good:`done` | |
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-| misc | array shaping | :good:`done` | D74144 |
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-| misc | library shutdown (omp_pause_resource[_all]) | :good:`done` | D55078 |
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-| misc | metadirectives | :part:`mostly done` | D91944, https://github.com/llvm/llvm-project/pull/128640 |
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-| misc | conditional modifier for lastprivate clause | :good:`done` | |
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-| misc | iterator and multidependences | :good:`done` | |
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-| misc | depobj directive and depobj dependency kind | :good:`done` | |
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-| misc | user-defined function variants | :good:`done`. | D67294, D64095, D71847, D71830, D109635 |
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-| misc | pointer/reference to pointer based array reductions | :good:`done` | |
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-| misc | prevent new type definitions in clauses | :good:`done` | |
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-| memory model | memory model update (seq_cst, acq_rel, release, acquire,...) | :good:`done` | |
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-
-
-.. _OpenMP 51 implementation details:
-
-OpenMP 5.1 Implementation Details
-=================================
+| Category | Feature | Status | Reviews |
+| ----------------- | ------------------------------------------------------------ | ----------------------- | -------------------------------------------------------------------- |
+| loop | support != in the canonical loop form | {good}`done` | D54441 |
+| loop | #pragma omp loop (directive) | {part}`partial` | D145823 (combined forms) |
+| loop | #pragma omp loop bind | {part}`worked on` | D144634 (needs review) |
+| loop | collapse imperfectly nested loop | {good}`done` | |
+| loop | collapse non-rectangular nested loop | {good}`done` | |
+| loop | C++ range-base for loop | {good}`done` | |
+| loop | clause: if for SIMD directives | {good}`done` | |
+| loop | inclusive scan (matching C++17 PSTL) | {good}`done` | |
+| memory management | memory allocators | {good}`done` | r341687,r357929 |
+| memory management | allocate directive and allocate clause | {good}`done` | r355614,r335952 |
+| OMPD | OMPD interfaces | {good}`done` | <https://reviews.llvm.org/D99914> (Supports only HOST(CPU) and Linux |
+| OMPT | OMPT interfaces (callback support) | {good}`done` | |
+| thread affinity | thread affinity | {good}`done` | |
+| task | taskloop reduction | {good}`done` | |
+| task | task affinity | {part}`not upstream` | <https://github.com/jklinkenberg/openmp/tree/task-affinity> |
+| task | clause: depend on the taskwait construct | {good}`done` | D113540 (regular codegen only) |
+| task | depend objects and detachable tasks | {good}`done` | |
+| task | mutexinoutset dependence-type for tasks | {good}`done` | D53380,D57576 |
+| task | combined taskloop constructs | {good}`done` | |
+| task | master taskloop | {good}`done` | |
+| task | parallel master taskloop | {good}`done` | |
+| task | master taskloop simd | {good}`done` | |
+| task | parallel master taskloop simd | {good}`done` | |
+| SIMD | atomic and simd constructs inside SIMD code | {good}`done` | |
+| SIMD | SIMD nontemporal | {good}`done` | |
+| device | infer target functions from initializers | {part}`worked on` | |
+| device | infer target variables from initializers | {good}`done` | D146418 |
+| device | OMP_TARGET_OFFLOAD environment variable | {good}`done` | D50522 |
+| device | support full 'defaultmap' functionality | {good}`done` | D69204 |
+| device | device specific functions | {good}`done` | |
+| device | clause: device_type | {good}`done` | |
+| device | clause: extended device | {good}`done` | |
+| device | clause: uses_allocators clause | {good}`done` | <https://github.com/llvm/llvm-project/pull/157025> |
+| device | clause: in_reduction | {part}`worked on` | r308768 |
+| device | omp_get_device_num() | {good}`done` | D54342,D128347 |
+| device | structure mapping of references | {none}`unclaimed` | |
+| device | nested target declare | {good}`done` | D51378 |
+| device | implicitly map 'this' (this[:1]) | {good}`done` | D55982 |
+| device | allow access to the reference count (omp_target_is_present) | {good}`done` | |
+| device | requires directive | {good}`done` | |
+| device | clause: unified_shared_memory | {good}`done` | D52625,D52359 |
+| device | clause: unified_address | {part}`partial` | |
+| device | clause: reverse_offload | {part}`partial` | D52780,D155003 |
+| device | clause: atomic_default_mem_order | {good}`done` | D53513 |
+| device | clause: dynamic_allocators | {part}`unclaimed parts` | D53079 |
+| device | user-defined mappers | {good}`done` | D56326,D58638,D58523,D58074,D60972,D59474 |
+| device | map array-section with implicit mapper | {good}`done` | <https://github.com/llvm/llvm-project/pull/101101> |
+| device | mapping lambda expression | {good}`done` | D51107 |
+| device | clause: use_device_addr for target data | {good}`done` | |
+| device | support close modifier on map clause | {good}`done` | D55719,D55892 |
+| device | teams construct on the host device | {good}`done` | r371553 |
+| device | support non-contiguous array sections for target update | {good}`done` | <https://github.com/llvm/llvm-project/pull/144635> |
+| device | pointer attachment | {part}`being repaired` | @abhinavgaba (<https://github.com/llvm/llvm-project/pull/153683>) |
+| atomic | hints for the atomic construct | {good}`done` | D51233 |
+| base language | C11 support | {good}`done` | |
+| base language | C++11/14/17 support | {good}`done` | |
+| base language | lambda support | {good}`done` | |
+| misc | array shaping | {good}`done` | D74144 |
+| misc | library shutdown (omp_pause_resource[\_all]) | {good}`done` | D55078 |
+| misc | metadirectives | {part}`mostly done` | D91944, <https://github.com/llvm/llvm-project/pull/128640> |
+| misc | conditional modifier for lastprivate clause | {good}`done` | |
+| misc | iterator and multidependences | {good}`done` | |
+| misc | depobj directive and depobj dependency kind | {good}`done` | |
+| misc | user-defined function variants | {good}`done`. | D67294, D64095, D71847, D71830, D109635 |
+| misc | pointer/reference to pointer based array reductions | {good}`done` | |
+| misc | prevent new type definitions in clauses | {good}`done` | |
+| memory model | memory model update (seq_cst, acq_rel, release, acquire,...) | {good}`done` | |
+
+(openmp-51-implementation-details)=
+
+## OpenMP 5.1 Implementation Details
The following table provides a quick overview over various OpenMP 5.1 features
and their implementation status.
Please post on the
-`Discourse forums (Runtimes - OpenMP category)`_ for more
+[Discourse forums (Runtimes - OpenMP category)] for more
information or if you want to help with the
implementation.
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-|Category | Feature | Status | Reviews |
-+==============================+==============================================================+==========================+=======================================================================+
-| atomic | 'compare' clause on atomic construct | :good:`done` | D120290, D120007, D118632, D120200, D116261, D118547, D116637 |
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-| atomic | 'fail' clause on atomic construct | :part:`worked on` | D123235 (in progress) |
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-| base language | C++ attribute specifier syntax | :good:`done` | D105648 |
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-| device | 'present' map type modifier | :good:`done` | D83061, D83062, D84422 |
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-| device | 'present' motion modifier | :good:`done` | D84711, D84712 |
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-| device | 'present' in defaultmap clause | :good:`done` | D92427 |
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-| device | map clause reordering based on 'present' modifier | :none:`unclaimed` | |
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-| device | device-specific environment variables | :none:`unclaimed` | |
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-| device | omp_target_is_accessible routine | :good:`done` | https://github.com/llvm/llvm-project/pull/138294 |
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-| device | omp_get_mapped_ptr routine | :good:`done` | D141545 |
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-| device | new async target memory copy routines | :good:`done` | D136103 |
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-| device | thread_limit clause on target construct | :part:`partial` | D141540 (offload), D152054 (host, in progress) |
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-| device | has_device_addr clause on target construct | :none:`unclaimed` | |
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-| device | use_device_ptr/addr preserve host address when lookup fails | :good:`done` | https://github.com/llvm/llvm-project/pull/174659 |
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-| device | iterators in map clause or motion clauses | :good:`done` | https://github.com/llvm/llvm-project/pull/159112 |
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-| device | indirect clause on declare target directive | :part:`In Progress` | |
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-| device | allow virtual functions calls for mapped object on device | :part:`partial` | |
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-| device | interop construct | :part:`partial` | parsing/sema done: D98558, D98834, D98815 |
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-| device | assorted routines for querying interoperable properties | :part:`partial` | D106674 |
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-| loop | Loop tiling transformation | :good:`done` | D76342 |
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-| loop | Loop unrolling transformation | :good:`done` | D99459 |
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-| loop | 'reproducible'/'unconstrained' modifiers in 'order' clause | :part:`partial` | D127855 |
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-| memory management | alignment for allocate directive and clause | :good:`done` | D115683 |
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-| memory management | 'allocator' modifier for allocate clause | :good:`done` | https://github.com/llvm/llvm-project/pull/114883 |
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-| memory management | 'align' modifier for allocate clause | :good:`done` | https://github.com/llvm/llvm-project/pull/121814 |
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-| memory management | new memory management routines | :none:`unclaimed` | |
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-| memory management | changes to omp_alloctrait_key enum | :none:`unclaimed` | |
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-| memory model | seq_cst clause on flush construct | :good:`done` | https://github.com/llvm/llvm-project/pull/114072 |
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-| misc | 'omp_all_memory' keyword and use in 'depend' clause | :good:`done` | D125828, D126321 |
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-| misc | error directive | :good:`done` | D139166 |
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-| misc | scope construct | :good:`done` | D157933, https://github.com/llvm/llvm-project/pull/109197 |
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-| misc | routines for controlling and querying team regions | :part:`partial` | D95003 (libomp only) |
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-| misc | omp_display_env routine | :good:`done` | D74956 |
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-| misc | extended OMP_PLACES syntax | :none:`unclaimed` | |
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-| misc | OMP_NUM_TEAMS and OMP_TEAMS_THREAD_LIMIT env vars | :good:`done` | D138769 |
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-| misc | 'target_device' selector in context specifier | :part:`worked on` | |
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-| misc | begin/end declare variant | :good:`done` | D71179 |
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-| misc | dispatch construct and function variant argument adjustment | :part:`worked on` | D99537, D99679 |
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-| misc | assumes directives | :part:`worked on` | |
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-| misc | assume directive | :good:`done` | |
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-| misc | nothing directive | :good:`done` | D123286 |
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-| misc | masked construct and related combined constructs | :good:`done` | D99995, D100514, PR-121741(parallel_masked_taskloop) |
-| | | | PR-121746(parallel_masked_task_loop_simd),PR-121914(masked_taskloop) |
-| | | | PR-121916(masked_taskloop_simd) |
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-| misc | default(firstprivate) & default(private) | :good:`done` | D75591 (firstprivate), D125912 (private) |
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-| other | deprecating master construct | :none:`unclaimed` | |
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-| OMPT | changes to ompt_scope_endpoint_t enum | :good:`done` | D90752 |
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-| OMPT | new barrier types added to ompt_sync_region_t enum | :good:`done` | D90752 |
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-| OMPT | async data transfers added to ompt_target_data_op_t enum | :good:`done` | D90752 |
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-| OMPT | new barrier state values added to ompt_state_t enum | :good:`done` | D90752 |
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-| OMPT | new 'emi' callbacks for external monitoring interfaces | :good:`done` | |
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-| OMPT | device tracing interface | :part:`in progress` | jplehr |
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-| task | 'strict' modifier for taskloop construct | :none:`unclaimed` | |
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-| task | inoutset in depend clause | :good:`done` | D97085, D118383 |
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-| task | nowait clause on taskwait | :part:`partial` | parsing/sema done: D131830, D141531 |
-+------------------------------+--------------------------------------------------------------+--------------------------+-----------------------------------------------------------------------+
-
-
-.. _OpenMP 5.2 implementation details:
-
-OpenMP 5.2 Implementation Details
-=================================
+| Category | Feature | Status | Reviews |
+| ----------------- | ----------------------------------------------------------- | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| atomic | 'compare' clause on atomic construct | {good}`done` | D120290, D120007, D118632, D120200, D116261, D118547, D116637 |
+| atomic | 'fail' clause on atomic construct | {part}`worked on` | D123235 (in progress) |
+| base language | C++ attribute specifier syntax | {good}`done` | D105648 |
+| device | 'present' map type modifier | {good}`done` | D83061, D83062, D84422 |
+| device | 'present' motion modifier | {good}`done` | D84711, D84712 |
+| device | 'present' in defaultmap clause | {good}`done` | D92427 |
+| device | map clause reordering based on 'present' modifier | {none}`unclaimed` | |
+| device | device-specific environment variables | {none}`unclaimed` | |
+| device | omp_target_is_accessible routine | {good}`done` | <https://github.com/llvm/llvm-project/pull/138294> |
+| device | omp_get_mapped_ptr routine | {good}`done` | D141545 |
+| device | new async target memory copy routines | {good}`done` | D136103 |
+| device | thread_limit clause on target construct | {part}`partial` | D141540 (offload), D152054 (host, in progress) |
+| device | has_device_addr clause on target construct | {none}`unclaimed` | |
+| device | use_device_ptr/addr preserve host address when lookup fails | {good}`done` | <https://github.com/llvm/llvm-project/pull/174659> |
+| device | iterators in map clause or motion clauses | {good}`done` | <https://github.com/llvm/llvm-project/pull/159112> |
+| device | indirect clause on declare target directive | {part}`In Progress` | |
+| device | allow virtual functions calls for mapped object on device | {part}`partial` | |
+| device | interop construct | {part}`partial` | parsing/sema done: D98558, D98834, D98815 |
+| device | assorted routines for querying interoperable properties | {part}`partial` | D106674 |
+| loop | Loop tiling transformation | {good}`done` | D76342 |
+| loop | Loop unrolling transformation | {good}`done` | D99459 |
+| loop | 'reproducible'/'unconstrained' modifiers in 'order' clause | {part}`partial` | D127855 |
+| memory management | alignment for allocate directive and clause | {good}`done` | D115683 |
+| memory management | 'allocator' modifier for allocate clause | {good}`done` | <https://github.com/llvm/llvm-project/pull/114883> |
+| memory management | 'align' modifier for allocate clause | {good}`done` | <https://github.com/llvm/llvm-project/pull/121814> |
+| memory management | new memory management routines | {none}`unclaimed` | |
+| memory management | changes to omp_alloctrait_key enum | {none}`unclaimed` | |
+| memory model | seq_cst clause on flush construct | {good}`done` | <https://github.com/llvm/llvm-project/pull/114072> |
+| misc | 'omp_all_memory' keyword and use in 'depend' clause | {good}`done` | D125828, D126321 |
+| misc | error directive | {good}`done` | D139166 |
+| misc | scope construct | {good}`done` | D157933, <https://github.com/llvm/llvm-project/pull/109197> |
+| misc | routines for controlling and querying team regions | {part}`partial` | D95003 (libomp only) |
+| misc | omp_display_env routine | {good}`done` | D74956 |
+| misc | extended OMP_PLACES syntax | {none}`unclaimed` | |
+| misc | OMP_NUM_TEAMS and OMP_TEAMS_THREAD_LIMIT env vars | {good}`done` | D138769 |
+| misc | 'target_device' selector in context specifier | {part}`worked on` | |
+| misc | begin/end declare variant | {good}`done` | D71179 |
+| misc | dispatch construct and function variant argument adjustment | {part}`worked on` | D99537, D99679 |
+| misc | assumes directives | {part}`worked on` | |
+| misc | assume directive | {good}`done` | |
+| misc | nothing directive | {good}`done` | D123286 |
+| misc | masked construct and related combined constructs | {good}`done` | D99995, D100514, PR-121741(parallel_masked_taskloop) PR-121746(parallel_masked_task_loop_simd),PR-121914(masked_taskloop) PR-121916(masked_taskloop_simd) |
+| misc | default(firstprivate) & default(private) | {good}`done` | D75591 (firstprivate), D125912 (private) |
+| other | deprecating master construct | {none}`unclaimed` | |
+| OMPT | changes to ompt_scope_endpoint_t enum | {good}`done` | D90752 |
+| OMPT | new barrier types added to ompt_sync_region_t enum | {good}`done` | D90752 |
+| OMPT | async data transfers added to ompt_target_data_op_t enum | {good}`done` | D90752 |
+| OMPT | new barrier state values added to ompt_state_t enum | {good}`done` | D90752 |
+| OMPT | new 'emi' callbacks for external monitoring interfaces | {good}`done` | |
+| OMPT | device tracing interface | {part}`in progress` | jplehr |
+| task | 'strict' modifier for taskloop construct | {none}`unclaimed` | |
+| task | inoutset in depend clause | {good}`done` | D97085, D118383 |
+| task | nowait clause on taskwait | {part}`partial` | parsing/sema done: D131830, D141531 |
+
+(openmp-5-2-implementation-details)=
+
+## OpenMP 5.2 Implementation Details
The following table provides a quick overview of various OpenMP 5.2 features
and their implementation status. Please post on the
-`Discourse forums (Runtimes - OpenMP category)`_ for more
+[Discourse forums (Runtimes - OpenMP category)] for more
information or if you want to help with the
implementation.
-
-
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-|Feature | C/C++ Status | Fortran Status | Reviews |
-+=============================================================+===========================+===========================+==========================================================================+
-| omp_in_explicit_task() | :none:`unclaimed` | :none:`unclaimed` | |
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-| semantics of explicit_task_var and implicit_task_var | :none:`unclaimed` | :none:`unclaimed` | |
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-| ompx sentinel for C/C++ directive extensions | :none:`unclaimed` | :none:`unclaimed` | |
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-| ompx prefix for clause extensions | :none:`unclaimed` | :none:`unclaimed` | |
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-| if clause on teams construct | :none:`unclaimed` | :none:`unclaimed` | |
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-| step modifier added | :none:`unclaimed` | :none:`unclaimed` | |
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-| declare mapper: Add iterator modifier on map clause | :none:`unclaimed` | :none:`unclaimed` | |
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-| declare mapper: Add iterator modifier on map clause | :none:`unclaimed` | :none:`unclaimed` | |
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-| memspace and traits modifiers to uses allocator i | :none:`unclaimed` | :none:`unclaimed` | |
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-| Add otherwise clause to metadirectives | :none:`unclaimed` | :none:`unclaimed` | |
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-| doacross clause with support for omp_cur_iteration | :none:`unclaimed` | :none:`unclaimed` | |
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-| position of interop_type in init clause on iterop | :none:`unclaimed` | :none:`unclaimed` | |
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-| implicit map type for target enter/exit data | :none:`unclaimed` | :none:`unclaimed` | |
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-| work OMPT type for work-sharing loop constructs | :good:`done` | :good:`done` | PR-189347, PR-97429 |
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-| extend ompt_dispatch_t for new enum values | :good:`done` | :good:`done` | D122107 |
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-| allocate and firstprivate on scope directive | :none:`unclaimed` | :none:`unclaimed` | |
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-| Change loop consistency for order clause | :none:`unclaimed` | :none:`unclaimed` | |
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-| Add memspace and traits modifiers to uses_allocators | :none:`unclaimed` | :none:`unclaimed` | |
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-| Keep original base pointer on map w/o matched candidate | :none:`unclaimed` | :none:`unclaimed` | |
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-| Pure procedure support for certain directives | :none:`N/A` | :none:`unclaimed` | |
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-| ALLOCATE statement support for allocators | :none:`N/A` | :none:`unclaimed` | |
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-| dispatch construct extension to support end directive | :none:`N/A` | :none:`unclaimed` | |
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-
-
-
-.. _OpenMP 5.2 Deprecations:
-
-OpenMP 5.2 Deprecations
-=======================
-
-
-
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-| | C/C++ Status | Fortran Status | Reviews |
-+=============================================================+===========================+===========================+==========================================================================+
-| Linear clause syntax | :none:`unclaimed` | :none:`unclaimed` | |
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-| The minus operator | :none:`unclaimed` | :none:`unclaimed` | |
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-| Map clause modifiers without commas | :none:`unclaimed` | :none:`unclaimed` | |
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-| The use of allocate directives with ALLOCATE statement | :good:`N/A` | :none:`unclaimed` | |
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-| uses_allocators list syntax | :none:`unclaimed` | :none:`unclaimed` | |
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-| The default clause on metadirectives | :none:`unclaimed` | :none:`unclaimed` | |
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-| The delimited form of the declare target directive | :none:`unclaimed` | :good:`N/A` | |
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-| The use of the to clause on the declare target directive | :none:`unclaimed` | :none:`unclaimed` | |
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-| The syntax of the destroy clause on the depobj construct | :none:`unclaimed` | :none:`unclaimed` | |
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-| keyword source and sink as task-dependence modifiers | :none:`unclaimed` | :none:`unclaimed` | |
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-| interop types in any position on init clause of interop | :none:`unclaimed` | :none:`unclaimed` | |
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-| ompd prefix usage for some ICVs | :none:`unclaimed` | :none:`unclaimed` | |
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-
-.. _OpenMP 6.0 implementation details:
-
-OpenMP 6.0 Implementation Details
-=================================
+| Feature | C/C++ Status | Fortran Status | Reviews |
+| ------------------------------------------------------- | ----------------- | ----------------- | ------------------- |
+| omp_in_explicit_task() | {none}`unclaimed` | {none}`unclaimed` | |
+| semantics of explicit_task_var and implicit_task_var | {none}`unclaimed` | {none}`unclaimed` | |
+| ompx sentinel for C/C++ directive extensions | {none}`unclaimed` | {none}`unclaimed` | |
+| ompx prefix for clause extensions | {none}`unclaimed` | {none}`unclaimed` | |
+| if clause on teams construct | {none}`unclaimed` | {none}`unclaimed` | |
+| step modifier added | {none}`unclaimed` | {none}`unclaimed` | |
+| declare mapper: Add iterator modifier on map clause | {none}`unclaimed` | {none}`unclaimed` | |
+| declare mapper: Add iterator modifier on map clause | {none}`unclaimed` | {none}`unclaimed` | |
+| memspace and traits modifiers to uses allocator i | {none}`unclaimed` | {none}`unclaimed` | |
+| Add otherwise clause to metadirectives | {none}`unclaimed` | {none}`unclaimed` | |
+| doacross clause with support for omp_cur_iteration | {none}`unclaimed` | {none}`unclaimed` | |
+| position of interop_type in init clause on iterop | {none}`unclaimed` | {none}`unclaimed` | |
+| implicit map type for target enter/exit data | {none}`unclaimed` | {none}`unclaimed` | |
+| work OMPT type for work-sharing loop constructs | {good}`done` | {good}`done` | PR-189347, PR-97429 |
+| extend ompt_dispatch_t for new enum values | {good}`done` | {good}`done` | D122107 |
+| allocate and firstprivate on scope directive | {none}`unclaimed` | {none}`unclaimed` | |
+| Change loop consistency for order clause | {none}`unclaimed` | {none}`unclaimed` | |
+| Add memspace and traits modifiers to uses_allocators | {none}`unclaimed` | {none}`unclaimed` | |
+| Keep original base pointer on map w/o matched candidate | {none}`unclaimed` | {none}`unclaimed` | |
+| Pure procedure support for certain directives | {none}`N/A` | {none}`unclaimed` | |
+| ALLOCATE statement support for allocators | {none}`N/A` | {none}`unclaimed` | |
+| dispatch construct extension to support end directive | {none}`N/A` | {none}`unclaimed` | |
+
+(openmp-5-2-deprecations)=
+
+## OpenMP 5.2 Deprecations
+
+| | C/C++ Status | Fortran Status | Reviews |
+| -------------------------------------------------------- | ----------------- | ----------------- | ------- |
+| Linear clause syntax | {none}`unclaimed` | {none}`unclaimed` | |
+| The minus operator | {none}`unclaimed` | {none}`unclaimed` | |
+| Map clause modifiers without commas | {none}`unclaimed` | {none}`unclaimed` | |
+| The use of allocate directives with ALLOCATE statement | {good}`N/A` | {none}`unclaimed` | |
+| uses_allocators list syntax | {none}`unclaimed` | {none}`unclaimed` | |
+| The default clause on metadirectives | {none}`unclaimed` | {none}`unclaimed` | |
+| The delimited form of the declare target directive | {none}`unclaimed` | {good}`N/A` | |
+| The use of the to clause on the declare target directive | {none}`unclaimed` | {none}`unclaimed` | |
+| The syntax of the destroy clause on the depobj construct | {none}`unclaimed` | {none}`unclaimed` | |
+| keyword source and sink as task-dependence modifiers | {none}`unclaimed` | {none}`unclaimed` | |
+| interop types in any position on init clause of interop | {none}`unclaimed` | {none}`unclaimed` | |
+| ompd prefix usage for some ICVs | {none}`unclaimed` | {none}`unclaimed` | |
+
+(openmp-6-0-implementation-details)=
+
+## OpenMP 6.0 Implementation Details
The following table provides a quick overview of various OpenMP 6.0 features
and their implementation status. Please post on the
-`Discourse forums (Runtimes - OpenMP category)`_ for more
+[Discourse forums (Runtimes - OpenMP category)] for more
information or if you want to help with the
implementation.
+(openmp-6-0-deprecations)=
+
+## OpenMP 6.0 Deprecations
+
+| | C/C++ Status | Fortran Status | Reviews |
+| ----------------------------------------------------- | ----------------- | -------------- | ------- |
+| OMPT: non-emi target callbacks | {none}`unclaimed` | {good}`N/A` | |
+| OMPT: transfer_to_device / transfer_from_device enums | {none}`unclaimed` | {good}`N/A` | |
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-|Feature | C/C++ Status | Fortran Status | Reviews |
-+=============================================================+===========================+===========================+==========================================================================+
-| free-agent threads | :none:`unclaimed` | :none:`unclaimed` | |
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-| threadset clause | :part:`partial` | :none:`unclaimed` | Parse/Sema/Codegen : https://github.com/llvm/llvm-project/pull/13580 |
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-| Recording of task graphs | :part:`in progress` | :part:`in progress` | clang: jtb20, flang: kparzysz |
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-| Parallel inductions | :none:`unclaimed` | :none:`unclaimed` | |
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-| init_complete for scan directive | :none:`unclaimed` | :none:`unclaimed` | |
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-| loop interchange transformation | :good:`done` | :none:`unclaimed` | Clang (interchange): https://github.com/llvm/llvm-project/pull/93022 |
-| | | | Clang (permutation): https://github.com/llvm/llvm-project/pull/92030 |
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-| loop reverse transformation | :good:`done` | :none:`unclaimed` | https://github.com/llvm/llvm-project/pull/92916 |
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-| loop stripe transformation | :good:`done` | :none:`unclaimed` | https://github.com/llvm/llvm-project/pull/119891 |
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-| loop fusion transformation | :part:`in progress` | :good:`done` | https://github.com/llvm/llvm-project/pull/139293 |
-| | | | https://github.com/llvm/llvm-project/pull/161213 |
-| | | | https://github.com/llvm/llvm-project/pull/168898 |
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-| loop index set splitting transformation with count clause | :part:`in progress` | :none:`unclaimed` | @amitamd7 |
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-| loop transformation apply clause | :none:`unclaimed` | :none:`unclaimed` | |
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-| loop fuse transformation | :good:`done` | :none:`unclaimed` | |
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-| workdistribute construct | | :none:`in progress` | @skc7, @mjklemm |
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-| task_iteration | :none:`unclaimed` | :none:`unclaimed` | |
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-| memscope clause for atomic and flush | :none:`unclaimed` | :none:`unclaimed` | |
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-| transparent clause (hull tasks) | :part:`partial` | :none:`unclaimed` | Clang parsing/sema https://github.com/llvm/llvm-project/pull/174646 |
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-| rule-based compound directives | :part:`In Progress` | :part:`In Progress` | kparzysz |
-| | | | Testing for Fortran missing |
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-| C23, C++23 | :none:`unclaimed` | | |
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-| Fortran 2023 | | :none:`unclaimed` | |
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-| decl attribute for declarative directives | :none:`unclaimed` | :none:`unclaimed` | |
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-| C attribute syntax | :none:`unclaimed` | | |
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-| pure directives in DO CONCURRENT | | :none:`unclaimed` | |
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-| Optional argument for all clauses | :part:`partial` | :part:`In Progress` | Parse/Sema (nowait): https://github.com/llvm/llvm-project/pull/159628 |
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-| Function references for locator list items | :none:`unclaimed` | :none:`unclaimed` | |
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-| All clauses accept directive name modifier | :none:`unclaimed` | :none:`unclaimed` | |
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-| Extensions to depobj construct | :none:`unclaimed` | :none:`unclaimed` | |
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-| Extensions to atomic construct | :none:`unclaimed` | :none:`unclaimed` | |
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-| Private reductions | :part:`mostly` | :none:`unclaimed` | Parse/Sema:https://github.com/llvm/llvm-project/pull/129938 |
-| | | | Codegen: https://github.com/llvm/llvm-project/pull/134709 |
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-| Self maps | :part:`partial` | :none:`unclaimed` | parsing/sema done: https://github.com/llvm/llvm-project/pull/129888 |
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-| Release map type for declare mapper | :none:`unclaimed` | :none:`unclaimed` | |
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-| Extensions to interop construct | :none:`unclaimed` | :none:`unclaimed` | |
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-| no_openmp_constructs | :good:`done` | :none:`unclaimed` | https://github.com/llvm/llvm-project/pull/125933 |
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-| safe_sync and progress with identifier and API | :none:`unclaimed` | :none:`unclaimed` | |
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-| OpenMP directives in concurrent loop regions | :good:`done` | :none:`unclaimed` | https://github.com/llvm/llvm-project/pull/125621 |
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-| atomics constructs on concurrent loop regions | :good:`done` | :none:`unclaimed` | https://github.com/llvm/llvm-project/pull/125621 |
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-| Loop construct with DO CONCURRENT | | :part:`In Progress` | |
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-| device_type clause for target construct | :none:`unclaimed` | :none:`unclaimed` | |
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-| nowait for ancestor target directives | :none:`unclaimed` | :none:`unclaimed` | |
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-| New API for devices' num_teams/thread_limit | :none:`unclaimed` | :none:`unclaimed` | |
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-| Host and device environment variables | :part:`in progress` | :none:`unclaimed` | @amitamd7 |
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-| num_threads ICV and clause accepts list | :none:`unclaimed` | :none:`unclaimed` | |
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-| Numeric names for environment variables | :none:`unclaimed` | :none:`unclaimed` | |
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-| Increment between places for OMP_PLACES | :none:`unclaimed` | :none:`unclaimed` | |
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-| OMP_AVAILABLE_DEVICES envirable | :none:`unclaimed` | :none:`unclaimed` | (should wait for "Traits for default device envirable" being done) |
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-| Traits for default device envirable | :part:`in progress` | :none:`unclaimed` | ro-i |
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-| Optionally omit array length expression | :good:`done` | :none:`unclaimed` | (Parse) https://github.com/llvm/llvm-project/pull/148048, |
-| | | | (Sema) https://github.com/llvm/llvm-project/pull/152786 |
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-| Canonical loop sequences | :part:`in progress` | :part:`in progress` | Clang: https://github.com/llvm/llvm-project/pull/139293 |
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-| Clarifications to Fortran map semantics | :none:`unclaimed` | :none:`unclaimed` | |
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-| default clause at target construct | :good:`done` | :none:`unclaimed` | https://github.com/llvm/llvm-project/pull/162910 |
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-| ref count update use_device_{ptr, addr} | :none:`unclaimed` | :none:`unclaimed` | |
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-| Clarifications to implicit reductions | :none:`unclaimed` | :none:`unclaimed` | |
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-| ref modifier for map clauses | :part:`In Progress` | :none:`unclaimed` | |
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-| map-type modifiers in arbitrary position | :good:`done` | :none:`unclaimed` | https://github.com/llvm/llvm-project/pull/90499 |
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-| Lift nesting restriction on concurrent loop | :good:`done` | :none:`unclaimed` | https://github.com/llvm/llvm-project/pull/125621 |
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-| priority clause for target constructs | :none:`unclaimed` | :none:`unclaimed` | |
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-| changes to target_data construct | :none:`unclaimed` | :none:`unclaimed` | |
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-| Non-const do_not_sync for nowait/nogroup | :none:`unclaimed` | :none:`unclaimed` | |
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-| need_device_addr modifier for adjust_args clause | :part:`partial` | :none:`unclaimed` | Parsing/Sema: https://github.com/llvm/llvm-project/pull/143442 |
-| | | | https://github.com/llvm/llvm-project/pull/149586 |
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-| need_device_ptr modifier for adjust_args clause | :none:`unclaimed` | :none:`unclaimed` | |
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-| Prescriptive num_threads | :good:`done` | :none:`unclaimed` | https://github.com/llvm/llvm-project/pull/160659 |
-| | | | https://github.com/llvm/llvm-project/pull/146403 |
-| | | | https://github.com/llvm/llvm-project/pull/146404 |
-| | | | https://github.com/llvm/llvm-project/pull/146405 |
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-| Message and severity clauses | :good:`done` | :none:`unclaimed` | https://github.com/llvm/llvm-project/pull/146093 |
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-| Local clause on declare target | :good:`done` | :none:`unclaimed` | clang Parse/Sema: https://github.com/llvm/llvm-project/pull/186281 |
-| | | | clang Codegen : https://github.com/llvm/llvm-project/pull/196431 |
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-| groupprivate directive | :part:`In Progress` | :part:`partial` | Flang: kparzysz, mjklemm |
-| | | | |
-| | | | Flang parser: https://github.com/llvm/llvm-project/pull/153807 |
-| | | | Flang sema: https://github.com/llvm/llvm-project/pull/154779 |
-| | | | Clang parse/sema: https://github.com/llvm/llvm-project/pull/158134 |
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-| variable-category on default clause | :good:`done` | :none:`unclaimed` | |
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-| Changes to omp_target_is_accessible | :part:`In Progress` | :part:`In Progress` | |
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-| defaultmap implicit-behavior 'storage' | :good:`done` | :none:`unclaimed` | https://github.com/llvm/llvm-project/pull/158336 |
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-| defaultmap implicit-behavior 'private' | :good:`done` | :none:`unclaimed` | https://github.com/llvm/llvm-project/pull/158712 |
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-| OMPT: ompt_get_buffer_limits entry point | :part:`partial` | :good:`N/A` | Definition: https://github.com/llvm/llvm-project/pull/195829 |
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-| OMPT: ompt_any_record_ompt_t for device tracing | :good:`done` | :good:`N/A` | https://github.com/llvm/llvm-project/pull/195829 |
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-| OMPT: ompt_target_data_transfer_rect(_async) & subvolume | :part:`partial` | :good:`N/A` | Enum: https://github.com/llvm/llvm-project/pull/195829 |
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-| OMPT: ompt_target_data_transfer(_async) | :part:`partial` | :good:`N/A` | Enum: https://github.com/llvm/llvm-project/pull/195829 |
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-| OMPT: ompt_target_data_memset(_async) | :part:`partial` | :good:`N/A` | Enum: https://github.com/llvm/llvm-project/pull/195829 |
-| | | | Callbacks: https://github.com/llvm/llvm-project/pull/194168 |
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-| OMPT: workdistribute work callback enum | :part:`partial` | :good:`N/A` | Enum: https://github.com/llvm/llvm-project/pull/195829 |
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-| OMPT: transparent task flag enum (importing/exporting) | :part:`partial` | :good:`N/A` | Enum: https://github.com/llvm/llvm-project/pull/195829 |
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-| OMPT: dependence type {out, inout}_all_memory | :part:`partial` | :good:`N/A` | Enum: https://github.com/llvm/llvm-project/pull/195829 |
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-| OMPT: removed master callback | :none:`unclaimed` | :good:`N/A` | |
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-| OMPT: removed sync_region_barrier(_implicit) enum value | :none:`unclaimed` | :good:`N/A` | |
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-
-.. _OpenMP 6.0 Deprecations:
-
-OpenMP 6.0 Deprecations
-=======================
-
-
-
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-| | C/C++ Status | Fortran Status | Reviews |
-+=============================================================+===========================+===========================+==========================================================================+
-| OMPT: non-emi target callbacks | :none:`unclaimed` | :good:`N/A` | |
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-| OMPT: transfer_to_device / transfer_from_device enums | :none:`unclaimed` | :good:`N/A` | |
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-
-.. _OpenMP 6.1 implementation details:
-
-OpenMP 6.1 Implementation Details (Experimental)
-================================================
+(openmp-6-1-implementation-details)=
+
+## OpenMP 6.1 Implementation Details (Experimental)
The following table provides a quick overview over various OpenMP 6.1 features
and their implementation status. Since OpenMP 6.1 has not yet been released, the
following features are experimental and are subject to change at any time.
-Please post on the `Discourse forums (Runtimes - OpenMP category)`_ for more
+Please post on the [Discourse forums (Runtimes - OpenMP category)] for more
information or if you want to help with the
implementation.
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-|Feature | C/C++ Status | Fortran Status | Reviews |
-+=============================================================+===========================+===========================+==========================================================================+
-| dyn_groupprivate clause | :part:`partial` | :part:`In Progress` | C/C++: Host device support missing |
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-| loop flatten transformation | :none:`unclaimed` | :none:`unclaimed` | |
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-| loop grid/tile modifiers for sizes clause | :none:`unclaimed` | :none:`unclaimed` | |
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-| attach map-type modifier | :part:`In Progress` | :none:`unclaimed` | C/C++: @abhinavgaba; |
-| | | | RT: @abhinavgaba (https://github.com/llvm/llvm-project/pull/149036, |
-| | | | https://github.com/llvm/llvm-project/pull/158370) |
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-| need_device_ptr modifier for adjust_args clause | :part:`partial` | :none:`unclaimed` | Clang Parsing/Sema: https://github.com/llvm/llvm-project/pull/168905 |
-| | | | https://github.com/llvm/llvm-project/pull/169558 |
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-| fallback modifier for use_device_ptr clause | :good:`done` | :none:`unclaimed` | Clang: @abhinavgaba (https://github.com/llvm/llvm-project/pull/170578, |
-| | | | https://github.com/llvm/llvm-project/pull/173931) |
-| | | | RT: @abhinavgaba (https://github.com/llvm/llvm-project/pull/169603) |
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-| dims clause with strict behavior (multidimensional teams | :part:`In Progress` | :part:`In Progress` | C/C++: kevinsala |
-| and leagues) | | | Fortran: skc7, kparzysz, mjklemm |
-+-------------------------------------------------------------+---------------------------+---------------------------+--------------------------------------------------------------------------+
-
-OpenMP Extensions
-=================
+| Feature | C/C++ Status | Fortran Status | Reviews |
+| --------------------------------------------------------------------- | ------------------- | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| dyn_groupprivate clause | {part}`partial` | {part}`In Progress` | C/C++: Host device support missing |
+| loop flatten transformation | {none}`unclaimed` | {none}`unclaimed` | |
+| loop grid/tile modifiers for sizes clause | {none}`unclaimed` | {none}`unclaimed` | |
+| attach map-type modifier | {part}`In Progress` | {none}`unclaimed` | C/C++: @abhinavgaba; RT: @abhinavgaba (<https://github.com/llvm/llvm-project/pull/149036>, <https://github.com/llvm/llvm-project/pull/158370>) |
+| need_device_ptr modifier for adjust_args clause | {part}`partial` | {none}`unclaimed` | Clang Parsing/Sema: <https://github.com/llvm/llvm-project/pull/168905> <https://github.com/llvm/llvm-project/pull/169558> |
+| fallback modifier for use_device_ptr clause | {good}`done` | {none}`unclaimed` | Clang: @abhinavgaba (<https://github.com/llvm/llvm-project/pull/170578>, <https://github.com/llvm/llvm-project/pull/173931>) RT: @abhinavgaba (<https://github.com/llvm/llvm-project/pull/169603>) |
+| dims clause with strict behavior (multidimensional teams and leagues) | {part}`In Progress` | {part}`In Progress` | C/C++: kevinsala Fortran: skc7, kparzysz, mjklemm |
+
+## OpenMP Extensions
The following table provides a quick overview over various OpenMP
-extensions and their implementation status. These extensions are not
+extensions and their implementation status. These extensions are not
currently defined by any standard, so links to associated LLVM
-documentation are provided. As these extensions mature, they will be
+documentation are provided. As these extensions mature, they will be
considered for standardization. Please post on the
-`Discourse forums (Runtimes - OpenMP category)`_ to provide feedback.
-
-+------------------------------+-----------------------------------------------------------------------------------+--------------------------+--------------------------------------------------------+
-|Category | Feature | Status | Reviews |
-+==============================+===================================================================================+==========================+========================================================+
-| atomic extension | `'atomic' strictly nested within 'teams' | :part:`prototyped` | D126323 |
-| | <https://openmp.llvm.org/docs/openacc/OpenMPExtensions.html#atomicWithinTeams>`_ | | |
-+------------------------------+-----------------------------------------------------------------------------------+--------------------------+--------------------------------------------------------+
-| device extension | `'ompx_hold' map type modifier | :part:`prototyped` | D106509, D106510 |
-| | <https://openmp.llvm.org/docs/openacc/OpenMPExtensions.html#ompx-hold>`_ | | |
-+------------------------------+-----------------------------------------------------------------------------------+--------------------------+--------------------------------------------------------+
-| device extension | `'ompx_bare' clause on 'target teams' construct | :part:`prototyped` | #66844, #70612 |
-| | <https://www.osti.gov/servlets/purl/2205717>`_ | | |
-+------------------------------+-----------------------------------------------------------------------------------+--------------------------+--------------------------------------------------------+
-| device extension | Multi-dim 'num_teams' and 'thread_limit' clause on 'target teams ompx_bare' | :part:`partial` | #99732, #101407, #102715 |
-| | construct | | |
-+------------------------------+-----------------------------------------------------------------------------------+--------------------------+--------------------------------------------------------+
-
-.. _Discourse forums (Runtimes - OpenMP category): https://discourse.llvm.org/c/runtimes/openmp/35
+[Discourse forums (Runtimes - OpenMP category)] to provide feedback.
+
+| Category | Feature | Status | Reviews |
+| ---------------- | ----------------------------------------------------------------------------------------------------------------------- | ------------------ | ------------------------ |
+| atomic extension | ['atomic' strictly nested within 'teams'](https://openmp.llvm.org/docs/openacc/OpenMPExtensions.html#atomicWithinTeams) | {part}`prototyped` | D126323 |
+| device extension | ['ompx_hold' map type modifier](https://openmp.llvm.org/docs/openacc/OpenMPExtensions.html#ompx-hold) | {part}`prototyped` | D106509, D106510 |
+| device extension | ['ompx_bare' clause on 'target teams' construct](https://www.osti.gov/servlets/purl/2205717) | {part}`prototyped` | #66844, #70612 |
+| device extension | Multi-dim 'num_teams' and 'thread_limit' clause on 'target teams ompx_bare' construct | {part}`partial` | #99732, #101407, #102715 |
+
+[discourse forums (runtimes - openmp category)]: https://discourse.llvm.org/c/runtimes/openmp/35
+
diff --git a/clang/docs/OverflowBehaviorTypes.md b/clang/docs/OverflowBehaviorTypes.md
index 0bedbc9a1a39c..06a44841b11ec 100644
--- a/clang/docs/OverflowBehaviorTypes.md
+++ b/clang/docs/OverflowBehaviorTypes.md
@@ -1,12 +1,10 @@
-=====================
-OverflowBehaviorTypes
-=====================
+# OverflowBehaviorTypes
-.. contents::
- :local:
+```{contents}
+:local: true
+```
-Introduction
-============
+## Introduction
Clang provides overflow behavior types that allow developers to have
fine-grained control over the overflow behavior of integer types. Overflow
@@ -16,103 +14,100 @@ overflow. This is particularly useful for projects that need to balance
performance and safety, allowing developers to enable or disable overflow
checks for specific types.
-Overflow behavior types can be enabled using the ``-cc1`` compiler option
-``-fexperimental-overflow-behavior-types``.
+Overflow behavior types can be enabled using the `-cc1` compiler option
+`-fexperimental-overflow-behavior-types`.
-.. note::
-
- This feature is experimental. The flag spelling may change in future
- releases as the feature matures.
+:::{note}
+This feature is experimental. The flag spelling may change in future
+releases as the feature matures.
+:::
There are two syntax options for specifying overflow behavior:
**Attribute syntax:**
-.. code-block:: c++
-
- __attribute__((overflow_behavior(behavior)))
+```c++
+__attribute__((overflow_behavior(behavior)))
+```
-Where ``behavior`` can be one of the following:
+Where `behavior` can be one of the following:
-* ``wrap``: Specifies that arithmetic operations on the integer type should
- wrap on overflow. This is equivalent to the behavior of ``-fwrapv``, but it
+- `wrap`: Specifies that arithmetic operations on the integer type should
+ wrap on overflow. This is equivalent to the behavior of `-fwrapv`, but it
applies only to the attributed type and may be used with both signed and
unsigned types. When this is enabled, UBSan's integer overflow and integer
- truncation checks (``signed-integer-overflow``,
- ``unsigned-integer-overflow``, ``implicit-signed-integer-truncation``, and
- ``implicit-unsigned-integer-truncation``) are suppressed for the attributed
- type. Similar to ``-fwrapv``, this behavior defines wrapping behavior which
+ truncation checks (`signed-integer-overflow`,
+ `unsigned-integer-overflow`, `implicit-signed-integer-truncation`, and
+ `implicit-unsigned-integer-truncation`) are suppressed for the attributed
+ type. Similar to `-fwrapv`, this behavior defines wrapping behavior which
also disables eager compiler optimizations concerning undefined behaviors.
-
-* ``trap``: Specifies that arithmetic operations on the integer type should
- be checked for overflow. When using the ``signed-integer-overflow`` sanitizer
- or when using ``-ftrapv`` alongside a signed type, this is the default
+- `trap`: Specifies that arithmetic operations on the integer type should
+ be checked for overflow. When using the `signed-integer-overflow` sanitizer
+ or when using `-ftrapv` alongside a signed type, this is the default
behavior. Using this, one may enforce overflow checks for a type even when
- ``-fwrapv`` is enabled globally.
+ `-fwrapv` is enabled globally.
**Keyword syntax:**
-.. code-block:: c++
+```c++
+__ob_wrap // equivalent to __attribute__((overflow_behavior(wrap)))
+__ob_trap // equivalent to __attribute__((overflow_behavior(trap)))
+```
- __ob_wrap // equivalent to __attribute__((overflow_behavior(wrap)))
- __ob_trap // equivalent to __attribute__((overflow_behavior(trap)))
-
-Either of these spellings can be applied to ``typedef`` declarations and to
+Either of these spellings can be applied to `typedef` declarations and to
integer types directly.
Arithmetic operations containing one or more overflow behavior types follow
standard C integer promotion and conversion rules while preserving overflow
behavior information.
-Examples
-========
+## Examples
Here are examples using both syntax options:
**Using attribute syntax with a typedef:**
-.. code-block:: c++
-
- typedef unsigned int __attribute__((overflow_behavior(trap))) non_wrapping_uint;
+```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.
- }
+non_wrapping_uint add_one(non_wrapping_uint a) {
+ return a + 1; // Overflow is checked for this operation.
+}
+```
**Using keyword syntax with a typedef:**
-.. code-block:: c++
-
- typedef unsigned int __ob_trap non_wrapping_uint;
+```c++
+typedef unsigned int __ob_trap non_wrapping_uint;
- non_wrapping_uint add_one(non_wrapping_uint a) {
- return a + 1; // Overflow is checked for this operation.
- }
+non_wrapping_uint add_one(non_wrapping_uint a) {
+ return a + 1; // Overflow is checked for this operation.
+}
+```
**Using attribute syntax with a type directly:**
-.. code-block:: c++
-
- int mul_alot(int n) {
- int __attribute__((overflow_behavior(wrap))) a = n;
- return a * 1337; // Potential overflow is not checked and is well-defined
- }
+```c++
+int mul_alot(int n) {
+ int __attribute__((overflow_behavior(wrap))) a = n;
+ return a * 1337; // Potential overflow is not checked and is well-defined
+}
+```
**Using keyword syntax with a type directly:**
-.. code-block:: c++
-
- int mul_alot(int n) {
- int __ob_wrap a = n;
- return a * 1337; // Potential overflow is not checked and is well-defined
- }
+```c++
+int mul_alot(int n) {
+ int __ob_wrap a = n;
+ return a * 1337; // Potential overflow is not checked and is well-defined
+}
+```
"Well-defined" overflow is consistent with two's complement wrap-around
semantics and won't be removed via eager compiler optimizations (like some
undefined behavior might).
-Promotion Rules
-===============
+## Promotion Rules
Overflow behavior types (OBTs) follow the traditional C integer promotion and
conversion rules while propagating overflow behavior qualifiers through
@@ -122,41 +117,41 @@ maintaining overflow behavior information throughout arithmetic expressions.
The resulting type characteristics for overflow behavior types (OBTs) across a
variety of scenarios is detailed below.
-* **OBT and Standard Integer Type**: The result follows standard C conversion
+- **OBT and Standard Integer Type**: The result follows standard C conversion
rules, with the OBT qualifier applied to the standard result type.
- .. code-block:: c++
-
- typedef char __ob_trap trap_char;
- trap_char c;
- unsigned long ul;
- auto result = c + ul; // result is __ob_trap unsigned long
+ ```c++
+ typedef char __ob_trap trap_char;
+ trap_char c;
+ unsigned long ul;
+ auto result = c + ul; // result is __ob_trap unsigned long
+ ```
-* **Two OBTs with Same Behavior**: When both operands have the same overflow
+- **Two OBTs with Same Behavior**: When both operands have the same overflow
behavior, the result follows standard C arithmetic conversions with that
behavior applied.
- .. code-block:: c++
+ ```c++
+ typedef unsigned char __ob_wrap u8_wrap;
+ typedef unsigned short __ob_wrap u16_wrap;
+ u8_wrap a;
+ u16_wrap b;
+ auto result = a + b; // result is __ob_wrap int (C promotes both to int)
+ ```
- typedef unsigned char __ob_wrap u8_wrap;
- typedef unsigned short __ob_wrap u16_wrap;
- u8_wrap a;
- u16_wrap b;
- auto result = a + b; // result is __ob_wrap int (C promotes both to int)
-
-* **Two OBTs with Different Behaviors**: ``trap`` behavior dominates ``wrap``
- behavior. The result follows standard C arithmetic conversions with ``trap``
+- **Two OBTs with Different Behaviors**: `trap` behavior dominates `wrap`
+ behavior. The result follows standard C arithmetic conversions with `trap`
behavior applied.
- .. code-block:: c++
-
- typedef unsigned short __ob_wrap u16_wrap;
- typedef int __ob_trap int_trap;
- u16_wrap a;
- int_trap b;
- auto result = a + b; // result is __ob_trap int (C promotes u16->int, dominance gives trap)
-
+ ```c++
+ typedef unsigned short __ob_wrap u16_wrap;
+ typedef int __ob_trap int_trap;
+ u16_wrap a;
+ int_trap b;
+ auto result = a + b; // result is __ob_trap int (C promotes u16->int, dominance gives trap)
+ ```
+```{eval-rst}
.. list-table:: Promotion Rules Summary
:widths: 30 70
:header-rows: 1
@@ -169,18 +164,18 @@ variety of scenarios is detailed below.
- Standard C conversion result with common overflow behavior
* - Different Kind OBTs (``wrap`` + ``trap``)
- Standard C conversion result with ``trap`` behavior (dominance)
+```
**Overflow Behavior Dominance Rules:**
-1. If either operand has ``trap`` behavior → result has ``trap`` behavior
-2. If either operand has ``wrap`` behavior (and neither has ``trap`) → result has ``wrap`` behavior
+1. If either operand has `trap` behavior → result has `trap` behavior
+2. If either operand has `wrap` behavior (and neither has ``` trap`) → result has ``wrap ``` behavior
3. Otherwise → no overflow behavior annotation
This model preserves traditional C semantics while ensuring overflow behavior
information is correctly propagated through arithmetic expressions.
-Pointer Semantics
------------------
+### Pointer Semantics
Overflow behavior types can be used with pointers, where the overflow behavior
annotation applies to the pointee type. Pointers to overflow behavior types
@@ -197,23 +192,22 @@ operations.
When assigning from a overflow behavior annotated type to a regular integer
type, the compiler issues a warning about discarding overflow behavior. This is
-controlled by the ``-Wincompatible-pointer-types-discards-overflow-behavior``
+controlled by the `-Wincompatible-pointer-types-discards-overflow-behavior`
diagnostic.
-.. code-block:: c++
+```c++
+unsigned long *px;
+unsigned long __ob_trap *py;
+unsigned long __ob_wrap *pz;
- unsigned long *px;
- unsigned long __ob_trap *py;
- unsigned long __ob_wrap *pz;
+// Discarding overflow behavior - warns but allowed
+px = py; // warning: assigning to 'unsigned long *' from
+ // '__ob_trap unsigned long *' discards overflow behavior
+py = px; // warning: assigning to '__ob_trap unsigned long *' from
+ // 'unsigned long *' discards overflow behavior
+```
- // Discarding overflow behavior - warns but allowed
- px = py; // warning: assigning to 'unsigned long *' from
- // '__ob_trap unsigned long *' discards overflow behavior
- py = px; // warning: assigning to '__ob_trap unsigned long *' from
- // 'unsigned long *' discards overflow behavior
-
-Conversion Semantics
-====================
+## Conversion Semantics
Overflow behavior types are implicitly convertible to and from built-in
integral types with specific semantics for warnings and constant evaluation.
@@ -221,21 +215,20 @@ integral types with specific semantics for warnings and constant evaluation.
**Incompatible Overflow Behaviors:**
Attempting to assign or convert between types with incompatible overflow
-behaviors (``trap`` vs ``wrap``) results in a compilation error, as these
+behaviors (`trap` vs `wrap`) results in a compilation error, as these
represent fundamentally different behavioral contracts.
-.. code-block:: c++
-
- int __ob_trap a;
- int __ob_wrap b;
- a = b; // error: assigning to '__ob_trap int' from '__ob_wrap int' with
- // incompatible overflow behavior types ('__ob_trap' and '__ob_wrap')
+```c++
+int __ob_trap a;
+int __ob_wrap b;
+a = b; // error: assigning to '__ob_trap int' from '__ob_wrap int' with
+ // incompatible overflow behavior types ('__ob_trap' and '__ob_wrap')
+```
The Diagnostics section further below details the exact diagnostics Clang
provides for overflow behavior types.
-Truncation Semantics
---------------------
+### Truncation Semantics
Truncation and overflow are related and are both often desirable in some
contexts and undesirable in others. To provide control over these behaviors,
@@ -251,34 +244,31 @@ related to truncation.
When an overflow behavior type is involved as the source or destination type of
truncation, instrumentation checks behave as follows:
-* **One or more types is 'trap'**: Truncation checks are inserted and may issue
+- **One or more types is 'trap'**: Truncation checks are inserted and may issue
either a trap or sanitizer warning based on compiler settings.
-
-* **One or more types is 'wrap'**: No truncation checks are added regardless of
+- **One or more types is 'wrap'**: No truncation checks are added regardless of
compiler flags because truncation with wrapping behavior well-defined. If any
- of the types is ``trap`` then the truncation rules match the behavior
+ of the types is `trap` then the truncation rules match the behavior
mentioned above.
-
-* **Both types are standard integer types**: Behaviors surrounding standard
+- **Both types are standard integer types**: Behaviors surrounding standard
integer types is unchanged.
-.. code-block:: c++
-
- void foo(char a, int __ob_trap b) {
- a = b; // truncation checks are inserted, may trap
- }
+```c++
+void foo(char a, int __ob_trap b) {
+ a = b; // truncation checks are inserted, may trap
+}
- void bar(char a, int __ob_wrap b) {
- a = b; // sanitizer truncation checks disallowed
- }
+void bar(char a, int __ob_wrap b) {
+ a = b; // sanitizer truncation checks disallowed
+}
+```
Note that truncation itself is a form of overflow behavior - when a value is
too large to fit in the destination type, the high-order bits are discarded,
-which is a wrapping behavior that ``wrap`` types are designed to handle
+which is a wrapping behavior that `wrap` types are designed to handle
predictably.
-Constant Conversion Semantics
-------------------------------
+### Constant Conversion Semantics
When converting constant values to overflow behavior types, the behavior
depends on the overflow behavior annotation and whether the conversion would
@@ -287,23 +277,22 @@ change the value:
**With 'wrap' types:**
Constant conversions that would overflow are accepted without warning when
-assigning to or explicitly casting to ``wrap`` types, as wrapping is the
+assigning to or explicitly casting to `wrap` types, as wrapping is the
intended behavior:
-.. code-block:: c++
-
- short x1 = (int __ob_wrap)100000; // OK: explicit wrap cast
- short __ob_wrap x2 = (int)100000; // OK: wrap destination
- unsigned short __ob_wrap ux = 100000; // OK: wrapping expected
+```c++
+short x1 = (int __ob_wrap)100000; // OK: explicit wrap cast
+short __ob_wrap x2 = (int)100000; // OK: wrap destination
+unsigned short __ob_wrap ux = 100000; // OK: wrapping expected
+```
**With 'trap' types:**
Constant conversions that would change the value generate a warning when the
-destination is a ``trap`` type. This matches the behavior of regular non-OBT
+destination is a `trap` type. This matches the behavior of regular non-OBT
constant conversions.
-Implicit Conversions Due to Assignment
---------------------------------------
+### Implicit Conversions Due to Assignment
Like with the basic integral types in C and C++, types on the right-hand side
of an assignment may be implicitly converted to match the left-hand side.
@@ -311,35 +300,34 @@ of an assignment may be implicitly converted to match the left-hand side.
All built-in integral types can be implicitly converted to an overflow behavior
version.
-.. code-block:: c++
-
- char x = 1;
- int __ob_wrap a = x; // x converted to __ob_wrap int
+```c++
+char x = 1;
+int __ob_wrap a = x; // x converted to __ob_wrap int
+```
Assigning one overflow behavior type to another is legal only when the two
-types have matching overflow behavior kinds (i.e., ``wrap`` and ``wrap`` or
-``trap`` and ``trap``). Assigning overflow behavior types with differing
+types have matching overflow behavior kinds (i.e., `wrap` and `wrap` or
+`trap` and `trap`). Assigning overflow behavior types with differing
behavior kinds will result in an error.
-.. code-block:: c++
-
- int __ob_trap trap_var;
- int __ob_wrap wrap_var;
+```c++
+int __ob_trap trap_var;
+int __ob_wrap wrap_var;
- trap_var = wrap_var; // error: assigning to '__ob_trap int' from
- // '__ob_wrap int' with incompatible overflow
- // behavior types ('__ob_trap' and '__ob_wrap')
+trap_var = wrap_var; // error: assigning to '__ob_trap int' from
+ // '__ob_wrap int' with incompatible overflow
+ // behavior types ('__ob_trap' and '__ob_wrap')
+```
However, conversions between compatible overflow behavior types (same kind,
different underlying widths or signedness) are allowed:
-.. code-block:: c++
-
- long __ob_wrap x = __LONG_MAX__;
- int __ob_wrap a = x; // OK: both have 'wrap' behavior
+```c++
+long __ob_wrap x = __LONG_MAX__;
+int __ob_wrap a = x; // OK: both have 'wrap' behavior
+```
-C++ Overload Resolution
------------------------
+### C++ Overload Resolution
For the purposes of C++ overload set formation, promotions or conversions to
and from overflow behavior types are of the same rank as normal integer
@@ -349,105 +337,101 @@ candidate selection which may lead to unexpected but correct ambiguity errors.
The example below shows potential ambiguity as matching just the underlying
type of an OBT parameter is not enough to precisely pick an overload candidate.
-.. code-block:: c++
+```c++
+void foo(int __ob_trap a);
+void foo(short a);
- void foo(int __ob_trap a);
- void foo(short a);
-
- void bar(int a) {
- foo(a); // call to 'foo' is ambiguous
- }
+void bar(int a) {
+ foo(a); // call to 'foo' is ambiguous
+}
+```
Most integral types can be implicitly converted to match OBT parameter types
and this can be done unambiguously in certain cases. Especially, when all other
candidates are not implicitly convertible.
-.. code-block:: c++
-
- void foo(int __ob_trap a);
- void foo(char *a);
-
- void bar(int a) {
- foo(a); // picks foo(__ob_trap int)
- }
+```c++
+void foo(int __ob_trap a);
+void foo(char *a);
+void bar(int a) {
+ foo(a); // picks foo(__ob_trap int)
+}
+```
Overflow behavior types with differing kinds may also create ambiguity in
certain contexts.
-.. code-block:: c++
+```c++
+void foo(int __ob_trap a);
+void foo(int __ob_wrap a);
- void foo(int __ob_trap a);
- void foo(int __ob_wrap a);
-
- void bar(int a) {
- foo(a); // call to 'foo' is ambiguous
- }
+void bar(int a) {
+ foo(a); // call to 'foo' is ambiguous
+}
+```
Overflow behavior types may also be used as template parameters and used within
-C ``_Generic`` expressions.
+C `_Generic` expressions.
-C _Generic Expressions
-----------------------
+### C \_Generic Expressions
-Overflow behavior types may be used within C ``_Generic`` expressions.
+Overflow behavior types may be used within C `_Generic` expressions.
Overflow behavior types do not match against their underlying types within C
-``_Generic`` expressions. This means that an OBT will not be considered
+`_Generic` expressions. This means that an OBT will not be considered
equivalent to its base type for generic selection purposes. OBTs will match
against exact types considering bitwidth, signedness and overflow
behavior kind.
-.. code-block:: c++
-
- int foo(int __ob_wrap x) {
- return _Generic(x, int: 1, char: 2, default: 3); // returns 3
- }
-
- int bar(int __ob_wrap x) {
- return _Generic(x, int __ob_wrap: 1, int: 2, default: 3); // returns 1
- }
+```c++
+int foo(int __ob_wrap x) {
+ return _Generic(x, int: 1, char: 2, default: 3); // returns 3
+}
+int bar(int __ob_wrap x) {
+ return _Generic(x, int __ob_wrap: 1, int: 2, default: 3); // returns 1
+}
+```
-C++ Template Specializations
------------------------------
+### C++ Template Specializations
-Like with ``_Generic``, each OBT is treated as a distinct type for template
+Like with `_Generic`, each OBT is treated as a distinct type for template
specialization purposes, enabling precise type-based template selection.
-.. code-block:: c++
+```c++
+template<typename T>
+struct TypeProcessor {
+ static constexpr int value = 0; // default case
+};
- template<typename T>
- struct TypeProcessor {
- static constexpr int value = 0; // default case
- };
+template<>
+struct TypeProcessor<int> {
+ static constexpr int value = 1; // int specialization
+};
- template<>
- struct TypeProcessor<int> {
- static constexpr int value = 1; // int specialization
- };
+template<>
+struct TypeProcessor<int __ob_wrap> {
+ static constexpr int value = 2; // __ob_wrap int specialization
+};
- template<>
- struct TypeProcessor<int __ob_wrap> {
- static constexpr int value = 2; // __ob_wrap int specialization
- };
-
- template<>
- struct TypeProcessor<int __ob_trap> {
- static constexpr int value = 3; // __ob_trap int specialization
- };
+template<>
+struct TypeProcessor<int __ob_trap> {
+ static constexpr int value = 3; // __ob_trap int specialization
+};
+```
When no exact template specialization exists for an OBT, it falls back to the
default template rather than matching the underlying type specialization,
maintaining type safety and avoiding unexpected behavior.
-Interaction with Command-Line Flags and Sanitizer Special Case Lists
-====================================================================
+## Interaction with Command-Line Flags and Sanitizer Special Case Lists
-The ``overflow_behavior`` attribute interacts with sanitizers, ``-ftrapv``,
-``-fwrapv``, and Sanitizer Special Case Lists (SSCL) by wholly overriding these
+The `overflow_behavior` attribute interacts with sanitizers, `-ftrapv`,
+`-fwrapv`, and Sanitizer Special Case Lists (SSCL) by wholly overriding these
global flags. The following table summarizes the interactions:
+```{eval-rst}
.. list-table:: Overflow Behavior Precedence
:widths: 15 15 15 15 20 15
:header-rows: 1
@@ -470,24 +454,23 @@ global flags. The following table summarizes the interactions:
- Traps
- Reports
- Overrides SSCL
+```
It is important to note the distinction between signed and unsigned types. For
-unsigned integers, which wrap on overflow by default, ``overflow_behavior(trap)``
+unsigned integers, which wrap on overflow by default, `overflow_behavior(trap)`
is particularly useful for enabling overflow checks. For signed integers, whose
-overflow behavior is undefined by default, ``overflow_behavior(wrap)`` provides
+overflow behavior is undefined by default, `overflow_behavior(wrap)` provides
a guaranteed wrapping behavior.
-The ``overflow_behavior`` attribute can be used to override the behavior of
-entries from a :doc:`SanitizerSpecialCaseList`. This is useful for allowlisting
+The `overflow_behavior` attribute can be used to override the behavior of
+entries from a {doc}`SanitizerSpecialCaseList`. This is useful for allowlisting
specific types into overflow or truncation instrumentation.
-Diagnostics
-===========
+## Diagnostics
Clang provides diagnostics to help developers manage overflow behavior types.
-Specification Errors and Warnings
-----------------------------------
+### Specification Errors and Warnings
When using overflow behavior types, several diagnostics help catch mistakes in
how the types are specified.
@@ -497,189 +480,185 @@ how the types are specified.
An error is issued when both the keyword syntax and attribute syntax are used
with incompatible overflow behaviors on the same type:
-.. code-block:: c++
-
- int __ob_wrap __attribute__((overflow_behavior(trap))) x;
- // error: conflicting overflow behavior specification; specifier
- // specifies 'wrap' but attribute specifies 'trap'
+```c++
+int __ob_wrap __attribute__((overflow_behavior(trap))) x;
+// error: conflicting overflow behavior specification; specifier
+// specifies 'wrap' but attribute specifies 'trap'
+```
**Redundant Specifications:**
A warning is issued when both syntax forms specify the same behavior, which is
redundant but allowed:
-.. code-block:: c++
-
- int __ob_wrap __attribute__((overflow_behavior(wrap))) x;
- // warning: redundant overflow behavior specification; both specifier
- // and attribute specify 'wrap'
+```c++
+int __ob_wrap __attribute__((overflow_behavior(wrap))) x;
+// warning: redundant overflow behavior specification; both specifier
+// and attribute specify 'wrap'
+```
**Feature Not Enabled:**
When overflow behavior types are used without enabling the feature via
-``-fexperimental-overflow-behavior-types``, a warning is issued and the attribute is ignored:
+`-fexperimental-overflow-behavior-types`, a warning is issued and the attribute is ignored:
-.. code-block:: c++
+```c++
+// Without -fexperimental-overflow-behavior-types
+int __attribute__((overflow_behavior(wrap))) x;
+// warning: 'overflow_behavior' attribute is ignored because it is
+// not enabled; pass -fexperimental-overflow-behavior-types
+```
- // Without -fexperimental-overflow-behavior-types
- int __attribute__((overflow_behavior(wrap))) x;
- // warning: 'overflow_behavior' attribute is ignored because it is
- // not enabled; pass -fexperimental-overflow-behavior-types
-
--Woverflow-behavior-conversion
-------------------------------
+### -Woverflow-behavior-conversion
This warning group is issued when an overflow behavior type is implicitly
converted to a standard integer type, which may lead to the loss of the
specified overflow behavior.
-.. code-block:: c++
-
- typedef int __ob_wrap wrapping_int;
+```c++
+typedef int __ob_wrap wrapping_int;
- void some_function(int);
+void some_function(int);
- void another_function(wrapping_int w) {
- some_function(w); // warning: implicit conversion from 'wrapping_int' to
- // 'int' discards overflow behavior
- }
+void another_function(wrapping_int w) {
+ some_function(w); // warning: implicit conversion from 'wrapping_int' to
+ // 'int' discards overflow behavior
+}
+```
To fix this, you can explicitly cast the overflow behavior type to a standard
integer type.
-.. code-block:: c++
-
- typedef int __ob_wrap wrapping_int;
+```c++
+typedef int __ob_wrap wrapping_int;
- void some_function(int);
+void some_function(int);
- void another_function(wrapping_int w) {
- some_function(static_cast<int>(w)); // OK
- }
+void another_function(wrapping_int w) {
+ some_function(static_cast<int>(w)); // OK
+}
+```
This warning group includes
-``-Wimplicit-overflow-behavior-conversion``, which includes
-``-Wimplicit-overflow-behavior-conversion-assignment``,
-``-Wimplicit-overflow-behavior-conversion-function-boundary``,
-``-Wimplicit-overflow-behavior-conversion-function-boundary-pedantic``, and
-``-Wimplicit-overflow-behavior-conversion-pedantic``.
+`-Wimplicit-overflow-behavior-conversion`, which includes
+`-Wimplicit-overflow-behavior-conversion-assignment`,
+`-Wimplicit-overflow-behavior-conversion-function-boundary`,
+`-Wimplicit-overflow-behavior-conversion-function-boundary-pedantic`, and
+`-Wimplicit-overflow-behavior-conversion-pedantic`.
-.. note::
- ``-Woverflow-behavior-conversion`` is implied by ``-Wconversion``.
+:::{note}
+`-Woverflow-behavior-conversion` is implied by `-Wconversion`.
+:::
--Wincompatible-pointer-types-discards-overflow-behavior
---------------------------------------------------------
+### -Wincompatible-pointer-types-discards-overflow-behavior
This warning (enabled by default) is issued when converting between pointer
types where overflow behavior information is discarded. This occurs when
assigning between pointers that differ only in their overflow behavior
annotation.
-.. code-block:: c++
+```c++
+void example() {
+ unsigned long __ob_trap *trap_ptr;
+ unsigned long *regular_ptr;
- void example() {
- unsigned long __ob_trap *trap_ptr;
- unsigned long *regular_ptr;
+ regular_ptr = trap_ptr; // warning: assigning to 'unsigned long *'
+ // from '__ob_trap unsigned long *' discards
+ // overflow behavior
- regular_ptr = trap_ptr; // warning: assigning to 'unsigned long *'
- // from '__ob_trap unsigned long *' discards
- // overflow behavior
+ trap_ptr = regular_ptr; // warning: assigning to '__ob_trap unsigned long *'
+ // from 'unsigned long *' discards overflow behavior
+}
+```
- trap_ptr = regular_ptr; // warning: assigning to '__ob_trap unsigned long *'
- // from 'unsigned long *' discards overflow behavior
- }
-
-This warning is part of the ``-Wincompatible-pointer-types`` group and helps
+This warning is part of the `-Wincompatible-pointer-types` group and helps
catch potential bugs where overflow behavior contracts may be inadvertently
lost through pointer conversions.
--Wimplicit-overflow-behavior-conversion
----------------------------------------
+### -Wimplicit-overflow-behavior-conversion
This warning is issued when an overflow behavior type is implicitly converted
to a standard integer type as part of most conversions, which may lead to the
loss of the specified overflow behavior. This is the main warning in the
-``-Woverflow-behavior-conversion`` group.
-
-.. code-block:: c++
-
- typedef int __ob_wrap wrapping_int;
+`-Woverflow-behavior-conversion` group.
- void some_function() {
- wrapping_int w = 1;
- int i = w; // warning: implicit conversion from 'wrapping_int' to 'int'
- // during assignment discards overflow behavior
- // [-Wimplicit-overflow-behavior-conversion]
- }
+```c++
+typedef int __ob_wrap wrapping_int;
-Here's another example showing function parameter conversion with a ``trap`` type:
+void some_function() {
+ wrapping_int w = 1;
+ int i = w; // warning: implicit conversion from 'wrapping_int' to 'int'
+ // during assignment discards overflow behavior
+ // [-Wimplicit-overflow-behavior-conversion]
+}
+```
-.. code-block:: c++
+Here's another example showing function parameter conversion with a `trap` type:
- typedef int __ob_trap safe_int;
+```c++
+typedef int __ob_trap safe_int;
- void bar(int x); // Function expects standard int
+void bar(int x); // Function expects standard int
- void foo() {
- safe_int s = 42;
- bar(s); // warning: implicit conversion from 'safe_int' to 'int'
- // discards overflow behavior
- // [-Wimplicit-overflow-behavior-conversion]
- }
+void foo() {
+ safe_int s = 42;
+ bar(s); // warning: implicit conversion from 'safe_int' to 'int'
+ // discards overflow behavior
+ // [-Wimplicit-overflow-behavior-conversion]
+}
+```
To fix this, you can explicitly cast the overflow behavior type to a standard
integer type.
-.. code-block:: c++
+```c++
+typedef int __ob_wrap wrapping_int;
+typedef int __ob_trap safe_int;
- typedef int __ob_wrap wrapping_int;
- typedef int __ob_trap safe_int;
+void some_function() {
+ wrapping_int w = 1;
+ int i = static_cast<int>(w); // OK
+ int j = (int)w; // C-style OK
+}
- void some_function() {
- wrapping_int w = 1;
- int i = static_cast<int>(w); // OK
- int j = (int)w; // C-style OK
- }
+void bar(int x);
- void bar(int x);
+void foo() {
+ safe_int s = 42;
+ bar(static_cast<int>(s)); // OK
+}
+```
- void foo() {
- safe_int s = 42;
- bar(static_cast<int>(s)); // OK
- }
-
-
--Wimplicit-overflow-behavior-conversion-assignment
---------------------------------------------------
+### -Wimplicit-overflow-behavior-conversion-assignment
This warning is issued specifically when an overflow behavior type is
implicitly converted to a standard integer type during assignment operations or
variable initialization. This is a subset of the more general
-``-Wimplicit-overflow-behavior-conversion`` warning, allowing developers to
+`-Wimplicit-overflow-behavior-conversion` warning, allowing developers to
control assignment-specific warnings separately. This warning is disabled by
default.
-.. code-block:: c++
-
- typedef int __ob_wrap wrapping_int;
+```c++
+typedef int __ob_wrap wrapping_int;
- void some_function() {
- wrapping_int w = 1;
- int i = w; // warning: implicit conversion from 'wrapping_int' to 'int'
- // during assignment discards overflow behavior
- // [-Wimplicit-overflow-behavior-conversion-assignment]
- }
+void some_function() {
+ wrapping_int w = 1;
+ int i = w; // warning: implicit conversion from 'wrapping_int' to 'int'
+ // during assignment discards overflow behavior
+ // [-Wimplicit-overflow-behavior-conversion-assignment]
+}
+```
This also applies to variable initialization:
-.. code-block:: c++
-
- void another_example() {
- int __ob_trap safe = 42;
- int regular = safe; // warning: implicit conversion from '__ob_trap int'
- // to 'int' during assignment discards overflow behavior
- // [-Wimplicit-overflow-behavior-conversion-assignment]
- }
+```c++
+void another_example() {
+ int __ob_trap safe = 42;
+ int regular = safe; // warning: implicit conversion from '__ob_trap int'
+ // to 'int' during assignment discards overflow behavior
+ // [-Wimplicit-overflow-behavior-conversion-assignment]
+}
+```
This diagnostic can be controlled independently, allowing projects to suppress
assignment-related warnings while still receiving warnings for other types of
@@ -688,145 +667,139 @@ implicit conversions (such as function parameter passing).
Note that when assigning from a non-OBT type to an OBT type, no warning is
issued as overflow behavior is being added, not discarded:
-.. code-block:: c++
-
- void adding_obt_is_ok() {
- int plain = 42;
- int __ob_wrap wrapped = plain; // OK - adding overflow behavior, no warning
- }
+```c++
+void adding_obt_is_ok() {
+ int plain = 42;
+ int __ob_wrap wrapped = plain; // OK - adding overflow behavior, no warning
+}
+```
--Wimplicit-overflow-behavior-conversion-assignment-pedantic
------------------------------------------------------------
+### -Wimplicit-overflow-behavior-conversion-assignment-pedantic
A less severe version of
-``-Wimplicit-overflow-behavior-conversion-assignment`` which is issued only
-when an unsigned ``wrap`` type is implicitly converted to a standard unsigned
+`-Wimplicit-overflow-behavior-conversion-assignment` which is issued only
+when an unsigned `wrap` type is implicitly converted to a standard unsigned
integer type during assignment. This is considered less problematic than other
conversions because unsigned integers already have well-defined wrapping
behavior by the C standard.
-.. code-block:: c++
-
- void example() {
- unsigned int __ob_wrap wrapped_uint = 42;
- unsigned int regular = wrapped_uint; // warning: implicit conversion from
- // '__ob_wrap unsigned int' to
- // 'unsigned int' during assignment
- // discards overflow behavior
- // [-Wimplicit-overflow-behavior-conversion-assignment-pedantic]
- }
+```c++
+void example() {
+ unsigned int __ob_wrap wrapped_uint = 42;
+ unsigned int regular = wrapped_uint; // warning: implicit conversion from
+ // '__ob_wrap unsigned int' to
+ // 'unsigned int' during assignment
+ // discards overflow behavior
+ // [-Wimplicit-overflow-behavior-conversion-assignment-pedantic]
+}
+```
This warning is useful for projects that want to track all overflow behavior
annotations but consider unsigned wrapping conversions to be lower priority
-than signed conversions or ``trap`` conversions.
+than signed conversions or `trap` conversions.
--Wimplicit-overflow-behavior-conversion-function-boundary
-----------------------------------------------------------
+### -Wimplicit-overflow-behavior-conversion-function-boundary
This warning (disabled by default) is issued when an overflow behavior type is
passed as an argument to a function parameter that does not have the same
overflow behavior annotation. This helps identify situations where overflow
behavior contracts may be lost at function boundaries.
-.. code-block:: c++
+```c++
+void process_value(int x); // Function expects standard int
- void process_value(int x); // Function expects standard int
-
- void caller() {
- int __ob_trap safe_value = 42;
- process_value(safe_value); // warning: passing argument of type
- // '__ob_trap int' to parameter of type 'int'
- // discards overflow behavior at function boundary
- // [-Wimplicit-overflow-behavior-conversion-function-boundary]
- }
+void caller() {
+ int __ob_trap safe_value = 42;
+ process_value(safe_value); // warning: passing argument of type
+ // '__ob_trap int' to parameter of type 'int'
+ // discards overflow behavior at function boundary
+ // [-Wimplicit-overflow-behavior-conversion-function-boundary]
+}
+```
This warning can be particularly useful for catching cases where overflow
checking behavior is lost when crossing API boundaries. Both the general
version
-(``-Wimplicit-overflow-behavior-conversion-function-boundary``) and a pedantic
-version (``-Wimplicit-overflow-behavior-conversion-function-boundary-pedantic``)
+(`-Wimplicit-overflow-behavior-conversion-function-boundary`) and a pedantic
+version (`-Wimplicit-overflow-behavior-conversion-function-boundary-pedantic`)
for unsigned wrapping types are disabled by default.
To fix this warning, you can either:
1. Update the function parameter to accept the overflow behavior type:
-.. code-block:: c++
-
- void process_value(int __ob_trap x); // Accept trap-annotated int
+```c++
+void process_value(int __ob_trap x); // Accept trap-annotated int
- void caller() {
- int __ob_trap safe_value = 42;
- process_value(safe_value); // OK
- }
+void caller() {
+ int __ob_trap safe_value = 42;
+ process_value(safe_value); // OK
+}
+```
2. Explicitly cast at the call site to acknowledge the loss of overflow behavior:
-.. code-block:: c++
-
- void process_value(int x);
+```c++
+void process_value(int x);
- void caller() {
- int __ob_trap safe_value = 42;
- process_value((int)safe_value); // OK - explicit cast
- }
+void caller() {
+ int __ob_trap safe_value = 42;
+ process_value((int)safe_value); // OK - explicit cast
+}
+```
--Wimplicit-overflow-behavior-conversion-function-boundary-pedantic
-------------------------------------------------------------------
+### -Wimplicit-overflow-behavior-conversion-function-boundary-pedantic
A less severe version of the warning above which is issued only in the case of
-unsigned ``wrap`` types being passed to a function expecting a standard
+unsigned `wrap` types being passed to a function expecting a standard
unsigned integer type. This is a less problematic issue since the standard and
well-defined overflow procedure for unsigned integer types is essentially
-``wrap``.
+`wrap`.
-
-Format String Functions
-=======================
+## Format String Functions
When overflow behavior types are used with format string functions (printf-family
-functions like ``printf``, ``fprintf``, ``sprintf``, etc., and scanf-family
-functions like ``scanf``, ``fscanf``, ``sscanf``, etc.), they are treated based
+functions like `printf`, `fprintf`, `sprintf`, etc., and scanf-family
+functions like `scanf`, `fscanf`, `sscanf`, etc.), they are treated based
on their underlying integer types for format specifier compatibility checking.
More generally, overflow behavior types are ABI-compatible with their underlying
types when passed to any varargs function.
-.. code-block:: c++
-
- #include <cstdio>
+```c++
+#include <cstdio>
- typedef int __ob_wrap wrap_int;
- typedef unsigned int __ob_trap nowrap_uint;
+typedef int __ob_wrap wrap_int;
+typedef unsigned int __ob_trap nowrap_uint;
- void example() {
- wrap_int wi = 42;
- nowrap_uint su = 100;
+void example() {
+ wrap_int wi = 42;
+ nowrap_uint su = 100;
- scanf("%d\n", &wi); // OK: &wi treated as int* for %d
- printf("%d\n", wi); // OK: wi treated as int for %d
- printf("%u\n", su); // OK: su treated as unsigned int for %u
- printf("%s\n", wi); // Error: int incompatible with %s (same as regular int)
- }
+ scanf("%d\n", &wi); // OK: &wi treated as int* for %d
+ printf("%d\n", wi); // OK: wi treated as int for %d
+ printf("%u\n", su); // OK: su treated as unsigned int for %u
+ printf("%s\n", wi); // Error: int incompatible with %s (same as regular int)
+}
+```
This behavior ensures that overflow behavior types work seamlessly with existing
format string functions without requiring special format specifiers, while
still maintaining their overflow behavior semantics in arithmetic operations.
The format string checker uses the underlying type to determine compatibility,
-so ``int __ob_wrap`` is fully compatible with ``%d``, ``%i``, ``%x``, etc.,
-just like a regular ``int`` would be.
+so `int __ob_wrap` is fully compatible with `%d`, `%i`, `%x`, etc.,
+just like a regular `int` would be.
-Incompatibility With Non-Integer Types
---------------------------------------
+### Incompatibility With Non-Integer Types
An error is issued when attempting to create an overflow behavior type from
a non-integer type.
-.. code-block:: c++
-
- typedef float __attribute__((overflow_behavior(wrap))) wrapping_float;
- // error: 'overflow_behavior' attribute cannot be applied to non-integer type 'float'
+```c++
+typedef float __attribute__((overflow_behavior(wrap))) wrapping_float;
+// error: 'overflow_behavior' attribute cannot be applied to non-integer type 'float'
- typedef struct S { int i; } __attribute__((overflow_behavior(wrap))) S_t;
- // error: 'overflow_behavior' attribute cannot be applied to non-integer type 'struct S'
+typedef struct S { int i; } __attribute__((overflow_behavior(wrap))) S_t;
+// error: 'overflow_behavior' attribute cannot be applied to non-integer type 'struct S'
+```
diff --git a/clang/docs/PointerAuthentication.md b/clang/docs/PointerAuthentication.md
index 475ccebd6b72d..ade185b238e69 100644
--- a/clang/docs/PointerAuthentication.md
+++ b/clang/docs/PointerAuthentication.md
@@ -1,246 +1,227 @@
-Pointer Authentication
-======================
+# Pointer Authentication
-.. contents::
- :local:
+```{contents}
+:local: true
+```
-Introduction
-------------
+## Introduction
Pointer authentication is a technology which offers strong probabilistic
protection against exploiting a broad class of memory bugs to take control of
-program execution. When adopted consistently in a language ABI, it provides
+program execution. When adopted consistently in a language ABI, it provides
a form of relatively fine-grained control flow integrity (CFI) check that
resists both return-oriented programming (ROP) and jump-oriented programming
(JOP) attacks.
While pointer authentication can be implemented purely in software, direct
hardware support (e.g. as provided by Armv8.3 PAuth) can dramatically improve
-performance and code size. Similarly, while pointer authentication
+performance and code size. Similarly, while pointer authentication
can be implemented on any architecture, taking advantage of the (typically)
excess addressing range of a target with 64-bit pointers minimizes the impact
on memory performance and can allow interoperation with existing code (by
-disabling pointer authentication dynamically). This document will generally
+disabling pointer authentication dynamically). This document will generally
attempt to present the pointer authentication feature independent of any
-hardware implementation or ABI. Considerations that are
+hardware implementation or ABI. Considerations that are
implementation-specific are clearly identified throughout.
Note that there are several different terms in use:
- **Pointer authentication** is a target-independent language technology.
-
- **PAuth** (sometimes referred to as **PAC**, for Pointer Authentication
Codes) is an AArch64 architecture extension that provides hardware support
- for pointer authentication. Additional extensions either modify some of the
+ for pointer authentication. Additional extensions either modify some of the
PAuth instruction behavior (notably FPAC), or provide new instruction
variants (PAuth_LR).
-
- **Armv8.3** is an AArch64 architecture revision that makes PAuth mandatory.
-
- **arm64e** is a specific ABI (not yet fully stable) for implementing pointer
authentication using PAuth on certain Apple operating systems.
This document serves four purposes:
- It describes the basic ideas of pointer authentication.
-
- It documents several language extensions that are useful on targets using
pointer authentication.
-
- It presents a theory of operation for the security mitigation, describing the
basic requirements for correctness, various weaknesses in the mechanism, and
ways in which programmers can strengthen its protections (including
recommendations for language implementors).
-
- It documents the stable ABI of the C, C++, and Objective-C languages on arm64e
platforms.
+## Basic concepts
-Basic concepts
---------------
-
-The simple address of an object or function is a **raw pointer**. A raw
-pointer can be **signed** to produce a **signed pointer**. A signed pointer
+The simple address of an object or function is a **raw pointer**. A raw
+pointer can be **signed** to produce a **signed pointer**. A signed pointer
can be then **authenticated** in order to verify that it was **validly signed**
-and extract the original raw pointer. These terms reflect the most likely
+and extract the original raw pointer. These terms reflect the most likely
implementation technique: computing and storing a cryptographic signature along
with the pointer.
An **abstract signing key** is a name which refers to a secret key which is
-used to sign and authenticate pointers. The concrete key value for a
+used to sign and authenticate pointers. The concrete key value for a
particular name is consistent throughout a process.
A **discriminator** is an arbitrary value used to **diversify** signed pointers
so that one validly-signed pointer cannot simply be copied over another.
A discriminator is simply opaque data of some implementation-defined size that
-is included in the signature as a salt (see `Discriminators`_ for details.)
+is included in the signature as a salt (see [Discriminators] for details.)
Nearly all aspects of pointer authentication use just these two primary
operations:
-- ``sign(raw_pointer, key, discriminator)`` produces a signed pointer given
+- `sign(raw_pointer, key, discriminator)` produces a signed pointer given
a raw pointer, an abstract signing key, and a discriminator.
-
-- ``auth(signed_pointer, key, discriminator)`` produces a raw pointer given
+- `auth(signed_pointer, key, discriminator)` produces a raw pointer given
a signed pointer, an abstract signing key, and a discriminator.
-``auth(sign(raw_pointer, key, discriminator), key, discriminator)`` must
-succeed and produce ``raw_pointer``. ``auth`` applied to a value that was
+`auth(sign(raw_pointer, key, discriminator), key, discriminator)` must
+succeed and produce `raw_pointer`. `auth` applied to a value that was
ultimately produced in any other way is expected to fail, which halts the
program either:
-- immediately, on implementations that enforce ``auth`` success (e.g., when
- using compiler-generated ``auth`` failure checks, or Armv8.3 with the FPAC
+- immediately, on implementations that enforce `auth` success (e.g., when
+ using compiler-generated `auth` failure checks, or Armv8.3 with the FPAC
extension), or
-
- when the resulting pointer value is used, on implementations that don't.
-However, regardless of the implementation's handling of ``auth`` failures, it
-is permitted for ``auth`` to fail to detect that a signed pointer was not
+However, regardless of the implementation's handling of `auth` failures, it
+is permitted for `auth` to fail to detect that a signed pointer was not
produced in this way, in which case it may return anything; this is what makes
pointer authentication a probabilistic mitigation rather than a perfect one.
There are two secondary operations which are required only to implement certain
-intrinsics in ``<ptrauth.h>``:
+intrinsics in `<ptrauth.h>`:
-- ``strip(signed_pointer, key)`` produces a raw pointer given a signed pointer
- and a key without verifying its validity, unlike ``auth``. This is useful
+- `strip(signed_pointer, key)` produces a raw pointer given a signed pointer
+ and a key without verifying its validity, unlike `auth`. This is useful
for certain kinds of tooling, such as crash backtraces; it should generally
not be used in the basic language ABI except in very careful ways.
-
-- ``sign_generic(value)`` produces a cryptographic signature for arbitrary
- data, not necessarily a pointer. This is useful for efficiently verifying
+- `sign_generic(value)` produces a cryptographic signature for arbitrary
+ data, not necessarily a pointer. This is useful for efficiently verifying
that non-pointer data has not been tampered with.
Whenever any of these operations is called for, the key value must be known
-statically. This is because the layout of a signed pointer may vary according
-to the signing key. (For example, in Armv8.3, the layout of a signed pointer
+statically. This is because the layout of a signed pointer may vary according
+to the signing key. (For example, in Armv8.3, the layout of a signed pointer
depends on whether Top Byte Ignore (TBI) is enabled, which can be set
independently for I and D keys.)
-.. admonition:: Note for API designers and language implementors
-
- These are the *primitive* operations of pointer authentication, provided for
- clarity of description. They are not suitable either as high-level
- interfaces or as primitives in a compiler IR because they expose raw
- pointers. Raw pointers require special attention in the language
- implementation to avoid the accidental creation of exploitable code
- sequences; see the section on `Attackable code sequences`_.
+:::{admonition} Note for API designers and language implementors
+These are the *primitive* operations of pointer authentication, provided for
+clarity of description. They are not suitable either as high-level
+interfaces or as primitives in a compiler IR because they expose raw
+pointers. Raw pointers require special attention in the language
+implementation to avoid the accidental creation of exploitable code
+sequences; see the section on [Attackable code sequences].
+:::
The following details are all implementation-defined:
- the nature of a signed pointer
- the size of a discriminator
- the number and nature of the signing keys
-- the implementation of the ``sign``, ``auth``, ``strip``, and ``sign_generic``
+- the implementation of the `sign`, `auth`, `strip`, and `sign_generic`
operations
While the use of the terms "sign" and "signed pointer" suggest the use of
-a cryptographic signature, other implementations may be possible. See
-`Alternative implementations`_ for an exploration of implementation options.
-
-.. admonition:: Implementation example: Armv8.3
-
- Readers may find it helpful to know how these terms map to Armv8.3 PAuth:
-
- - A signed pointer is a pointer with a signature stored in the
- otherwise-unused high bits. The kernel configures the address width based
- on the system's addressing needs, and enables TBI for I or D keys as
- needed. The bits above the address bits and below the TBI bits (if
- enabled) are unused. The signature width then depends on this addressing
- configuration.
-
- - A discriminator is a 64-bit integer. Constant discriminators are 16-bit
- integers. Blending a constant discriminator into an address consists of
- replacing the top 16 bits of the pointer containing the address with the
- constant. Pointers used for blending purposes should only have address
- bits, since higher bits will be at least partially overwritten with the
- constant discriminator.
-
- - There are five 128-bit signing-key registers, each of which can only be
- directly read or set by privileged code. Of these, four are used for
- signing pointers, and the fifth is used only for ``sign_generic``. The key
- data is simply a pepper added to the hash, not an encryption key, and so
- can be initialized using random data.
-
- - ``sign`` computes a cryptographic hash of the pointer, discriminator, and
- signing key, and stores it in the high bits as the signature. ``auth``
- removes the signature, computes the same hash, and compares the result with
- the stored signature. ``strip`` removes the signature without
- authenticating it. The ``aut`` instructions in the baseline Armv8.3 PAuth
- feature do not guarantee to trap on authentication failure; instead, they
- simply corrupt the pointer so that later uses will likely trap. Unless the
- "later use" follows immediately and cannot be recovered from (e.g. with a
- signal handler), this does not provide adequate protection against
- `authentication oracles`_, so implementations must emit additional
- instructions to force an immediate trap. This is unnecessary if the
- processor provides the optional ``FPAC`` extension, which guarantees an
- immediate trap.
-
- - ``sign_generic`` corresponds to the ``pacga`` instruction, which takes two
- 64-bit values and produces a 64-bit cryptographic hash. Implementations of
- this instruction are not required to produce meaningful data in all bits of
- the result.
-
-Discriminators
-~~~~~~~~~~~~~~
+a cryptographic signature, other implementations may be possible. See
+[Alternative implementations] for an exploration of implementation options.
+
+:::{admonition} Implementation example: Armv8.3
+Readers may find it helpful to know how these terms map to Armv8.3 PAuth:
+
+- A signed pointer is a pointer with a signature stored in the
+ otherwise-unused high bits. The kernel configures the address width based
+ on the system's addressing needs, and enables TBI for I or D keys as
+ needed. The bits above the address bits and below the TBI bits (if
+ enabled) are unused. The signature width then depends on this addressing
+ configuration.
+- A discriminator is a 64-bit integer. Constant discriminators are 16-bit
+ integers. Blending a constant discriminator into an address consists of
+ replacing the top 16 bits of the pointer containing the address with the
+ constant. Pointers used for blending purposes should only have address
+ bits, since higher bits will be at least partially overwritten with the
+ constant discriminator.
+- There are five 128-bit signing-key registers, each of which can only be
+ directly read or set by privileged code. Of these, four are used for
+ signing pointers, and the fifth is used only for `sign_generic`. The key
+ data is simply a pepper added to the hash, not an encryption key, and so
+ can be initialized using random data.
+- `sign` computes a cryptographic hash of the pointer, discriminator, and
+ signing key, and stores it in the high bits as the signature. `auth`
+ removes the signature, computes the same hash, and compares the result with
+ the stored signature. `strip` removes the signature without
+ authenticating it. The `aut` instructions in the baseline Armv8.3 PAuth
+ feature do not guarantee to trap on authentication failure; instead, they
+ simply corrupt the pointer so that later uses will likely trap. Unless the
+ "later use" follows immediately and cannot be recovered from (e.g. with a
+ signal handler), this does not provide adequate protection against
+ [authentication oracles], so implementations must emit additional
+ instructions to force an immediate trap. This is unnecessary if the
+ processor provides the optional `FPAC` extension, which guarantees an
+ immediate trap.
+- `sign_generic` corresponds to the `pacga` instruction, which takes two
+ 64-bit values and produces a 64-bit cryptographic hash. Implementations of
+ this instruction are not required to produce meaningful data in all bits of
+ the result.
+:::
+
+### Discriminators
A discriminator is arbitrary extra data which alters the signature calculated
-for a pointer. When two pointers are signed differently --- either with
+for a pointer. When two pointers are signed differently --- either with
different keys or with different discriminators --- an attacker cannot simply
replace one pointer with the other.
To use standard cryptographic terminology, a discriminator acts as a
-`salt <https://en.wikipedia.org/wiki/Salt_(cryptography)>`_ in the signing of a
+[salt](<https://en.wikipedia.org/wiki/Salt_(cryptography)>) in the signing of a
pointer, and the key data acts as a
-`pepper <https://en.wikipedia.org/wiki/Pepper_(cryptography)>`_. That is,
+[pepper](<https://en.wikipedia.org/wiki/Pepper_(cryptography)>). That is,
both the discriminator and key data are ultimately just added as inputs to the
signing algorithm along with the pointer, but they serve significantly
-different roles. The key data is a common secret added to every signature,
+different roles. The key data is a common secret added to every signature,
whereas the discriminator is a value that can be derived from
-the context in which a specific pointer is signed. However, unlike a password
+the context in which a specific pointer is signed. However, unlike a password
salt, it's important that discriminators be *independently* derived from the
circumstances of the signing; they should never simply be stored alongside
-a pointer. Discriminators are then re-derived in authentication operations.
+a pointer. Discriminators are then re-derived in authentication operations.
-The intrinsic interface in ``<ptrauth.h>`` allows an arbitrary discriminator
-value to be provided, but can only be used when running normal code. The
+The intrinsic interface in `<ptrauth.h>` allows an arbitrary discriminator
+value to be provided, but can only be used when running normal code. The
discriminators used by language ABIs must be restricted to make it feasible for
the loader to sign pointers stored in global memory without needing excessive
-amounts of metadata. Under these restrictions, a discriminator may consist of
+amounts of metadata. Under these restrictions, a discriminator may consist of
either or both of the following:
-- The address at which the pointer is stored in memory. A pointer signed with
+- The address at which the pointer is stored in memory. A pointer signed with
a discriminator which incorporates its storage address is said to have
- **address diversity**. In general, using address diversity means that
+ **address diversity**. In general, using address diversity means that
a pointer cannot be reliably copied by an attacker to or from a different
- memory location. However, an attacker may still be able to attack a larger
+ memory location. However, an attacker may still be able to attack a larger
call sequence if they can alter the address through which the pointer is
- accessed. Furthermore, some situations cannot use address diversity because
+ accessed. Furthermore, some situations cannot use address diversity because
of language or other restrictions.
-
- A constant integer, called a **constant discriminator**. A pointer signed
with a non-zero constant discriminator is said to have **constant
- diversity**. If the discriminator is specific to a single declaration, it is
+ diversity**. If the discriminator is specific to a single declaration, it is
said to have **declaration diversity**; if the discriminator is specific to
- a type of value, it is said to have **type diversity**. For example, C++
+ a type of value, it is said to have **type diversity**. For example, C++
v-tables on arm64e sign their component functions using a hash of their
method names and signatures, which provides declaration diversity; similarly,
C++ member function pointers sign their invocation functions using a hash of
the member pointer type, which provides type diversity.
The implementation may need to restrict constant discriminators to be
-significantly smaller than the full size of a discriminator. For example, on
-arm64e, constant discriminators are only 16-bit values. This is believed to
+significantly smaller than the full size of a discriminator. For example, on
+arm64e, constant discriminators are only 16-bit values. This is believed to
not significantly weaken the mitigation, since collisions remain uncommon.
The algorithm for blending a constant discriminator with a storage address is
implementation-defined.
-.. _Signing schemas:
+(signing-schemas)=
-Signing schemas
-~~~~~~~~~~~~~~~
+### Signing schemas
Correct use of pointer authentication requires the signing code and the
authenticating code to agree about the **signing schema** for the pointer:
@@ -248,9 +229,9 @@ authenticating code to agree about the **signing schema** for the pointer:
- the abstract signing key with which the pointer should be signed and
- an algorithm for computing the discriminator.
-As described in the section above on `Discriminators`_, in most situations, the
+As described in the section above on [Discriminators], in most situations, the
discriminator is produced by taking a constant discriminator and optionally
-blending it with the storage address of the pointer. In these situations, the
+blending it with the storage address of the pointer. In these situations, the
signing schema breaks down even more simply:
- the abstract signing key,
@@ -258,14 +239,12 @@ signing schema breaks down even more simply:
- whether to use address diversity.
It is important that the signing schema be independently derived at all signing
-and authentication sites. Preferably, the schema should be hard-coded
+and authentication sites. Preferably, the schema should be hard-coded
everywhere it is needed, but at the very least, it must not be derived by
-inspecting information stored along with the pointer. See the section on
-`Attacks on pointer authentication`_ for more information.
+inspecting information stored along with the pointer. See the section on
+[Attacks on pointer authentication] for more information.
-
-Language features
------------------
+## Language features
There are three levels of the pointer authentication language feature:
@@ -278,87 +257,79 @@ There are three levels of the pointer authentication language feature:
authentication to protect data values that directly or indirectly influence
control flow or program integrity, or can provide attackers with some other
powerful program compromise.
-
- The language also provides extensions to override the default rules used by
- the language implementation. For example, the ``__ptrauth`` type qualifier
+ the language implementation. For example, the `__ptrauth` type qualifier
can be used to change how pointers or pointer sized integers are signed when
they are stored in a particular variable or field; this provides much stronger
protection than is guaranteed by the default rules for C function and data
pointers.
-
-- Finally, the language provides the ``<ptrauth.h>`` intrinsic interface for
- manually signing and authenticating pointers in code. These can be used in
+- Finally, the language provides the `<ptrauth.h>` intrinsic interface for
+ manually signing and authenticating pointers in code. These can be used in
circumstances where very specific behavior is required.
-Language implementation
-~~~~~~~~~~~~~~~~~~~~~~~
+### Language implementation
For the most part, pointer authentication is an unobserved detail of the
-implementation of the programming language. Any element of the language
+implementation of the programming language. Any element of the language
implementation that would perform an indirect branch to a pointer is implicitly
altered so that the pointer is signed when first constructed and authenticated
-when the branch is performed. This includes:
+when the branch is performed. This includes:
- indirect-call features in the programming language, such as C function
pointers, C++ virtual functions, C++ member function pointers, the "blocks"
C extension, and so on;
-
- returning from a function, no matter how it is called; and
-
- indirect calls introduced by the implementation, such as branches through the
global offset table (GOT) used to implement direct calls to functions defined
outside of the current shared object.
-For more information about this, see the `Language ABI`_ section.
+For more information about this, see the [Language ABI] section.
However, some aspects of the implementation are observable by the programmer or
otherwise require special notice.
-C data pointers
-^^^^^^^^^^^^^^^
+#### C data pointers
The current implementation in Clang does not sign pointers to ordinary data by
default. For a partial explanation of the reasoning behind this, see the
-`Theory of Operation`_ section.
+[Theory of Operation] section.
A specific data pointer which is more security-sensitive than most can be
-signed using the `__ptrauth qualifier`_ or using the ``<ptrauth.h>``
+signed using the [\_\_ptrauth qualifier][__ptrauth qualifier] or using the `<ptrauth.h>`
intrinsics.
-C function pointers
-^^^^^^^^^^^^^^^^^^^
+#### C function pointers
The C standard imposes restrictions on the representation and semantics of
function pointer types which make it difficult to achieve satisfactory
-signature diversity in the default language rules. See `Attacks on pointer
-authentication`_ for more information about signature diversity. Programmers
-should strongly consider using the ``__ptrauth`` qualifier to improve the
+signature diversity in the default language rules. See [Attacks on pointer
+authentication][attacks on pointer authentication] for more information about signature diversity. Programmers
+should strongly consider using the `__ptrauth` qualifier to improve the
protections for important function pointers, such as the components of of
-a hand-rolled "v-table"; see the section on the `__ptrauth qualifier`_ for
+a hand-rolled "v-table"; see the section on the [\_\_ptrauth qualifier][__ptrauth qualifier] for
details.
The value of a pointer to a C function includes a signature, even when the
-value is cast to a non-function-pointer type like ``void*`` or ``intptr_t``. On
+value is cast to a non-function-pointer type like `void*` or `intptr_t`. On
implementations that use high bits to store the signature, this means that
relational comparisons and hashes will vary according to the exact signature
-value, which is likely to change between executions of a program. In some
+value, which is likely to change between executions of a program. In some
implementations, it may also vary based on the exact function pointer type.
-Null pointers
-^^^^^^^^^^^^^
+#### Null pointers
In principle, an implementation could derive the signed null pointer value
simply by applying the standard signing algorithm to the raw null pointer
value. However, for likely signing algorithms, this would mean that the signed
null pointer value would no longer be statically known, which would have many
-negative consequences. For one, it would become substantially more expensive
-to emit null pointer values or to perform null-pointer checks. For another,
+negative consequences. For one, it would become substantially more expensive
+to emit null pointer values or to perform null-pointer checks. For another,
the pervasive (even if technically unportable) assumption that null pointers
are bitwise zero would be invalidated, making it substantially more difficult
to adopt pointer authentication, as well as weakening common optimizations for
-zero-initialized memory such as the use of ``.bzz`` sections. Therefore it is
+zero-initialized memory such as the use of `.bzz` sections. Therefore it is
beneficial to treat null pointers specially by giving them their usual
-representation. On AArch64, this requires additional code when working with
+representation. On AArch64, this requires additional code when working with
possibly-null pointers, such as when copying a pointer field that has been
signed with address diversity.
@@ -367,416 +338,375 @@ there are some situations in which a null pointer may have important semantic
or security impact. For that purpose Clang has the concept of a pointer
authentication schema that signs and authenticates null values.
-Return addresses
-^^^^^^^^^^^^^^^^
+#### Return addresses
The current implementation in Clang implicitly signs the return addresses in
-function calls. While the value of the return address is technically an
+function calls. While the value of the return address is technically an
implementation detail of a function, there are some important libraries and
development tools which rely on manually walking the chain of stack frames.
These tools must be updated to correctly account for pointer authentication,
either by stripping signatures (if security is not important for the tool, e.g.
if it is capturing a stack trace during a crash) or properly authenticating
-them. More information about how these values are signed is available in the
-`Language ABI`_ section.
+them. More information about how these values are signed is available in the
+[Language ABI] section.
-C++ virtual functions
-^^^^^^^^^^^^^^^^^^^^^
+#### C++ virtual functions
The current implementation in Clang signs virtual function pointers with
a discriminator derived from the full signature of the overridden method,
-including the method name and parameter types. It is possible to write C++
+including the method name and parameter types. It is possible to write C++
code that relies on v-table layout remaining constant despite changes to
-a method signature; for example, a parameter might be a ``typedef`` that
-resolves to a different type based on a build setting. Such code violates
+a method signature; for example, a parameter might be a `typedef` that
+resolves to a different type based on a build setting. Such code violates
C++'s One Definition Rule (ODR), but that violation is not normally detected;
however, pointer authentication will detect it.
-Language extensions
-~~~~~~~~~~~~~~~~~~~
+### Language extensions
-Feature testing
-^^^^^^^^^^^^^^^
+#### Feature testing
Whether the current target uses pointer authentication can be tested for with
a number of different tests.
-- ``__PTRAUTH__`` macro is defined if ``<ptrauth.h>`` provides its normal
+- `__PTRAUTH__` macro is defined if `<ptrauth.h>` provides its normal
interface. This implies support for the pointer authentication intrinsics
- and the ``__ptrauth`` qualifier.
-
-- ``__has_feature(ptrauth_returns)`` is true if the target uses pointer
+ and the `__ptrauth` qualifier.
+- `__has_feature(ptrauth_returns)` is true if the target uses pointer
authentication to protect return addresses.
-
-- ``__has_feature(ptrauth_calls)`` is true if the target uses pointer
- authentication to protect indirect branches. On arm64e this implies
- ``__has_feature(ptrauth_returns)``, ``__has_feature(ptrauth_intrinsics)``,
- and the ``__PTRAUTH__`` macro.
-
-- For backwards compatibility purposes ``__has_feature(ptrauth_intrinsics)``
- and ``__has_feature(ptrauth_qualifier)`` are available on arm64e targets.
+- `__has_feature(ptrauth_calls)` is true if the target uses pointer
+ authentication to protect indirect branches. On arm64e this implies
+ `__has_feature(ptrauth_returns)`, `__has_feature(ptrauth_intrinsics)`,
+ and the `__PTRAUTH__` macro.
+- For backwards compatibility purposes `__has_feature(ptrauth_intrinsics)`
+ and `__has_feature(ptrauth_qualifier)` are available on arm64e targets.
These features are synonymous with each other, and are equivalent to testing
- for the ``__PTRAUTH__`` macro definition. Use of these features should be
+ for the `__PTRAUTH__` macro definition. Use of these features should be
restricted to cases where backwards compatibility is required, and should be
- paired with ``defined(__PTRAUTH__)``.
-
+ paired with `defined(__PTRAUTH__)`.
Clang provides several other tests only for historical purposes; for current
-purposes they are all equivalent to ``ptrauth_calls``.
+purposes they are all equivalent to `ptrauth_calls`.
-``__ptrauth`` qualifier
-^^^^^^^^^^^^^^^^^^^^^^^
+#### `__ptrauth` qualifier
-``__ptrauth(key, address, discriminator)`` is an extended type
+`__ptrauth(key, address, discriminator)` is an extended type
qualifier which causes so-qualified objects to hold pointers or pointer sized
integers signed using the specified schema rather than the default schema for
such types.
In the current implementation in Clang, the qualified type must be a C pointer
-type, either to a function or to an object, or a pointer sized integer. It
+type, either to a function or to an object, or a pointer sized integer. It
currently cannot be an Objective-C pointer type, a C++ reference type, or a
block pointer type; these restrictions may be lifted in the future.
The current implementation in Clang is known to not provide adequate safety
-guarantees against the creation of `signing oracles`_ when assigning data
-pointers to ``__ptrauth``-qualified gl-values. See the section on `safe
-derivation`_ for more information.
+guarantees against the creation of [signing oracles] when assigning data
+pointers to `__ptrauth`-qualified gl-values. See the section on [safe
+derivation][safe derivation] for more information.
The qualifier's operands are as follows:
-- ``key`` - an expression evaluating to a key value from ``<ptrauth.h>``; must
+- `key` - an expression evaluating to a key value from `<ptrauth.h>`; must
be a constant expression
-
-- ``address`` - whether to use address diversity (1) or not (0); must be
+- `address` - whether to use address diversity (1) or not (0); must be
a constant expression with one of these two values
+- `discriminator` - a constant discriminator; must be a constant expression
-- ``discriminator`` - a constant discriminator; must be a constant expression
-
-See `Discriminators`_ for more information about discriminators.
+See [Discriminators] for more information about discriminators.
Currently the operands must be constant-evaluable even within templates. In the
future this restriction may be lifted to allow value-dependent expressions as
long as they instantiate to a constant expression.
-Consistent with the ordinary C/C++ rule for parameters, top-level ``__ptrauth``
+Consistent with the ordinary C/C++ rule for parameters, top-level `__ptrauth`
qualifiers on a parameter (after parameter type adjustment) are ignored when
-deriving the type of the function. The parameter will be passed using the
+deriving the type of the function. The parameter will be passed using the
default ABI for the unqualified pointer type.
-If ``x`` is an object of type ``__ptrauth(key, address, discriminator) T``,
-then the signing schema of the value stored in ``x`` is a key of ``key`` and
+If `x` is an object of type `__ptrauth(key, address, discriminator) T`,
+then the signing schema of the value stored in `x` is a key of `key` and
a discriminator determined as follows:
-- if ``address`` is 0, then the discriminator is ``discriminator``;
+- if `address` is 0, then the discriminator is `discriminator`;
+- if `address` is 1 and `discriminator` is 0, then the discriminator is
+ `&x`; otherwise
+- if `address` is 1 and `discriminator` is non-zero, then the discriminator
+ is `ptrauth_blend_discriminator(&x, discriminator)`; see
+ [ptrauth_blend_discriminator].
-- if ``address`` is 1 and ``discriminator`` is 0, then the discriminator is
- ``&x``; otherwise
-
-- if ``address`` is 1 and ``discriminator`` is non-zero, then the discriminator
- is ``ptrauth_blend_discriminator(&x, discriminator)``; see
- `ptrauth_blend_discriminator`_.
-
-Non-triviality from address diversity
-+++++++++++++++++++++++++++++++++++++
+##### Non-triviality from address diversity
Address diversity must impose additional restrictions in order to allow the
-implementation to correctly copy values. In C++, a type qualified with address
+implementation to correctly copy values. In C++, a type qualified with address
diversity is treated like a class type with non-trivial copy/move constructors
and assignment operators, with the usual effect on containing classes and
-unions. C does not have a standard concept of non-triviality, and so we must
+unions. C does not have a standard concept of non-triviality, and so we must
describe the basic rules here, with the intention of imitating the emergent
rules of C++:
- A type may be **non-trivial to copy**.
-
- A type may also be **illegal to copy**. Types that are illegal to copy are
always non-trivial to copy.
-
- A type may also be **address-sensitive**. This includes types that use self
referencing pointers, data protected by address diversified pointer
authentication, or other similar concepts.
-
-- A type qualified with a ``ptrauth`` qualifier or implicit authentication
+- A type qualified with a `ptrauth` qualifier or implicit authentication
schema that requires address diversity is non-trivial to copy and
address-sensitive.
-
- An array type is illegal to copy, non-trivial to copy, or address-sensitive
if its element type is illegal to copy, non-trivial to copy, or
address-sensitive, respectively.
-
- A struct type is illegal to copy, non-trivial to copy, or address-sensitive
if it has a field whose type is illegal to copy, non-trivial to copy, or
address-sensitive, respectively.
-
- A union type is both illegal and non-trivial to copy if it has a field whose
type is non-trivial or illegal to copy.
-
- A union type is address-sensitive if it has a field whose type is
address-sensitive.
-
- A program is ill-formed if it uses a type that is illegal to copy as
a function parameter, argument, or return type.
-
- A program is ill-formed if an expression requires a type to be copied that is
illegal to copy.
-
- Otherwise, copying a type that is non-trivial to copy correctly copies its
subobjects.
-
- Types that are address-sensitive must always be passed and returned
indirectly. Thus, changing the address-sensitivity of a type may be
ABI-breaking even if its size and alignment do not change.
-``<ptrauth.h>``
-~~~~~~~~~~~~~~~
+### `<ptrauth.h>`
This header defines the following types and operations:
-``ptrauth_key``
-^^^^^^^^^^^^^^^
+#### `ptrauth_key`
-This ``enum`` is the type of abstract signing keys. In addition to defining
+This `enum` is the type of abstract signing keys. In addition to defining
the set of implementation-specific signing keys (for example, Armv8.3 defines
-``ptrauth_key_asia``), it also defines some portable aliases for those keys.
-For example, ``ptrauth_key_function_pointer`` is the key generally used for
+`ptrauth_key_asia`), it also defines some portable aliases for those keys.
+For example, `ptrauth_key_function_pointer` is the key generally used for
C function pointers, which will generally be suitable for other
function-signing schemas.
In all the operation descriptions below, key values must be constant values
corresponding to one of the implementation-specific abstract signing keys from
-this ``enum``.
+this `enum`.
-``ptrauth_extra_data_t``
-^^^^^^^^^^^^^^^^^^^^^^^^
+#### `ptrauth_extra_data_t`
-This is a ``typedef`` of a standard integer type of the correct size to hold
+This is a `typedef` of a standard integer type of the correct size to hold
a discriminator value.
In the signing and authentication operation descriptions below, discriminator
values must have either pointer type or integer type. If the discriminator is
-an integer, it will be coerced to ``ptrauth_extra_data_t``.
-
-``ptrauth_blend_discriminator``
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+an integer, it will be coerced to `ptrauth_extra_data_t`.
-.. code-block:: c
+#### `ptrauth_blend_discriminator`
- ptrauth_blend_discriminator(pointer, integer)
+```c
+ptrauth_blend_discriminator(pointer, integer)
+```
Produce a discriminator value which blends information from the given pointer
and the given integer.
Implementations may ignore some bits from each value, which is to say, the
blending algorithm may be chosen for speed and convenience over theoretical
-strength as a hash-combining algorithm. For example, arm64e simply overwrites
+strength as a hash-combining algorithm. For example, arm64e simply overwrites
the high 16 bits of the pointer with the low 16 bits of the integer, which can
be done in a single instruction with an immediate integer.
-``pointer`` must have pointer type, and ``integer`` must have integer type. The
-result has type ``ptrauth_extra_data_t``.
+`pointer` must have pointer type, and `integer` must have integer type. The
+result has type `ptrauth_extra_data_t`.
-``ptrauth_string_discriminator``
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+#### `ptrauth_string_discriminator`
-.. code-block:: c
-
- ptrauth_string_discriminator(string)
+```c
+ptrauth_string_discriminator(string)
+```
Compute a constant discriminator from the given string.
-``string`` must be a string literal of ``char`` character type. The result has
-type ``ptrauth_extra_data_t``.
+`string` must be a string literal of `char` character type. The result has
+type `ptrauth_extra_data_t`.
The result value is never zero and always within range for both the
-``__ptrauth`` qualifier and ``ptrauth_blend_discriminator``.
+`__ptrauth` qualifier and `ptrauth_blend_discriminator`.
This can be used in constant expressions.
-``ptrauth_type_discriminator``
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-.. code-block:: c
+#### `ptrauth_type_discriminator`
- ptrauth_type_discriminator(type)
+```c
+ptrauth_type_discriminator(type)
+```
Compute the constant discriminator derived from the given type, as is computed
for automatically type diversified schemas.
-``type`` must be a type. The result has the type ``ptrauth_extra_data_t``.
+`type` must be a type. The result has the type `ptrauth_extra_data_t`.
This can be used in constant expressions.
-``ptrauth_function_pointer_type_discriminator``
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-.. code-block:: c
+#### `ptrauth_function_pointer_type_discriminator`
- ptrauth_function_pointer_type_discriminator(function_type)
+```c
+ptrauth_function_pointer_type_discriminator(function_type)
+```
Compute the constant discriminator derived from the provided function type, for
use in contexts where the default function authentication schema. If function
pointer type diversity is enabled, this is equivalent to
`ptrauth_type_discriminator(function_type)`, if it is not enabled this is `0`.
-``function_type`` must be a function type. The result has the type ``ptrauth_extra_data_t``.
+`function_type` must be a function type. The result has the type `ptrauth_extra_data_t`.
This can be used in constant expressions.
-``ptrauth_strip``
-^^^^^^^^^^^^^^^^^
+#### `ptrauth_strip`
-.. code-block:: c
+```c
+ptrauth_strip(signedPointer, key)
+```
- ptrauth_strip(signedPointer, key)
-
-Given that ``signedPointer`` matches the layout for signed pointers signed with
-the given key, extract the raw pointer from it. This operation does not trap
+Given that `signedPointer` matches the layout for signed pointers signed with
+the given key, extract the raw pointer from it. This operation does not trap
and cannot fail, even if the pointer is not validly signed.
-``ptrauth_sign_constant``
-^^^^^^^^^^^^^^^^^^^^^^^^^
-
-.. code-block:: c
+#### `ptrauth_sign_constant`
- ptrauth_sign_constant(pointer, key, discriminator)
+```c
+ptrauth_sign_constant(pointer, key, discriminator)
+```
Return a signed pointer for a constant address in a manner which guarantees
a non-attackable sequence.
-``pointer`` must be a constant expression of pointer type which evaluates to
+`pointer` must be a constant expression of pointer type which evaluates to
a non-null pointer.
-``key`` must be a constant expression of type ``ptrauth_key``.
-``discriminator`` must be a constant expression of pointer or integer type;
-if an integer, it will be coerced to ``ptrauth_extra_data_t``.
-The result will have the same type as ``pointer``.
+`key` must be a constant expression of type `ptrauth_key`.
+`discriminator` must be a constant expression of pointer or integer type;
+if an integer, it will be coerced to `ptrauth_extra_data_t`.
+The result will have the same type as `pointer`.
This can be used in constant expressions.
-``ptrauth_sign_unauthenticated``
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-.. code-block:: c
+#### `ptrauth_sign_unauthenticated`
- ptrauth_sign_unauthenticated(pointer, key, discriminator)
+```c
+ptrauth_sign_unauthenticated(pointer, key, discriminator)
+```
Produce a signed pointer for the given raw pointer without applying any
-authentication or extra treatment. This operation is not required to have the
+authentication or extra treatment. This operation is not required to have the
same behavior on a null pointer that the language implementation would.
-This is a treacherous operation that can easily result in `signing oracles`_.
+This is a treacherous operation that can easily result in [signing oracles].
Programs should use it seldom and carefully.
-.. _ptrauth_auth_and_resign:
+(ptrauth-auth-and-resign)=
-``ptrauth_auth_and_resign``
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
+#### `ptrauth_auth_and_resign`
-.. code-block:: c
+```c
+ptrauth_auth_and_resign(pointer, oldKey, oldDiscriminator, newKey, newDiscriminator)
+```
- ptrauth_auth_and_resign(pointer, oldKey, oldDiscriminator, newKey, newDiscriminator)
+Authenticate that `pointer` is signed with `oldKey` and
+`oldDiscriminator` and then resign the raw-pointer result of that
+authentication with `newKey` and `newDiscriminator`.
-Authenticate that ``pointer`` is signed with ``oldKey`` and
-``oldDiscriminator`` and then resign the raw-pointer result of that
-authentication with ``newKey`` and ``newDiscriminator``.
-
-``pointer`` must have pointer type. The result will have the same type as
-``pointer``. This operation is not required to have the same behavior on
+`pointer` must have pointer type. The result will have the same type as
+`pointer`. This operation is not required to have the same behavior on
a null pointer that the language implementation would.
The code sequence produced for this operation must not be directly attackable.
However, if the discriminator values are not constant integers, their
-computations may still be attackable. In the future, Clang should be enhanced
+computations may still be attackable. In the future, Clang should be enhanced
to guarantee non-attackability if these expressions are
-:ref:`safely-derived<Safe derivation>`.
-
-``ptrauth_auth_with_pc_and_resign``
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+{ref}`safely-derived<Safe derivation>`.
-.. code-block:: c
+#### `ptrauth_auth_with_pc_and_resign`
- ptrauth_auth_with_pc_and_resign(pointer, oldKey, oldDiscriminator, oldPC, newKey, newDiscriminator)
+```c
+ptrauth_auth_with_pc_and_resign(pointer, oldKey, oldDiscriminator, oldPC, newKey, newDiscriminator)
+```
-Similar to :ref:`ptrauth_auth_and_resign`, but additionally requires that the
+Similar to {ref}`ptrauth_auth_and_resign`, but additionally requires that the
original signing schema includes the address of the signing instruction (i.e.
uses `paciasppc` / `pacibsppc` instead of `paciasp` / `pacibsp`). This
-authenticates ``pointer`` signed with ``oldKey`` and ``oldDiscriminator`` at
-``oldPC``, then resigns the raw-pointer result with ``newKey`` and
-``newDiscriminator``.
+authenticates `pointer` signed with `oldKey` and `oldDiscriminator` at
+`oldPC`, then resigns the raw-pointer result with `newKey` and
+`newDiscriminator`.
-Note: ``oldKey`` must be ``ptrauth_key_asia`` (IA) or ``ptrauth_key_asib`` (IB),
+Note: `oldKey` must be `ptrauth_key_asia` (IA) or `ptrauth_key_asib` (IB),
as only these keys support PC-based authentication instructions. Data keys
-(``ptrauth_key_asda`` / ``ptrauth_key_asdb``) are not supported.
+(`ptrauth_key_asda` / `ptrauth_key_asdb`) are not supported.
-``ptrauth_auth_function``
-^^^^^^^^^^^^^^^^^^^^^^^^^
+#### `ptrauth_auth_function`
-.. code-block:: c
+```c
+ptrauth_auth_function(pointer, key, discriminator)
+```
- ptrauth_auth_function(pointer, key, discriminator)
-
-Authenticate that ``pointer`` is signed with ``key`` and ``discriminator`` and
+Authenticate that `pointer` is signed with `key` and `discriminator` and
re-sign it to the standard schema for a function pointer of its type.
-``pointer`` must have function pointer type. The result will have the same
-type as ``pointer``. This operation is not required to have the same behavior
+`pointer` must have function pointer type. The result will have the same
+type as `pointer`. This operation is not required to have the same behavior
on a null pointer that the language implementation would.
This operation makes the same attackability guarantees as
-``ptrauth_auth_and_resign``.
+`ptrauth_auth_and_resign`.
If this operation appears syntactically as the function operand of a call,
Clang guarantees that the call will directly authenticate the function value
using the given schema rather than re-signing to the standard schema.
-``ptrauth_auth_data``
-^^^^^^^^^^^^^^^^^^^^^
-
-.. code-block:: c
+#### `ptrauth_auth_data`
- ptrauth_auth_data(pointer, key, discriminator)
+```c
+ptrauth_auth_data(pointer, key, discriminator)
+```
-Authenticate that ``pointer`` is signed with ``key`` and ``discriminator`` and
+Authenticate that `pointer` is signed with `key` and `discriminator` and
remove the signature.
-``pointer`` must have object pointer type. The result will have the same type
-as ``pointer``. This operation is not required to have the same behavior on
+`pointer` must have object pointer type. The result will have the same type
+as `pointer`. This operation is not required to have the same behavior on
a null pointer that the language implementation would.
In the future when Clang makes safe derivation guarantees, the result of
this operation should be considered safely-derived.
-``ptrauth_sign_generic_data``
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-.. code-block:: c
+#### `ptrauth_sign_generic_data`
- ptrauth_sign_generic_data(value1, value2)
+```c
+ptrauth_sign_generic_data(value1, value2)
+```
Computes a signature for the given pair of values, incorporating a secret
signing key.
This operation can be used to verify that arbitrary data has not been tampered
with by computing a signature for the data, storing that signature, and then
-repeating this process and verifying that it yields the same result. This can
+repeating this process and verifying that it yields the same result. This can
be reasonably done in any number of ways; for example, a library could compute
an ordinary checksum of the data and just sign the result in order to get the
tamper-resistance advantages of the secret signing key (since otherwise an
attacker could reliably overwrite both the data and the checksum).
-``value1`` and ``value2`` must be either pointers or integers. If the integers
-are larger than ``uintptr_t`` then data not representable in ``uintptr_t`` may
+`value1` and `value2` must be either pointers or integers. If the integers
+are larger than `uintptr_t` then data not representable in `uintptr_t` may
be discarded.
-The result will have type ``ptrauth_generic_signature_t``, which is an integer
-type. Implementations are not required to make all bits of the result equally
+The result will have type `ptrauth_generic_signature_t`, which is an integer
+type. Implementations are not required to make all bits of the result equally
significant; in particular, some implementations are known to not leave
meaningful data in the low bits.
-Standard ``__ptrauth`` qualifiers
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+#### Standard `__ptrauth` qualifiers
-``<ptrauth.h>`` additionally provides several macros which expand to
-``__ptrauth`` qualifiers for common ABI situations.
+`<ptrauth.h>` additionally provides several macros which expand to
+`__ptrauth` qualifiers for common ABI situations.
For convenience, these macros expand to nothing when pointer authentication is
disabled.
@@ -784,35 +714,32 @@ disabled.
These macros can be found in the header; some details of these macros may be
unstable or implementation-specific.
-
-Theory of operation
--------------------
+## Theory of operation
The threat model of pointer authentication is as follows:
- The attacker has the ability to read and write to a certain range of
- addresses, possibly the entire address space. However, they are constrained
+ addresses, possibly the entire address space. However, they are constrained
by the normal rules of the process: for example, they cannot write to memory
that is mapped read-only, and if they access unmapped memory it will trigger
a trap.
-
- The attacker has no ability to add arbitrary executable code to the program.
For example, the program does not include malicious code to begin with, and
the attacker cannot alter existing instructions, load a malicious shared
- library, or remap writable pages as executable. If the attacker wants to get
+ library, or remap writable pages as executable. If the attacker wants to get
the process to perform a specific sequence of actions, they must somehow
subvert the normal control flow of the process.
In both of the above paragraphs, it is merely assumed that the attacker's
*current* capabilities are restricted; that is, their current exploit does not
-directly give them the power to do these things. The attacker's immediate goal
+directly give them the power to do these things. The attacker's immediate goal
may well be to leverage their exploit to gain these capabilities, e.g. to load
a malicious dynamic library into the process, even though the process does not
directly contain code to do so.
Note that any bug that fits the above threat model can be immediately exploited
as a denial-of-service attack by simply performing an illegal access and
-crashing the program. Pointer authentication cannot protect against this.
+crashing the program. Pointer authentication cannot protect against this.
While denial-of-service attacks are unfortunate, they are also unquestionably
the best possible result of a bug this severe. Therefore, pointer authentication
enthusiastically embraces the idea of halting the program on a pointer
@@ -821,114 +748,110 @@ authentication failure rather than continuing in a possibly-compromised state.
Pointer authentication is a form of control-flow integrity (CFI) enforcement.
The basic security hypothesis behind CFI enforcement is that many bugs can only
be usefully exploited (other than as a denial-of-service) by leveraging them to
-subvert the control flow of the program. If this is true, then by inhibiting or
+subvert the control flow of the program. If this is true, then by inhibiting or
limiting that subversion, it may be possible to largely mitigate the security
consequences of those bugs by rendering them impractical (or, ideally,
impossible) to exploit.
-Every indirect branch in a program has a purpose. Using human intelligence, a
+Every indirect branch in a program has a purpose. Using human intelligence, a
programmer can describe where a particular branch *should* go according to this
-purpose: a ``return`` in ``printf`` should return to the call site, a particular
-call in ``qsort`` should call the comparator that was passed in as an argument,
-and so on. But for CFI to enforce that every branch in a program goes where it
+purpose: a `return` in `printf` should return to the call site, a particular
+call in `qsort` should call the comparator that was passed in as an argument,
+and so on. But for CFI to enforce that every branch in a program goes where it
*should* in this sense would require CFI to perfectly enforce every semantic
rule of the program's abstract machine; that is, it would require making the
-programming environment perfectly sound. That is out of scope. Instead, the
+programming environment perfectly sound. That is out of scope. Instead, the
goal of CFI is merely to catch attempts to make a branch go somewhere that its
obviously *shouldn't* for its purpose: for example, to stop a call from
-branching into the middle of a function rather than its beginning. As the
+branching into the middle of a function rather than its beginning. As the
information available to CFI gets better about the purpose of the branch, CFI
can enforce tighter and tighter restrictions on where the branch is permitted to
-go. Still, ultimately CFI cannot make the program sound. This may help explain
+go. Still, ultimately CFI cannot make the program sound. This may help explain
why pointer authentication makes some of the choices it does: for example, to
sign and authenticate mostly code pointers rather than every pointer in the
-program. Preventing attackers from redirecting branches is both particularly
-important and particularly approachable as a goal. Detecting corruption more
+program. Preventing attackers from redirecting branches is both particularly
+important and particularly approachable as a goal. Detecting corruption more
broadly is infeasible with these techniques, and the attempt would have far
higher cost.
-Attacks on pointer authentication
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+### Attacks on pointer authentication
-Pointer authentication works as follows. Every indirect branch in a program has
-a purpose. For every purpose, the implementation chooses a
-:ref:`signing schema<Signing schemas>`. At some place where a pointer is known
+Pointer authentication works as follows. Every indirect branch in a program has
+a purpose. For every purpose, the implementation chooses a
+{ref}`signing schema<Signing schemas>`. At some place where a pointer is known
to be correct for its purpose, it is signed according to the purpose's schema.
At every place where the pointer is needed for its purpose, it is authenticated
-according to the purpose's schema. If that authentication fails, the program is
+according to the purpose's schema. If that authentication fails, the program is
halted.
There are a variety of ways to attack this.
-Attacks of interest to programmers
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+#### Attacks of interest to programmers
These attacks arise from weaknesses in the default protections offered by
-pointer authentication. They can be addressed by using attributes or intrinsics
+pointer authentication. They can be addressed by using attributes or intrinsics
to opt in to stronger protection.
-Substitution attacks
-++++++++++++++++++++
+##### Substitution attacks
An attacker can simply overwrite a pointer intended for one purpose with a
pointer intended for another purpose if both purposes use the same signing
schema and that schema does not use address diversity.
The most common source of this weakness is when code relies on using the default
-language rules for C function pointers. The current implementation uses the
+language rules for C function pointers. The current implementation uses the
exact same signing schema for all C function pointers, even for functions of
-substantially different type. While efforts are ongoing to improve constant
+substantially different type. While efforts are ongoing to improve constant
diversity for C function pointers of different type, there are necessary limits
-to this. The C standard requires function pointers to be copyable with
-``memcpy``, which means that function pointers can never use address diversity.
+to this. The C standard requires function pointers to be copyable with
+`memcpy`, which means that function pointers can never use address diversity.
Furthermore, even if a function pointer can only be replaced with another
function of the exact same type, that can still be useful to an attacker, as in
the following example of a hand-rolled "v-table":
-.. code-block:: c
-
- struct ObjectOperations {
- void (*retain)(Object *);
- void (*release)(Object *);
- void (*deallocate)(Object *);
- void (*logStatus)(Object *);
- };
+```c
+struct ObjectOperations {
+ void (*retain)(Object *);
+ void (*release)(Object *);
+ void (*deallocate)(Object *);
+ void (*logStatus)(Object *);
+};
+```
The weakness in this design is that by lacking any context specific
discriminator, this means an attacker can substitute any of these fields with
any other function pointer signed with the default schema. Similarly the lack of
address diversity allows an attacker to replace the functions in one type's
"v-table" with those of another. This can be mitigated by overriding the default
-authentication schema with a more specific signing schema for each purpose. For
-instance, in this example, the ``__ptrauth`` qualifier can be used with a
-different constant discriminator for each field. Since there's no particular
-reason it's important for this v-table to be copyable with ``memcpy``, the
+authentication schema with a more specific signing schema for each purpose. For
+instance, in this example, the `__ptrauth` qualifier can be used with a
+different constant discriminator for each field. Since there's no particular
+reason it's important for this v-table to be copyable with `memcpy`, the
functions can also be signed with address diversity:
-.. code-block:: c
-
- #if defined(__PTRAUTH__)
- #define objectOperation(discriminator) \
- __ptrauth(ptrauth_key_function_pointer, 1, discriminator)
- #else
- #define objectOperation(discriminator)
- #endif
-
- struct ObjectOperations {
- void (*objectOperation(0xf017) retain)(Object *);
- void (*objectOperation(0x2639) release)(Object *);
- void (*objectOperation(0x8bb0) deallocate)(Object *);
- void (*objectOperation(0xc5d4) logStatus)(Object *);
- };
+```c
+#if defined(__PTRAUTH__)
+#define objectOperation(discriminator) \
+ __ptrauth(ptrauth_key_function_pointer, 1, discriminator)
+#else
+#define objectOperation(discriminator)
+#endif
+
+struct ObjectOperations {
+ void (*objectOperation(0xf017) retain)(Object *);
+ void (*objectOperation(0x2639) release)(Object *);
+ void (*objectOperation(0x8bb0) deallocate)(Object *);
+ void (*objectOperation(0xc5d4) logStatus)(Object *);
+};
+```
This weakness can also sometimes be mitigated by simply keeping the signed
pointer in constant memory, but this is less effective than using better signing
diversity.
-.. _Access path attacks:
+(access-path-attacks)=
-Access path attacks
-+++++++++++++++++++
+##### Access path attacks
If a signed pointer is often accessed indirectly (that is, by first loading the
address of the object where the signed pointer is stored), an attacker can
@@ -948,7 +871,7 @@ means that each pointer is signed with its own storage address,
which (by design) is invariant to changes in the accessing pointer.
Using sufficiently diverse signing schemas within the v-table can provide
-reasonably strong mitigation against this weakness. Always use address and type
+reasonably strong mitigation against this weakness. Always use address and type
diversity in v-tables to prevent attackers from assembling their own v-table.
Avoid re-using constant discriminators to prevent attackers from replacing a
v-table pointer with a pointer to totally unrelated memory that just happens to
@@ -958,46 +881,44 @@ type.
Further mitigation can be attained by signing pointers to v-tables. Any
signature at all should prevent attackers from forging v-table pointers; they
will need to somehow harvest an existing signed pointer from elsewhere in
-memory. Using a meaningful constant discriminator will force this to be
+memory. Using a meaningful constant discriminator will force this to be
harvested from an object with similar structure (e.g. a different implementation
-of the same interface). Using address diversity will prevent such harvesting
-entirely. However, care must be taken when sourcing the v-table pointer
+of the same interface). Using address diversity will prevent such harvesting
+entirely. However, care must be taken when sourcing the v-table pointer
originally; do not blindly sign a pointer that is not
-:ref:`safely derived<Safe derivation>`.
+{ref}`safely derived<Safe derivation>`.
-.. _Signing oracles:
+(signing-oracles)=
-Signing oracles
-+++++++++++++++
+##### Signing oracles
A signing oracle is a bit of code which can be exploited by an attacker to sign
-an arbitrary pointer in a way that can later be recovered. Such oracles can be
+an arbitrary pointer in a way that can later be recovered. Such oracles can be
used by attackers to forge signatures matching the oracle's signing schema,
which is likely to cause a total compromise of pointer authentication's
effectiveness.
This attack only affects ordinary programmers if they are using certain
-treacherous patterns of code. Currently this includes:
+treacherous patterns of code. Currently this includes:
-- all uses of the ``__ptrauth_sign_unauthenticated`` intrinsic and
-- assigning values to ``__ptrauth``-qualified l-values.
+- all uses of the `__ptrauth_sign_unauthenticated` intrinsic and
+- assigning values to `__ptrauth`-qualified l-values.
Care must be taken in these situations to ensure that the pointer being signed
-has been :ref:`safely derived<Safe derivation>` or is otherwise not possible to
-attack. (In some cases, this may be challenging without compiler support.)
+has been {ref}`safely derived<Safe derivation>` or is otherwise not possible to
+attack. (In some cases, this may be challenging without compiler support.)
A diagnostic will be added in the future for implicitly dangerous patterns of
code, such as assigning a non-safely-derived values to a
-``__ptrauth``-qualified l-value.
+`__ptrauth`-qualified l-value.
-.. _Authentication oracles:
+(authentication-oracles)=
-Authentication oracles
-++++++++++++++++++++++
+##### Authentication oracles
An authentication oracle is a bit of code which can be exploited by an attacker
to leak whether a signed pointer is validly signed without halting the program
-if it isn't. Such oracles can be used to forge signatures matching the oracle's
+if it isn't. Such oracles can be used to forge signatures matching the oracle's
signing schema if the attacker can repeatedly invoke the oracle for different
candidate signed pointers. This is likely to cause a total compromise of pointer
authentication's effectiveness.
@@ -1010,111 +931,107 @@ immediately trap on authentication failure.
The likelihood of creating an authentication oracle is why there is currently no
intrinsic which queries whether a signed pointer is validly signed.
-
-Attacks of interest to implementors
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+#### Attacks of interest to implementors
These attacks are not inherent to the model; they arise from mistakes in either
implementing or using the `sign` and `auth` operations. Avoiding these mistakes
requires careful work throughout the system.
-Failure to trap on authentication failure
-+++++++++++++++++++++++++++++++++++++++++
+##### Failure to trap on authentication failure
Any failure to halt the program on an authentication failure is likely to be
exploitable by attackers to create an
-:ref:`authentication oracle<Authentication oracles>`.
+{ref}`authentication oracle<Authentication oracles>`.
There are several different ways to introduce this problem:
- The implementation might try to halt the program in some way that can be
intercepted.
- For example, the Armv8.3 ``aut`` instructions do not directly trap on
- authentication failure on processors that lack the ``FPAC`` extension.
+ For example, the Armv8.3 `aut` instructions do not directly trap on
+ authentication failure on processors that lack the `FPAC` extension.
Instead, they corrupt their results to be invalid pointers, with the idea that
subsequent uses of those pointers will trigger traps as bad memory accesses.
However, most kernels do not immediately halt programs that trap due to bad
memory accesses; instead, they notify the process to give it an opportunity to
- recover. If this happens with an ``auth`` failure, the attacker may be able to
+ recover. If this happens with an `auth` failure, the attacker may be able to
exploit the recovery path in a way that creates an oracle. Kernels must
provide a way for a process to trap unrecoverably, and this should cover all
- ``FPAC`` traps. Compilers must ensure that ``auth`` failures trigger an
- unrecoverable trap, ideally by taking advantage of ``FPAC``, but if necessary
+ `FPAC` traps. Compilers must ensure that `auth` failures trigger an
+ unrecoverable trap, ideally by taking advantage of `FPAC`, but if necessary
by emitting extra instructions.
-- A compiler might use an intermediate representation (IR) for ``sign`` and
- ``auth`` operations that cannot make adequate correctness guarantees.
+- A compiler might use an intermediate representation (IR) for `sign` and
+ `auth` operations that cannot make adequate correctness guarantees.
- For example, suppose that an IR uses ARMv8.3-like semantics for ``auth``: the
+ For example, suppose that an IR uses ARMv8.3-like semantics for `auth`: the
operation merely corrupts its result on failure instead of promising to trap.
- A frontend might emit patterns of IR that always follow an ``auth`` with a
+ A frontend might emit patterns of IR that always follow an `auth` with a
memory access, thinking that this ensures correctness. But if the IR can be
- transformed to insert code between the ``auth`` and the access, or if the
- ``auth`` can be speculated, then this potentially creates an oracle. It is
- better for ``auth`` to semantically guarantee to trap, potentially requiring
+ transformed to insert code between the `auth` and the access, or if the
+ `auth` can be speculated, then this potentially creates an oracle. It is
+ better for `auth` to semantically guarantee to trap, potentially requiring
an explicit check in the generated code. An ARMv8.3-like target can avoid this
- explicit check in the common case by recognizing the pattern of an ``auth``
+ explicit check in the common case by recognizing the pattern of an `auth`
followed immediately by an access.
-Attackable code sequences
-+++++++++++++++++++++++++
+##### Attackable code sequences
If code that is part of a pointer authentication operation is interleaved with
code that may itself be vulnerable to attacks, an attacker may be able to use
-this to create a :ref:`signing<Signing oracles>` or
-:ref:`authentication<Authentication oracles>` oracle.
+this to create a {ref}`signing<Signing oracles>` or
+{ref}`authentication<Authentication oracles>` oracle.
For example, suppose that the compiler is generating a call to a function and
passing two arguments: a signed constant pointer and a value derived from a
-call. In ARMv8.3, this code might look like so:
-
-.. code-block:: asm
-
- adr x19, _callback. ; compute &_callback
- paciza x19 ; sign it with a constant discriminator of 0
- blr _argGenerator ; call _argGenerator() (returns in x0)
- mov x1, x0 ; move call result to second arg register
- mov x0, x19 ; move signed &_callback to first arg register
- blr _function ; call _function
-
-This code is correct, as would be a sequencing that does *both* the ``adr`` and
-the ``paciza`` after the call to ``_argGenerator``. But a sequence that
-computes the address of ``_callback`` but leaves it as a raw pointer in a
-register during the call to ``_argGenerator`` would be vulnerable:
-
-.. code-block:: asm
-
- adr x19, _callback. ; compute &_callback
- blr _argGenerator ; call _argGenerator() (returns in x0)
- mov x1, x0 ; move call result to second arg register
- paciza x19 ; sign &_callback
- mov x0, x19 ; move signed &_callback to first arg register
- blr _function ; call _function
-
-If ``_argGenerator`` spills ``x19`` (a callee-save register), and if the
+call. In ARMv8.3, this code might look like so:
+
+```asm
+adr x19, _callback. ; compute &_callback
+paciza x19 ; sign it with a constant discriminator of 0
+blr _argGenerator ; call _argGenerator() (returns in x0)
+mov x1, x0 ; move call result to second arg register
+mov x0, x19 ; move signed &_callback to first arg register
+blr _function ; call _function
+```
+
+This code is correct, as would be a sequencing that does *both* the `adr` and
+the `paciza` after the call to `_argGenerator`. But a sequence that
+computes the address of `_callback` but leaves it as a raw pointer in a
+register during the call to `_argGenerator` would be vulnerable:
+
+```asm
+adr x19, _callback. ; compute &_callback
+blr _argGenerator ; call _argGenerator() (returns in x0)
+mov x1, x0 ; move call result to second arg register
+paciza x19 ; sign &_callback
+mov x0, x19 ; move signed &_callback to first arg register
+blr _function ; call _function
+```
+
+If `_argGenerator` spills `x19` (a callee-save register), and if the
attacker can perform a write during this call, then the attacker can overwrite
the spill slot with an arbitrary pointer that will eventually be unconditionally
-signed after the function returns. This would be a signing oracle.
+signed after the function returns. This would be a signing oracle.
The implementation can avoid this by obeying two basic rules:
- The compiler's intermediate representations (IR) should not provide operations
- that expose intermediate raw pointers. This may require providing extra
+ that expose intermediate raw pointers. This may require providing extra
operations that perform useful combinations of operations.
For example, there should be an "atomic" auth-and-resign operation that should
- be used instead of emitting an ``auth`` operation whose result is fed into a
- ``sign``.
+ be used instead of emitting an `auth` operation whose result is fed into a
+ `sign`.
Similarly, if a pointer should be authenticated as part of doing a memory
access or a call, then the access or call should be decorated with enough
information to perform the authentication; there should not be a separate
- ``auth`` whose result is used as the pointer operand for the access or call.
+ `auth` whose result is used as the pointer operand for the access or call.
(In LLVM IR, we do this for calls, but not yet for loads or stores.)
"Operations" includes things like materializing a signed value to a known
- function or global variable. The compiler must be able to recognize and emit
+ function or global variable. The compiler must be able to recognize and emit
this as a unified operation, rather than potentially splitting it up as in
the example above.
@@ -1122,21 +1039,20 @@ The implementation can avoid this by obeying two basic rules:
instructions that are part of a pointer authentication operation. This may
require custom code-generation of these operations in some cases.
-Register clobbering
-+++++++++++++++++++
+##### Register clobbering
-As a refinement of the section on `Attackable code sequences`_, if the attacker
+As a refinement of the section on [Attackable code sequences], if the attacker
has the ability to modify arbitrary *register* state at arbitrary points in the
program, then special care must be taken.
For example, ARMv8.3 might materialize a signed function pointer like so:
-.. code-block:: asm
+```asm
+adr x0, _callback. ; compute &_callback
+paciza x0 ; sign it with a constant discriminator of 0
+```
- adr x0, _callback. ; compute &_callback
- paciza x0 ; sign it with a constant discriminator of 0
-
-If an attacker has the ability to overwrite ``x0`` between these two
+If an attacker has the ability to overwrite `x0` between these two
instructions, this code sequence is vulnerable to becoming a signing oracle.
For the most part, this sort of attack is not possible: it is a basic element of
@@ -1145,36 +1061,35 @@ However, in systems that support asynchronous interrupts, this property requires
the cooperation of the interrupt-handling code. If that code saves register
state to memory, and that memory can be overwritten by an attacker, then
essentially the attack can overwrite arbitrary register state at an arbitrary
-point. This could be a concern if the threat model includes attacks on the
+point. This could be a concern if the threat model includes attacks on the
kernel or if the program uses user-space preemptive multitasking.
(Readers might object that an attacker cannot rely on asynchronous interrupts
-triggering at an exact instruction boundary. In fact, researchers have had some
-success in doing exactly that. Even ignoring that, though, we should aim to
+triggering at an exact instruction boundary. In fact, researchers have had some
+success in doing exactly that. Even ignoring that, though, we should aim to
protect against lucky attackers just as much as good ones.)
To protect against this, saved register state must be at least partially signed
-(using something like `ptrauth_sign_generic_data`_). This is required for
+(using something like [ptrauth_sign_generic_data]). This is required for
correctness anyway because saved thread states include security-critical
-registers such as SP, FP, PC, and LR (where applicable). Ideally, this
+registers such as SP, FP, PC, and LR (where applicable). Ideally, this
signature would cover all the registers, but since saving and restoring
registers can be very performance-sensitive, that may not be acceptable. It is
sufficient to set aside a small number of scratch registers that will be
guaranteed to be preserved correctly; the compiler can then be careful to only
store critical values like intermediate raw pointers in those registers.
-``setjmp`` and ``longjmp`` should sign and authenticate the core registers (SP,
+`setjmp` and `longjmp` should sign and authenticate the core registers (SP,
FP, PC, and LR), but they do not need to worry about intermediate values because
-``setjmp`` can only be called synchronously, and the compiler should never
+`setjmp` can only be called synchronously, and the compiler should never
schedule pointer-authentication operations interleaved with arbitrary calls.
-.. _Relative addresses:
+(relative-addresses)=
-Attacks on relative addressing
-++++++++++++++++++++++++++++++
+##### Attacks on relative addressing
Relative addressing is a technique used to compress and reduce the load-time
-cost of infrequently-used global data. The pointer authentication system is
+cost of infrequently-used global data. The pointer authentication system is
unlikely to support signing or authenticating a relative address, and in most
cases it would defeat the point to do so: it would take additional storage
space, and applying the signature would take extra work at load time.
@@ -1182,18 +1097,16 @@ space, and applying the signature would take extra work at load time.
Relative addressing is not precluded by the use of pointer authentication, but
it does take extra considerations to make it secure:
-- Relative addresses must only be stored in read-only memory. A writable
+- Relative addresses must only be stored in read-only memory. A writable
relative address can be overwritten to point nearly anywhere, making it
inherently insecure; this danger can only be compensated for with techniques
- for protecting arbitrary data like `ptrauth_sign_generic_data`_.
-
+ for protecting arbitrary data like [ptrauth_sign_generic_data].
- Relative addresses must only be accessed through signed pointers with adequate
- diversity. If an attacker can perform an `access path attack` to replace the
+ diversity. If an attacker can perform an `access path attack` to replace the
pointer through which the relative address is accessed, they can easily cause
the relative address to point wherever they want.
-Signature forging
-+++++++++++++++++
+##### Signature forging
If an attacker can exactly reproduce the behavior of the signing algorithm, and
they know all the correct inputs to it, then they can perfectly forge a
@@ -1204,64 +1117,56 @@ There are three components to avoiding this mistake:
- The abstract signing algorithm should be good: it should not have glaring
flaws which would allow attackers to predict its result with better than
random accuracy without knowing all the inputs (like the key values).
-
-- The key values should be kept secret. If at all possible, they should never
+- The key values should be kept secret. If at all possible, they should never
be stored in accessible memory, or perhaps only stored encrypted.
-
- Contexts that are meant to be independently protected should use different
- key values. For example, the kernel should not use the same keys as user
- processes. Different user processes should also use different keys from each
+ key values. For example, the kernel should not use the same keys as user
+ processes. Different user processes should also use different keys from each
other as much as possible, although this may pose its own technical
challenges.
-Remapping
-+++++++++
+##### Remapping
If an attacker can change the memory protections on certain pages of the
program's memory, that can substantially weaken the protections afforded by
pointer authentication.
- If an attacker can inject their own executable code, they can also certainly
- inject code that can be used as a :ref:`signing oracle<Signing Oracles>`.
+ inject code that can be used as a {ref}`signing oracle<Signing Oracles>`.
The same is true if they can write to the instruction stream.
-
- If an attacker can remap read-only program data sections to be writable, then
- any use of :ref:`relative addresses` in global data becomes insecure.
-
+ any use of {ref}`relative addresses` in global data becomes insecure.
- On platforms that use them, if an attacker can remap the memory containing
- the `global offset tables`_ as writable, then any unsigned pointers in those
+ the [global offset tables] as writable, then any unsigned pointers in those
tables are insecure.
Remapping memory in this way often requires the attacker to have already
-substantively subverted the control flow of the process. Nonetheless, if the
+substantively subverted the control flow of the process. Nonetheless, if the
operating system has a mechanism for mapping pages in a way that cannot be
remapped, this should be used wherever possible.
-.. _Safe Derivation:
+(safe-derivation)=
-Safe derivation
-~~~~~~~~~~~~~~~
+### Safe derivation
Whether a data pointer is stored, even briefly, as a raw pointer can affect the
-security-correctness of a program. (Function pointers are never implicitly
+security-correctness of a program. (Function pointers are never implicitly
stored as raw pointers; raw pointers to functions can only be produced with the
-``<ptrauth.h>`` intrinsics.) Repeated re-signing can also impact performance.
+`<ptrauth.h>` intrinsics.) Repeated re-signing can also impact performance.
Clang makes a modest set of guarantees in this area:
- An expression of pointer type is said to be **safely derived** if:
- it takes the address of a global variable or function, or
-
- - it is a load from a gl-value of ``__ptrauth``-qualified type, or
-
+ - it is a load from a gl-value of `__ptrauth`-qualified type, or
- it is a load from read-only memory that has been initialized from a safely
derived source, such as the `data const` section of a binary or library.
-- If a value that is safely derived is assigned to a ``__ptrauth``-qualified
+- If a value that is safely derived is assigned to a `__ptrauth`-qualified
object, including by initialization, then the value will be directly signed as
appropriate for the target qualifier and will not be stored as a raw pointer.
-- If the function expression of a call is a gl-value of ``__ptrauth``-qualified
+- If the function expression of a call is a gl-value of `__ptrauth`-qualified
type, then the call will be authenticated directly according to the source
qualifier and will not be resigned to the default rule for a function pointer
of its type.
@@ -1272,58 +1177,48 @@ particular, Clang should be enhanced to make the following guarantees:
- A pointer should additionally be considered safely derived if it is:
- the address of a gl-value that is safely derived,
-
- the result of pointer arithmetic on a pointer that is safely derived (with
some restrictions on the integer operand),
-
- the result of a comma operator where the second operand is safely derived,
-
- the result of a conditional operator where the selected operand is safely
derived, or
-
- the result of loading from a safely derived gl-value.
- A gl-value should be considered safely derived if it is:
- a dereference of a safely derived pointer,
-
- a member access into a safely derived gl-value, or
-
- a reference to a variable.
- An access to a safely derived gl-value should be guaranteed to not allow
replacement of any of the safely-derived component values at any point in the
- access. "Access" should include loading a function pointer.
+ access. "Access" should include loading a function pointer.
-- Assignments should include pointer-arithmetic operators like ``+=``.
+- Assignments should include pointer-arithmetic operators like `+=`.
Making these guarantees will require further work, including significant new
support in LLVM IR.
Furthermore, Clang should implement a warning when assigning a data pointer that
-is not safely derived to a ``__ptrauth``-qualified gl-value.
+is not safely derived to a `__ptrauth`-qualified gl-value.
-
-Language ABI
-------------
+## Language ABI
This section describes the pointer-authentication ABI currently implemented in
-Clang for the Apple arm64e target. As other targets adopt pointer
+Clang for the Apple arm64e target. As other targets adopt pointer
authentication, this section should be generalized to express their ABIs as
well.
-Key assignments
-~~~~~~~~~~~~~~~
+### Key assignments
-ARMv8.3 provides four abstract signing keys: ``IA``, ``IB``, ``DA``, and ``DB``.
-The architecture designates ``IA`` and ``IB`` for signing code pointers and
-``DA`` and ``DB`` for signing data pointers; this is reinforced by two
+ARMv8.3 provides four abstract signing keys: `IA`, `IB`, `DA`, and `DB`.
+The architecture designates `IA` and `IB` for signing code pointers and
+`DA` and `DB` for signing data pointers; this is reinforced by two
properties:
- The ISA provides instructions that perform combined auth+call and auth+load
- operations; these instructions can only use the ``I`` keys and ``D`` keys,
+ operations; these instructions can only use the `I` keys and `D` keys,
respectively.
-
- AArch64's TBI feature can be separately enabled for code pointers (controlling
whether indirect-branch instructions ignore those bits) and data pointers
(controlling whether memory-access instructions) ignore those bits. If TBI is
@@ -1333,149 +1228,140 @@ properties:
arm64e then further subdivides the keys as follows:
-- The ``A`` keys are used for primarily "global" purposes like signing v-tables
- and function pointers. These keys are sometimes called *process-independent*
+- The `A` keys are used for primarily "global" purposes like signing v-tables
+ and function pointers. These keys are sometimes called *process-independent*
or *cross-process* because on existing OSes they are not changed when changing
processes, although this is not a platform guarantee.
-
-- The ``B`` keys are used for primarily "local" purposes like signing return
- addresses. These keys are sometimes called *process-specific* because they
+- The `B` keys are used for primarily "local" purposes like signing return
+ addresses. These keys are sometimes called *process-specific* because they
are typically different between processes. However, they are in fact shared
- across processes in one situation: systems which provide ``fork`` cannot
+ across processes in one situation: systems which provide `fork` cannot
change these keys in the child process; they can only be changed during
- ``exec``.
+ `exec`.
-Implementation-defined algorithms and quantities
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+### Implementation-defined algorithms and quantities
The cryptographic hash algorithm used to compute signatures in ARMv8.3 is a
private detail of the hardware implementation.
-arm64e restricts constant discriminators (used in ``__ptrauth`` and
-``ptrauth_blend_discriminator``) to the range from 0 to 65535, inclusive. A 0
+arm64e restricts constant discriminators (used in `__ptrauth` and
+`ptrauth_blend_discriminator`) to the range from 0 to 65535, inclusive. A 0
discriminator generally signifies that no blending is required; see the
-documentation for ``ptrauth_blend_discriminator``. This range is somewhat
+documentation for `ptrauth_blend_discriminator`. This range is somewhat
narrow but has two advantages:
- The AArch64 ISA allows an arbitrary 16-bit immediate to be written over the
top 16 bits of a register in a single instruction:
- .. code-block:: asm
-
- movk xN, #0x4849, LSL 48
+ ```asm
+ movk xN, #0x4849, LSL 48
+ ```
This is ideal for the discriminator blending operation because it adds minimal
code-size overhead and avoids overwriting any interesting bits from the
- pointer. Blending in a wider constant discriminator would either clobber
- interesting bits (e.g. if it was loaded with ``movk xN, #0x4c4f, LSL 32``) or
+ pointer. Blending in a wider constant discriminator would either clobber
+ interesting bits (e.g. if it was loaded with `movk xN, #0x4c4f, LSL 32`) or
require significantly more code (e.g. if the discriminator was loaded with a
- ``mov+bfi`` sequence).
+ `mov+bfi` sequence).
- It is possible to pack a 16-bit discriminator into loader metadata with
minimal compromises, whereas a wider discriminator would require extra
metadata storage and therefore significantly impact load times.
-The string hash used by ``ptrauth_string_discriminator`` is a 64-bit SipHash-2-4
-using the constant seed ``b5d4c9eb79104a796fec8b1b428781d4`` (big-endian), with
+The string hash used by `ptrauth_string_discriminator` is a 64-bit SipHash-2-4
+using the constant seed `b5d4c9eb79104a796fec8b1b428781d4` (big-endian), with
the result reduced by modulo to the range of non-zero discriminators (i.e.
-``(rawHash % 65535) + 1``).
+`(rawHash % 65535) + 1`).
-Return addresses
-~~~~~~~~~~~~~~~~
+### Return addresses
The kernel must ensure that attackers cannot replace LR due to an asynchronous
-exception; see `Register clobbering`_. If this is done by generally protecting
+exception; see [Register clobbering]. If this is done by generally protecting
LR, then functions which don't spill LR to the stack can avoid signing it
-entirely. Otherwise, the return address must be signed; on arm64e it is signed
-with the ``IB`` key using the stack pointer on entry as the discriminator.
+entirely. Otherwise, the return address must be signed; on arm64e it is signed
+with the `IB` key using the stack pointer on entry as the discriminator.
-Protecting return addresses is of such particular importance that the ``IB`` key
+Protecting return addresses is of such particular importance that the `IB` key
is almost entirely reserved for this purpose.
-Global offset tables
-~~~~~~~~~~~~~~~~~~~~
+### Global offset tables
The global offset table (GOT) is not part of the language ABI, but it is a
common implementation technique for dynamic linking which deserves special
discussion here.
Whenever possible, signed pointers should be materialized directly in code
-rather than via the GOT, e.g. using an ``adrp+add+pac`` sequence on ARMv8.3.
+rather than via the GOT, e.g. using an `adrp+add+pac` sequence on ARMv8.3.
This decreases the amount of work necessary at load time to initialize the GOT,
but more importantly, it defines away the potential for several attacks:
- Attackers cannot change instructions, so there is no way to cause this code
sequence to materialize a different pointer, whereas an access via the GOT
always has *at minimum* a probabilistic chance to be the target of successful
- `substitution attacks`_.
-
+ [substitution attacks].
- The GOT is a dense pool of fixed pointers at a fixed offset relative to code;
attackers can search this pool for useful pointers that can be used in
- `substitution attacks`_, whereas pointers that are only materialized directly
+ [substitution attacks], whereas pointers that are only materialized directly
are not so easily available.
-
-- Similarly, attackers can use `access path attacks`_ to replace a pointer to a
+- Similarly, attackers can use [access path attacks] to replace a pointer to a
signed pointer with a pointer to the GOT if the signing schema used within the
- GOT happens to be the same as the original pointer. This kind of collision
+ GOT happens to be the same as the original pointer. This kind of collision
becomes much less likely to be useful the fewer pointers are in the GOT in the
first place.
If this can be done for a symbol, then the compiler need only ensure that it
materializes the signed pointer using registers that are safe against
-`register clobbering`_.
+[register clobbering].
However, many symbols can only be accessed via the GOT, e.g. because they
-resolve to definitions outside of the current image. In this case, care must
+resolve to definitions outside of the current image. In this case, care must
be taken to ensure that using the GOT does not introduce weaknesses.
- If the entire GOT can be mapped read-only after loading, then no signing is
- required within the GOT. In fact, not signing pointers in the GOT is
+ required within the GOT. In fact, not signing pointers in the GOT is
preferable in this case because it makes the GOT useless for the harvesting
- and access-path attacks above. Storing raw pointers in this way is usually
+ and access-path attacks above. Storing raw pointers in this way is usually
extremely unsafe, but for the special case of an immutable GOT entry it's fine
because the GOT is always accessed via an address that is directly
- materialized in code and thus provably unattackable. (But see `Remapping`_.)
-
+ materialized in code and thus provably unattackable. (But see [Remapping].)
- Otherwise, GOT entries which are used for producing a signed pointer constant
- must be signed. The signing schema used in the GOT need not match the target
- signing schema for the signed constant. To counteract the threats of
+ must be signed. The signing schema used in the GOT need not match the target
+ signing schema for the signed constant. To counteract the threats of
substitution attacks, it's best if GOT entries can be signed with address
- diversity. Using a good constant discriminator as well (perhaps derived from
+ diversity. Using a good constant discriminator as well (perhaps derived from
the symbol name) can make it less useful to use a pointer to the GOT as the
- replacement in an :ref:`access path attack<Access path attacks>`.
+ replacement in an {ref}`access path attack<Access path attacks>`.
In either case, the compiler must ensure that materializing the address of a GOT
entry as part of producing a signed pointer constant is not vulnerable to
-`register clobbering`_. If the linker also generates code for this, e.g. for
+[register clobbering]. If the linker also generates code for this, e.g. for
call stubs, this generated code must take the same precautions.
-Dynamic symbol lookup
-~~~~~~~~~~~~~~~~~~~~~
+### Dynamic symbol lookup
On platforms that support dynamically loading or resolving symbols it is
necessary for them to define the pointer authentication semantics of the APIs
provided to perform such lookups. While the platform may choose to reply
unsigned pointers from such function and rely on the caller performing the
initial signing, doing so creates the opportunity for caller side errors that
-create :ref:`signing oracles<Signing Oracles>`.
+create {ref}`signing oracles<Signing Oracles>`.
On arm64e the `dlsym` function is used to resolve a symbol at runtime. If the
resolved symbol is a function or other code pointer the returned pointer is
signed using the default function signing schema described in
-:ref:`C function pointers<C function abi>`. If the resolved symbol is not a code pointer it is
+{ref}`C function pointers<C function abi>`. If the resolved symbol is not a code pointer it is
returned as an unsigned pointer.
-.. _C function abi:
+(c-function-abi)=
-C function pointers
-~~~~~~~~~~~~~~~~~~~
+### C function pointers
-On arm64e, C function pointers are currently signed with the ``IA`` key without
+On arm64e, C function pointers are currently signed with the `IA` key without
address diversity and with a constant discriminator of 0.
The C and C++ standards do not permit C function pointers to be signed with
address diversity by default: in C++ terms, function pointer types are required
-to be trivially copyable, which means they must be copyable with ``memcpy``.
+to be trivially copyable, which means they must be copyable with `memcpy`.
The use of a uniform constant discriminator greatly simplifies the adoption of
arm64e, but it is a significant weakness in the mitigation because it allows any
@@ -1489,210 +1375,196 @@ ABI-incompatible with the standard arm64e ABI, but it can be used in constrained
contexts such as embedded systems or in code that does not require function
pointer interoperation with the standard ABI (e.g. because it does not pass
function pointers back and forth, or only does so through
-``__ptrauth``-qualified l-values).
+`__ptrauth`-qualified l-values).
-C++ virtual tables
-~~~~~~~~~~~~~~~~~~
+### C++ virtual tables
By default the pointer to a C++ virtual table is currently signed with the
-``DA`` key, address diversity, and a constant discriminator equal to the string
-hash (see `ptrauth_string_discriminator`_) of the mangled v-table identifier
+`DA` key, address diversity, and a constant discriminator equal to the string
+hash (see [ptrauth_string_discriminator]) of the mangled v-table identifier
of the primary base class for the v-table. To support existing code or ABI
constraints it is possible to use the `ptrauth_vtable_pointer` attribute to
override the schema used for the v-table pointer of the base type of
polymorphic class hierarchy. This attribute permits the configuration of the
key, address diversity mode, and any extra constant discriminator to be used.
-Virtual functions in a C++ virtual table are signed with the ``IA`` key, address
+Virtual functions in a C++ virtual table are signed with the `IA` key, address
diversity, and a constant discriminator equal to the string hash (see
-`ptrauth_string_discriminator`_) of the mangled name of the function which
+[ptrauth_string_discriminator]) of the mangled name of the function which
originally gave rise to the v-table slot.
-C++ dynamic_cast
-~~~~~~~~~~~~~~~~
+### C++ dynamic_cast
-C++'s ``dynamic_cast`` presents a difficulty relative to other polymorphic
+C++'s `dynamic_cast` presents a difficulty relative to other polymorphic
languages that have a
`top type <https://en.wikipedia.org/wiki/Any_type>` as the use of declaration
diversity for v-table pointers results in distinct signing schemas for each
isolated type hierarchy. As a result it is not possible for the Itanium ABI
-defined ``__dynamic_cast`` entry point to directly authenticate the v-table
+defined `__dynamic_cast` entry point to directly authenticate the v-table
pointer of the provided object.
The current implementation uses a forced authentication of the subject object's
-v-table prior to invoking ``__dynamic_cast`` to partially verify that the
-object's vtable is valid. The ``__dynamic_cast`` implementation currently relies
+v-table prior to invoking `__dynamic_cast` to partially verify that the
+object's vtable is valid. The `__dynamic_cast` implementation currently relies
on this caller side check to limit the substitutability of the v-table pointer
with an incorrect or invalid v-table. The subsequent implementation of the
-dynamic cast algorithm is built on pointer auth protected ``type_info`` objects.
+dynamic cast algorithm is built on pointer auth protected `type_info` objects.
In future a richer solution may be developed to support vending the correct
-authentication schema directly to the ``dynamic_cast`` implementation.
+authentication schema directly to the `dynamic_cast` implementation.
-C++ std::type_info v-table pointers
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+### C++ std::type_info v-table pointers
-The v-table pointer of the ``std::type_info`` type is signed with the ``DA`` key
+The v-table pointer of the `std::type_info` type is signed with the `DA` key
and no additional diversity.
-C++ member function pointers
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+### C++ member function pointers
-A member function pointer is signed with the ``IA`` key, no address diversity,
+A member function pointer is signed with the `IA` key, no address diversity,
and a constant discriminator equal to the string hash
-(see `ptrauth_string_discriminator`_) of the member pointer type. Address
+(see [ptrauth_string_discriminator]) of the member pointer type. Address
diversity is not permitted by C++ for member function pointers because they must
be trivially-copyable types.
The Itanium C++ ABI specifies that member function pointers to virtual functions
-simply store an offset to the correct v-table slot. This ABI cannot be used
+simply store an offset to the correct v-table slot. This ABI cannot be used
securely with pointer authentication because there is no safe place to store the
constant discriminator for the target v-table slot: if it's stored with the
offset, an attacker can simply overwrite it with the right discriminator for the
-offset. Even if the programmer never uses pointers to virtual functions, the
+offset. Even if the programmer never uses pointers to virtual functions, the
existence of this code path makes all member function pointer dereferences
insecure.
arm64e changes this ABI so that virtual function pointers are stored using
-dispatch thunks with vague linkage. Because arm64e supports interoperation with
-``arm64`` code when pointer authentication is disabled, an arm64e member
+dispatch thunks with vague linkage. Because arm64e supports interoperation with
+`arm64` code when pointer authentication is disabled, an arm64e member
function pointer dereference still recognizes the virtual-function
representation but uses an bogus discriminator on that path that should always
trap if pointer authentication is enabled dynamically.
-The use of dispatch thunks means that ``==`` on member function pointers is no
+The use of dispatch thunks means that `==` on member function pointers is no
longer reliable for virtual functions, but this is acceptable because the
standard makes no guarantees about it in the first place.
The use of dispatch thunks also is required to support declaration specific
authentication schemas for v-table pointers.
-C++ mangling
-~~~~~~~~~~~~
+### C++ mangling
-When the ``__ptrauth`` qualifier appears in a C++ mangled name,
+When the `__ptrauth` qualifier appears in a C++ mangled name,
it is mangled as a vendor qualifier with the signature
-``U9__ptrauthILj<key>ELb<addressDiscriminated>ELj<extraDiscriminator>EE``.
+`U9__ptrauthILj<key>ELb<addressDiscriminated>ELj<extraDiscriminator>EE`.
-e.g. ``int * __ptrauth(1, 0, 1234)`` will be mangled as
-``U9__ptrauthILj1ELb0ELj1234EE``.
+e.g. `int * __ptrauth(1, 0, 1234)` will be mangled as
+`U9__ptrauthILj1ELb0ELj1234EE`.
If the vtable pointer authentication scheme of a polymorphic class is overridden
we mangle the override information with the vendor qualifier
-``__vtptrauth(int key, bool addressDiscriminated, unsigned extraDiscriminator)``,
+`__vtptrauth(int key, bool addressDiscriminated, unsigned extraDiscriminator)`,
where the extra discriminator is the explicit value the specified discrimination
mode evalutes to.
-Blocks
-~~~~~~
+### Blocks
Block pointers are data pointers which must interoperate with the ObjC `id` type
and therefore cannot be signed themselves. As blocks conform to the ObjC `id`
-type, they contain an ``isa`` pointer signed as described
-:ref:`below<Objc isa and super>`.
+type, they contain an `isa` pointer signed as described
+{ref}`below<Objc isa and super>`.
-The invocation pointer in a block is signed with the ``IA`` key using address
-diversity and a constant discriminator of 0. Using a uniform discriminator is
+The invocation pointer in a block is signed with the `IA` key using address
+diversity and a constant discriminator of 0. Using a uniform discriminator is
seen as a weakness to be potentially improved, but this is tricky due to the
subtype polymorphism directly permitted for blocks.
-Block descriptors and ``__block`` variables can contain pointers to functions
-that can be used to copy or destroy the object. These functions are signed with
-the ``IA`` key, address diversity, and a constant discriminator of 0. The
+Block descriptors and `__block` variables can contain pointers to functions
+that can be used to copy or destroy the object. These functions are signed with
+the `IA` key, address diversity, and a constant discriminator of 0. The
structure of block descriptors is under consideration for improvement.
-Objective-C runtime
-~~~~~~~~~~~~~~~~~~~
+### Objective-C runtime
In addition to the compile time ABI design, the Objective-C runtime provides
additional protection to methods and other metadata that have been loaded into
the Objective-C method cache; this protection is private to the runtime.
-Objective-C methods
-~~~~~~~~~~~~~~~~~~~
+### Objective-C methods
-Objective-C method lists sign methods with the ``IA`` key using address
-diversity and a constant discriminator of 0. Using a uniform constant
+Objective-C method lists sign methods with the `IA` key using address
+diversity and a constant discriminator of 0. Using a uniform constant
discriminator is believed to be acceptable because these tables are only
accessed internally to the Objective-C runtime.
-Objective-C class method list pointer
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+### Objective-C class method list pointer
-The method list pointer in Objective-C classes are signed with the ``DA`` key
+The method list pointer in Objective-C classes are signed with the `DA` key
using address diversity, and a constant discriminator of 0xC310.
-Objective-C class read-only data pointer
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+### Objective-C class read-only data pointer
-The read-only data pointer in Objective-C classes are signed with the ``DA`` key
+The read-only data pointer in Objective-C classes are signed with the `DA` key
using address diversity, and a constant discriminator of 0x61F8.
-.. _Objc isa and super:
+(objc-isa-and-super)=
-Objective-C ``isa`` and ``super`` pointers
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+### Objective-C `isa` and `super` pointers
-An Objective-C object's ``isa`` and ``super`` pointers are both signed with
-the ``DA`` key using address diversity and constant discriminators of 0x6AE1
+An Objective-C object's `isa` and `super` pointers are both signed with
+the `DA` key using address diversity and constant discriminators of 0x6AE1
and 0x25DA respectively.
-Objective-C ``SEL`` pointers
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+### Objective-C `SEL` pointers
-By default, the type of an Objective-C instance variable of type ``SEL``, when
-the qualifiers do not include an explicit ``__ptrauth`` qualifier, is adjusted
-to be qualified with ``__ptrauth(ptrauth_key_asdb, 1, 0x57C2)``.
+By default, the type of an Objective-C instance variable of type `SEL`, when
+the qualifiers do not include an explicit `__ptrauth` qualifier, is adjusted
+to be qualified with `__ptrauth(ptrauth_key_asdb, 1, 0x57C2)`.
-This provides a measure of implicit at-rest protection to Objective-C classes
+This provides a measure of implicit at-rest protection to Objective-C classes
that store selectors, as in the common target-action design pattern. This
prevents attackers from overriding the selector to invoke an arbitrary different
-method, which is a major attack vector in Objective-C. Since ``SEL`` values are
+method, which is a major attack vector in Objective-C. Since `SEL` values are
not normally passed around as signed pointers, there is a
-:ref:`signing oracle<Signing Oracles>` associated with the initialization of the
+{ref}`signing oracle<Signing Oracles>` associated with the initialization of the
ivar, but the use of address and constant diversity limit the risks.
The implicit qualifier means that the type of the ivar does not match its
declaration, which can cause type errors if the address of the ivar is taken:
-.. code-block:: ObjC
-
- @interface A : NSObject {
- SEL _s;
- }
- @end
+```ObjC
+ at interface A : NSObject {
+ SEL _s;
+}
+ at end
- void f(SEL *);
+void f(SEL *);
- @implementation A
- -(void)g
- {
- f(&_s);
- }
- @end
+ at implementation A
+-(void)g
+{
+ f(&_s);
+}
+ at end
+```
To fix such a mismatch the schema macro from `<ptrauth.h>`:
-.. code-block:: ObjC
+```ObjC
+#include <ptrauth.h>
- #include <ptrauth.h>
-
- void f(SEL __ptrauth_objc_sel*);
+void f(SEL __ptrauth_objc_sel*);
+```
or less safely, and introducing the possibility of an
-:ref:`signing or authentication oracle<Signing oracles>`, an unauthenticated
+{ref}`signing or authentication oracle<Signing oracles>`, an unauthenticated
temporary may be used as intermediate storage.
-Alternative implementations
----------------------------
+## Alternative implementations
-Signature storage
-~~~~~~~~~~~~~~~~~
+### Signature storage
It is not critical for the security of pointer authentication that the
signature be stored "together" with the pointer, as it is in Armv8.3. An
implementation could just as well store the signature in a separate word, so
-that the ``sizeof`` a signed pointer would be larger than the ``sizeof`` a raw
+that the `sizeof` a signed pointer would be larger than the `sizeof` a raw
pointer.
Storing the signature in the high bits, as Armv8.3 does, has several trade-offs:
@@ -1700,50 +1572,44 @@ Storing the signature in the high bits, as Armv8.3 does, has several trade-offs:
- Disadvantage: there are substantially fewer bits available for the signature,
weakening the mitigation by making it much easier for an attacker to simply
guess the correct signature.
-
- Disadvantage: future growth of the address space will necessarily further
weaken the mitigation.
-
- Advantage: memory layouts don't change, so it's possible for
pointer-authentication-enabled code (for example, in a system library) to
efficiently interoperate with existing code, as long as pointer
authentication can be disabled dynamically.
-
- Advantage: the size of a signed pointer doesn't grow, which might
significantly increase memory requirements, code size, and register pressure.
-
- Advantage: the size of a signed pointer is the same as a raw pointer, so
generic APIs which work in types like `void *` (such as `dlsym`) can still
- return signed pointers. This means that clients of these APIs will not
+ return signed pointers. This means that clients of these APIs will not
require insecure code in order to correctly receive a function pointer.
-Hashing vs. encrypting pointers
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+### Hashing vs. encrypting pointers
-Armv8.3 implements ``sign`` by computing a cryptographic hash and storing that
-in the spare bits of the pointer. This means that there are relatively few
+Armv8.3 implements `sign` by computing a cryptographic hash and storing that
+in the spare bits of the pointer. This means that there are relatively few
possible values for the valid signed pointer, since the bits corresponding to
-the raw pointer are known. Together with an ``auth`` oracle, this can make it
+the raw pointer are known. Together with an `auth` oracle, this can make it
computationally feasible to discover the correct signature with brute force.
-(The implementation should of course endeavor not to introduce ``auth``
+(The implementation should of course endeavor not to introduce `auth`
oracles, but this can be difficult, and attackers can be devious.)
-If the implementation can instead *encrypt* the pointer during ``sign`` and
-*decrypt* it during ``auth``, this brute-force attack becomes far less
-feasible, even with an ``auth`` oracle. However, there are several problems
+If the implementation can instead *encrypt* the pointer during `sign` and
+*decrypt* it during `auth`, this brute-force attack becomes far less
+feasible, even with an `auth` oracle. However, there are several problems
with this idea:
- It's unclear whether this kind of encryption is even possible without
- increasing the storage size of a signed pointer. If the storage size can be
+ increasing the storage size of a signed pointer. If the storage size can be
increased, brute-force attacks can be equally well mitigated by simply storing
a larger signature.
-
-- It would likely be impossible to implement a ``strip`` operation, which might
+- It would likely be impossible to implement a `strip` operation, which might
make debuggers and other out-of-process tools far more difficult to write, as
well as generally making primitive debugging more challenging.
-
- Implementations can benefit from being able to extract the raw pointer
- immediately from a signed pointer. An Armv8.3 processor executing an
- ``auth``-and-load instruction can perform the load and ``auth`` in parallel;
+ immediately from a signed pointer. An Armv8.3 processor executing an
+ `auth`-and-load instruction can perform the load and `auth` in parallel;
a processor which instead encrypted the pointer would be forced to perform
these operations serially.
+
diff --git a/clang/docs/SYCLSupport.md b/clang/docs/SYCLSupport.md
index 364d95a31047e..f3506c8fcaa18 100644
--- a/clang/docs/SYCLSupport.md
+++ b/clang/docs/SYCLSupport.md
@@ -1,28 +1,25 @@
-=============================================
-SYCL Compiler and Runtime architecture design
-=============================================
+# SYCL Compiler and Runtime architecture design
-.. contents::
- :local:
+```{contents}
+:local: true
+```
-Introduction
-============
+## Introduction
This document describes the architecture of the SYCL compiler and runtime
library. More details are provided in
-`external document <https://github.com/intel/llvm/blob/sycl/sycl/doc/design/CompilerAndRuntimeDesign.md>`_\ ,
+[external document](https://github.com/intel/llvm/blob/sycl/sycl/doc/design/CompilerAndRuntimeDesign.md),
which are going to be added to clang documentation in the future.
-Address space handling
-======================
+## Address space handling
The SYCL specification represents pointers to disjoint memory regions using C++
wrapper classes on an accelerator to enable compilation with a standard C++
toolchain and a SYCL compiler toolchain. Section 3.8.2 of SYCL 2020
specification defines
-`memory model <https://www.khronos.org/registry/SYCL/specs/sycl-2020/html/sycl-2020.html#_sycl_device_memory_model>`_\ ,
-section 4.7.7 - `address space classes <https://www.khronos.org/registry/SYCL/specs/sycl-2020/html/sycl-2020.html#_address_space_classes>`_
-and section 5.9 covers `address space deduction <https://www.khronos.org/registry/SYCL/specs/sycl-2020/html/sycl-2020.html#_address_space_deduction>`_.
+[memory model](https://www.khronos.org/registry/SYCL/specs/sycl-2020/html/sycl-2020.html#_sycl_device_memory_model),
+section 4.7.7 - [address space classes](https://www.khronos.org/registry/SYCL/specs/sycl-2020/html/sycl-2020.html#_address_space_classes)
+and section 5.9 covers [address space deduction](https://www.khronos.org/registry/SYCL/specs/sycl-2020/html/sycl-2020.html#_address_space_deduction).
The SYCL specification allows two modes of address space deduction: "generic as
default address space" (see section 5.9.3) and "inferred address space" (see
section 5.9.4). Current implementation supports only "generic as default address
@@ -30,7 +27,7 @@ space" mode.
SYCL borrows its memory model from OpenCL however SYCL doesn't perform
the address space qualifier inference as detailed in
-`OpenCL C v3.0 6.7.8 <https://www.khronos.org/registry/OpenCL/specs/3.0-unified/html/OpenCL_C.html#addr-spaces-inference>`_.
+[OpenCL C v3.0 6.7.8](https://www.khronos.org/registry/OpenCL/specs/3.0-unified/html/OpenCL_C.html#addr-spaces-inference).
The default address space is "generic-memory", which is a virtual address space
that overlaps the global, local, and private address spaces. SYCL mode enables
@@ -41,10 +38,10 @@ following conversions:
- implicit conversions from the address space-attributed type to the default
address space
- explicit conversions to/from the global address space from/to the
- ``__attribute__((opencl_global_device))`` or
- ``__attribute__((opencl_global_host))`` address space-attributed type
-- implicit conversions from the ``__attribute__((opencl_global_device))`` or
- ``__attribute__((opencl_global_host))`` address space-attributed type to the
+ `__attribute__((opencl_global_device))` or
+ `__attribute__((opencl_global_host))` address space-attributed type
+- implicit conversions from the `__attribute__((opencl_global_device))` or
+ `__attribute__((opencl_global_host))` address space-attributed type to the
global address space
All named address spaces are disjoint and sub-sets of default address space.
@@ -56,46 +53,46 @@ Pointers to default address space should get lowered into a pointer to a generic
address space (or flat to reuse more general terminology). But depending on the
allocation context, the default address space of a non-pointer type is assigned
to a specific address space. This is described in
-`common address space deduction rules <https://www.khronos.org/registry/SYCL/specs/sycl-2020/html/sycl-2020.html#subsec:commonAddressSpace>`_
+[common address space deduction rules](https://www.khronos.org/registry/SYCL/specs/sycl-2020/html/sycl-2020.html#subsec:commonAddressSpace)
section.
-This is also in line with the behaviour of CUDA (`small example
-<https://godbolt.org/z/veqTfo9PK>`_).
-
-``multi_ptr`` class implementation example:
-
-.. code-block:: C++
-
- // check that SYCL mode is ON and we can use non-standard decorations
- #if defined(__SYCL_DEVICE_ONLY__)
- // GPU/accelerator implementation
- template <typename T, address_space AS> class multi_ptr {
- // DecoratedType applies corresponding address space attribute to the type T
- // DecoratedType<T, global_space>::type == "__attribute__((opencl_global)) T"
- // See sycl/include/CL/sycl/access/access.hpp for more details
- using pointer_t = typename DecoratedType<T, AS>::type *;
-
- pointer_t m_Pointer;
- public:
- pointer_t get() { return m_Pointer; }
- T& operator* () { return *reinterpret_cast<T*>(m_Pointer); }
- }
- #else
- // CPU/host implementation
- template <typename T, address_space AS> class multi_ptr {
- T *m_Pointer; // regular undecorated pointer
- public:
- T *get() { return m_Pointer; }
- T& operator* () { return *m_Pointer; }
- }
- #endif
-
-Depending on the compiler mode, ``multi_ptr`` will either decorate its internal
+This is also in line with the behaviour of CUDA ([small example](https://godbolt.org/z/veqTfo9PK)).
+
+`multi_ptr` class implementation example:
+
+```C++
+// check that SYCL mode is ON and we can use non-standard decorations
+#if defined(__SYCL_DEVICE_ONLY__)
+// GPU/accelerator implementation
+template <typename T, address_space AS> class multi_ptr {
+ // DecoratedType applies corresponding address space attribute to the type T
+ // DecoratedType<T, global_space>::type == "__attribute__((opencl_global)) T"
+ // See sycl/include/CL/sycl/access/access.hpp for more details
+ using pointer_t = typename DecoratedType<T, AS>::type *;
+
+ pointer_t m_Pointer;
+ public:
+ pointer_t get() { return m_Pointer; }
+ T& operator* () { return *reinterpret_cast<T*>(m_Pointer); }
+}
+#else
+// CPU/host implementation
+template <typename T, address_space AS> class multi_ptr {
+ T *m_Pointer; // regular undecorated pointer
+ public:
+ T *get() { return m_Pointer; }
+ T& operator* () { return *m_Pointer; }
+}
+#endif
+```
+
+Depending on the compiler mode, `multi_ptr` will either decorate its internal
data with the address space attribute or not.
To utilize clang's existing functionality, we reuse the following OpenCL address
space attributes for pointers:
+```{eval-rst}
.. list-table::
:header-rows: 1
@@ -112,8 +109,9 @@ space attributes for pointers:
* - ``__attribute__((opencl_private))``
- private_space
+```
-.. code-block:: C++
-
- //TODO: add support for __attribute__((opencl_global_host)) and __attribute__((opencl_global_device)).
+```C++
+//TODO: add support for __attribute__((opencl_global_host)) and __attribute__((opencl_global_device)).
+```
diff --git a/clang/docs/SafeStack.md b/clang/docs/SafeStack.md
index edf8876931464..f859a8cb5321c 100644
--- a/clang/docs/SafeStack.md
+++ b/clang/docs/SafeStack.md
@@ -1,12 +1,10 @@
-=========
-SafeStack
-=========
+# SafeStack
-.. contents::
- :local:
+```{contents}
+:local: true
+```
-Introduction
-============
+## Introduction
SafeStack is an instrumentation pass that protects programs against attacks
based on stack buffer overflows, without introducing any measurable performance
@@ -17,15 +15,12 @@ while the unsafe stack stores everything else. This separation ensures that
buffer overflows on the unsafe stack cannot be used to overwrite anything
on the safe stack.
-SafeStack is a part of the `Code-Pointer Integrity (CPI) Project
-<https://dslab.epfl.ch/research/cpi/>`_.
+SafeStack is a part of the [Code-Pointer Integrity (CPI) Project](https://dslab.epfl.ch/research/cpi/).
-Performance
------------
+### Performance
The performance overhead of the SafeStack instrumentation is less than 0.1% on
-average across a variety of benchmarks (see the `Code-Pointer Integrity
-<https://dslab.epfl.ch/pubs/cpi.pdf>`__ paper for details). This is mainly
+average across a variety of benchmarks (see the [Code-Pointer Integrity](https://dslab.epfl.ch/pubs/cpi.pdf) paper for details). This is mainly
because most small functions do not have any variables that require the unsafe
stack and, hence, do not need unsafe stack frames to be created. The cost of
creating unsafe stack frames for large functions is amortized by the cost of
@@ -37,8 +32,7 @@ used through multiple stack frames. Moving such objects away from the safe
stack increases the locality of frequently accessed values on the stack, such
as register spills, return addresses, and small local variables.
-Compatibility
--------------
+### Compatibility
Most programs, static libraries, or individual files can be compiled
with SafeStack as is. SafeStack requires basic runtime support, which, on most
@@ -47,8 +41,7 @@ in when the program is compiled with SafeStack.
Linking a DSO with SafeStack is not currently supported.
-Known compatibility limitations
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+#### Known compatibility limitations
Certain code that relies on low-level stack manipulations requires adaption to
work with SafeStack. One example is mark-and-sweep garbage collection
@@ -60,13 +53,12 @@ without SafeStack. An executable compiled with SafeStack can load dynamic
libraries that are not compiled with SafeStack. At the moment, compiling
dynamic libraries with SafeStack is not supported.
-Signal handlers that use ``sigaltstack()`` must not use the unsafe stack (see
-``__attribute__((no_sanitize("safe-stack")))`` below).
+Signal handlers that use `sigaltstack()` must not use the unsafe stack (see
+`__attribute__((no_sanitize("safe-stack")))` below).
-Programs that use APIs from ``ucontext.h`` are not supported yet.
+Programs that use APIs from `ucontext.h` are not supported yet.
-Security
---------
+### Security
SafeStack protects return addresses, spilled registers and local variables that
are always accessed in a safe way by separating them in a dedicated safe stack
@@ -78,16 +70,14 @@ randomization and information hiding: the safe stack is allocated at a random
address and the instrumentation ensures that no pointers to the safe stack are
ever stored outside of the safe stack itself (see limitations below).
-Known security limitations
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+#### Known security limitations
A complete protection against control-flow hijack attacks requires combining
SafeStack with another mechanism that enforces the integrity of code pointers
-that are stored on the heap or the unsafe stack, such as `CPI
-<https://dslab.epfl.ch/research/cpi/>`_, or a forward-edge control flow integrity
+that are stored on the heap or the unsafe stack, such as [CPI](https://dslab.epfl.ch/research/cpi/), or a forward-edge control flow integrity
mechanism that enforces correct calling conventions at indirect call sites,
-such as `IFCC <https://research.google.com/pubs/archive/42808.pdf>`_ with arity
-checks. Clang has control-flow integrity protection scheme for :doc:`C++ virtual
+such as [IFCC](https://research.google.com/pubs/archive/42808.pdf) with arity
+checks. Clang has control-flow integrity protection scheme for {doc}`C++ virtual
calls <ControlFlowIntegrity>`, but not non-virtual indirect calls. With
SafeStack alone, an attacker can overwrite a function pointer on the heap or
the unsafe stack and cause a program to call arbitrary location, which in turn
@@ -98,15 +88,15 @@ stack-based buffer overflows, but protection against arbitrary memory write
vulnerabilities is probabilistic and relies on randomization and information
hiding. The randomization is currently based on system-enforced ASLR and shares
its known security limitations. The safe stack pointer hiding is not perfect
-yet either: system library functions such as ``swapcontext``, exception
-handling mechanisms, intrinsics such as ``__builtin_frame_address``, or
+yet either: system library functions such as `swapcontext`, exception
+handling mechanisms, intrinsics such as `__builtin_frame_address`, or
low-level bugs in runtime support could leak the safe stack pointer. In the
future, such leaks could be detected by static or dynamic analysis tools and
prevented by adjusting such functions to either encrypt the stack pointer when
-storing it in the heap (as already done e.g., by ``setjmp``/``longjmp``
+storing it in the heap (as already done e.g., by `setjmp`/`longjmp`
implementation in glibc), or store it in a safe region instead.
-The `CPI paper <https://dslab.epfl.ch/pubs/cpi.pdf>`_ describes two alternative,
+The [CPI paper](https://dslab.epfl.ch/pubs/cpi.pdf) describes two alternative,
stronger safe stack protection mechanisms, that rely on software fault
isolation, or hardware segmentation (as available on x86-32 and some x86-64
CPUs).
@@ -117,39 +107,34 @@ always regress in the future. It's therefore desirable to have a separate
static or dynamic binary verification tool that would check the correctness of
the SafeStack instrumentation in final binaries.
-Usage
-=====
+## Usage
-To enable SafeStack, just pass ``-fsanitize=safe-stack`` flag to both compile
+To enable SafeStack, just pass `-fsanitize=safe-stack` flag to both compile
and link command lines.
-Supported Platforms
--------------------
+### Supported Platforms
SafeStack was tested on Linux, NetBSD, FreeBSD and macOS.
-Low-level API
--------------
+### Low-level API
-``__has_feature(safe_stack)``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+#### `__has_feature(safe_stack)`
In some rare cases one may need to execute different code depending on
-whether SafeStack is enabled. The macro ``__has_feature(safe_stack)`` can
+whether SafeStack is enabled. The macro `__has_feature(safe_stack)` can
be used for this purpose.
-.. code-block:: c
+```c
+#if __has_feature(safe_stack)
+// code that builds only under SafeStack
+#endif
+```
- #if __has_feature(safe_stack)
- // code that builds only under SafeStack
- #endif
+#### `__attribute__((no_sanitize("safe-stack")))`
-``__attribute__((no_sanitize("safe-stack")))``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Use ``__attribute__((no_sanitize("safe-stack")))`` on a function declaration
+Use `__attribute__((no_sanitize("safe-stack")))` on a function declaration
to specify that the safe stack instrumentation should not be applied to that
-function, even if enabled globally (see ``-fsanitize=safe-stack`` flag). This
+function, even if enabled globally (see `-fsanitize=safe-stack` flag). This
attribute may be required for functions that make assumptions about the
exact layout of their stack frames.
@@ -159,79 +144,66 @@ these variables, so extra care must be taken to manually ensure that all such
accesses are safe. Furthermore, the addresses of such local variables should
never be stored on the heap, as it would leak the location of the SafeStack.
-``sanitizer/safestack_interface.h``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+#### `sanitizer/safestack_interface.h`
-To use the low-level API, include the header ``<sanitizer/safestack_interface.h>``.
+To use the low-level API, include the header `<sanitizer/safestack_interface.h>`.
-``__safestack_get_unsafe_stack_ptr()``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+#### `__safestack_get_unsafe_stack_ptr()`
This function returns current unsafe stack pointer of the current thread.
-``__safestack_get_unsafe_stack_bottom()``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+#### `__safestack_get_unsafe_stack_bottom()`
This function returns a pointer to the bottom of the unsafe stack of the
current thread.
-``__safestack_get_unsafe_stack_top()``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+#### `__safestack_get_unsafe_stack_top()`
This function returns a pointer to the top of the unsafe stack of the
current thread.
-
-
-Deprecated Builtins
-~~~~~~~~~~~~~~~~~~~
+#### Deprecated Builtins
The following builtins are still supported but are deprecated and will emit a
-warning. Use the corresponding functions from ``<sanitizer/safestack_interface.h>``
+warning. Use the corresponding functions from `<sanitizer/safestack_interface.h>`
instead.
-``__builtin___get_unsafe_stack_ptr()``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+#### `__builtin___get_unsafe_stack_ptr()`
-Deprecated alias for ``__safestack_get_unsafe_stack_ptr()``.
+Deprecated alias for `__safestack_get_unsafe_stack_ptr()`.
-``__builtin___get_unsafe_stack_bottom()``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+#### `__builtin___get_unsafe_stack_bottom()`
-Deprecated alias for ``__safestack_get_unsafe_stack_bottom()``.
+Deprecated alias for `__safestack_get_unsafe_stack_bottom()`.
-``__builtin___get_unsafe_stack_top()``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+#### `__builtin___get_unsafe_stack_top()`
-Deprecated alias for ``__safestack_get_unsafe_stack_top()``.
+Deprecated alias for `__safestack_get_unsafe_stack_top()`.
-``__builtin___get_unsafe_stack_start()``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+#### `__builtin___get_unsafe_stack_start()`
-Deprecated alias for ``__safestack_get_unsafe_stack_bottom()``.
+Deprecated alias for `__safestack_get_unsafe_stack_bottom()`.
-Design
-======
+## Design
-Please refer to the `Code-Pointer Integrity <https://dslab.epfl.ch/research/cpi/>`__
+Please refer to the [Code-Pointer Integrity](https://dslab.epfl.ch/research/cpi/)
project page for more information about the design of the SafeStack and its
related technologies.
-setjmp and exception handling
------------------------------
+### setjmp and exception handling
-The `OSDI'14 paper <https://dslab.epfl.ch/pubs/cpi.pdf>`_ mentions that
+The [OSDI'14 paper](https://dslab.epfl.ch/pubs/cpi.pdf) mentions that
on Linux the instrumentation pass finds calls to setjmp or functions that
may throw an exception, and inserts required instrumentation at their call
sites. Specifically, the instrumentation pass saves the shadow stack pointer
on the safe stack before the call site, and restores it either after the
call to setjmp or after an exception has been caught. This is implemented
-in the function ``SafeStack::createStackRestorePoints``.
+in the function `SafeStack::createStackRestorePoints`.
-Publications
-------------
+### Publications
-`Code-Pointer Integrity <https://dslab.epfl.ch/pubs/cpi.pdf>`__.
+[Code-Pointer Integrity](https://dslab.epfl.ch/pubs/cpi.pdf).
Volodymyr Kuznetsov, Laszlo Szekeres, Mathias Payer, George Candea, R. Sekar, Dawn Song.
USENIX Symposium on Operating Systems Design and Implementation
-(`OSDI <https://www.usenix.org/conference/osdi14>`_), Broomfield, CO, October 2014
+([OSDI](https://www.usenix.org/conference/osdi14)), Broomfield, CO, October 2014
+
diff --git a/clang/docs/SanitizerSpecialCaseList.md b/clang/docs/SanitizerSpecialCaseList.md
index 918abf19f8f10..c9c866be05ade 100644
--- a/clang/docs/SanitizerSpecialCaseList.md
+++ b/clang/docs/SanitizerSpecialCaseList.md
@@ -1,279 +1,270 @@
-===========================
-Sanitizer special case list
-===========================
+# Sanitizer special case list
-.. contents::
- :local:
+```{contents}
+:local: true
+```
-Introduction
-============
+## Introduction
This document describes the way to disable or alter the behavior of
sanitizer tools for certain source-level entities by providing a special
file at compile-time.
-Goal and usage
-==============
+## Goal and usage
-Users of sanitizer tools, such as :doc:`AddressSanitizer`,
-:doc:`HardwareAssistedAddressSanitizerDesign`, :doc:`ThreadSanitizer`,
-:doc:`MemorySanitizer` or :doc:`UndefinedBehaviorSanitizer` may want to disable
+Users of sanitizer tools, such as {doc}`AddressSanitizer`,
+{doc}`HardwareAssistedAddressSanitizerDesign`, {doc}`ThreadSanitizer`,
+{doc}`MemorySanitizer` or {doc}`UndefinedBehaviorSanitizer` may want to disable
or alter some checks for certain source-level entities to:
-* speedup hot function, which is known to be correct;
-* ignore a function that does some low-level magic (e.g. walks through the
+- speedup hot function, which is known to be correct;
+- ignore a function that does some low-level magic (e.g. walks through the
thread stack, bypassing the frame boundaries);
-* ignore a known problem.
+- ignore a known problem.
To achieve this, user may create a file listing the entities they want to
ignore, and pass it to clang at compile-time using
-``-fsanitize-ignorelist`` flag. See :doc:`UsersManual` for details.
-
-Example
-=======
-
-.. code-block:: bash
-
- $ cat foo.c
- #include <stdlib.h>
- void bad_foo() {
- int *a = (int*)malloc(40);
- a[10] = 1;
- free(a);
- }
- int main() { bad_foo(); }
- $ cat ignorelist.txt
- # Ignore reports from bad_foo function.
- fun:bad_foo
- $ clang -fsanitize=address foo.c ; ./a.out
- # AddressSanitizer prints an error report.
- $ clang -fsanitize=address -fsanitize-ignorelist=ignorelist.txt foo.c ; ./a.out
- # No error report here.
-
-Usage with UndefinedBehaviorSanitizer
-=====================================
-
-``unsigned-integer-overflow``, ``signed-integer-overflow``,
-``implicit-signed-integer-truncation``,
-``implicit-unsigned-integer-truncation``, and ``enum`` sanitizers support the
+`-fsanitize-ignorelist` flag. See {doc}`UsersManual` for details.
+
+## Example
+
+```bash
+$ cat foo.c
+#include <stdlib.h>
+void bad_foo() {
+ int *a = (int*)malloc(40);
+ a[10] = 1;
+ free(a);
+}
+int main() { bad_foo(); }
+$ cat ignorelist.txt
+# Ignore reports from bad_foo function.
+fun:bad_foo
+$ clang -fsanitize=address foo.c ; ./a.out
+# AddressSanitizer prints an error report.
+$ clang -fsanitize=address -fsanitize-ignorelist=ignorelist.txt foo.c ; ./a.out
+# No error report here.
+```
+
+## Usage with UndefinedBehaviorSanitizer
+
+`unsigned-integer-overflow`, `signed-integer-overflow`,
+`implicit-signed-integer-truncation`,
+`implicit-unsigned-integer-truncation`, and `enum` sanitizers support the
ability to adjust instrumentation based on type.
By default, supported sanitizers will have their instrumentation disabled for
entries specified within an ignorelist.
-.. code-block:: bash
-
- $ cat foo.c
- void foo() {
- int a = 2147483647; // INT_MAX
- ++a; // Normally, an overflow with -fsanitize=signed-integer-overflow
- }
- $ cat ignorelist.txt
- [signed-integer-overflow]
- type:int
- $ clang -fsanitize=signed-integer-overflow -fsanitize-ignorelist=ignorelist.txt foo.c ; ./a.out
- # no signed-integer-overflow error
-
-For example, supplying the above ``ignorelist.txt`` to
-``-fsanitize-ignorelist=ignorelist.txt`` disables overflow sanitizer
-instrumentation for arithmetic operations containing values of type ``int``.
-
-The ``=sanitize`` category is also supported. Any ``=sanitize`` category
+```bash
+$ cat foo.c
+void foo() {
+ int a = 2147483647; // INT_MAX
+ ++a; // Normally, an overflow with -fsanitize=signed-integer-overflow
+}
+$ cat ignorelist.txt
+[signed-integer-overflow]
+type:int
+$ clang -fsanitize=signed-integer-overflow -fsanitize-ignorelist=ignorelist.txt foo.c ; ./a.out
+# no signed-integer-overflow error
+```
+
+For example, supplying the above `ignorelist.txt` to
+`-fsanitize-ignorelist=ignorelist.txt` disables overflow sanitizer
+instrumentation for arithmetic operations containing values of type `int`.
+
+The `=sanitize` category is also supported. Any `=sanitize` category
entries enable sanitizer instrumentation, even if it was ignored by entries
-before. Entries can be ``src``, ``type``, ``global``, ``fun``, and
-``mainfile``.
+before. Entries can be `src`, `type`, `global`, `fun`, and
+`mainfile`.
With this, one may disable instrumentation for some or all types and
specifically allow instrumentation for one or many types -- including types
-created via ``typedef``. This is a way to achieve a sort of "allowlist" for
+created via `typedef`. This is a way to achieve a sort of "allowlist" for
supported sanitizers.
-.. code-block:: bash
-
- $ cat ignorelist.txt
- [implicit-signed-integer-truncation]
- type:*
- type:T=sanitize
-
- $ cat foo.c
- typedef char T;
- typedef char U;
- void foo(int toobig) {
- T a = toobig; // instrumented
- U b = toobig; // not instrumented
- char c = toobig; // also not instrumented
- }
+```bash
+$ cat ignorelist.txt
+[implicit-signed-integer-truncation]
+type:*
+type:T=sanitize
+
+$ cat foo.c
+typedef char T;
+typedef char U;
+void foo(int toobig) {
+ T a = toobig; // instrumented
+ U b = toobig; // not instrumented
+ char c = toobig; // also not instrumented
+}
+```
If multiple entries match the source, then the latest entry takes the
precedence. Here are a few examples.
-.. code-block:: bash
-
- $ cat ignorelist1.txt
- # test.cc will not be instrumented.
- src:*
- src:*/mylib/*=sanitize
- src:*/mylib/test.cc
-
- $ cat ignorelist2.txt
- # test.cc will be instrumented.
- src:*
- src:*/mylib/test.cc
- src:*/mylib/*=sanitize
-
- $ cat ignorelist3.txt
- # Type T will not be instrumented.
- type:*
- type:T=sanitize
- type:T
-
- $ cat ignorelist4.txt
- # Function `bad_bar` will be instrumented.
- # Function `good_bar` will not be instrumented.
- fun:*
- fun:*bar
- fun:bad_bar=sanitize
-
-Interaction with Overflow Behavior Types
-----------------------------------------
-
-The ``overflow_behavior`` attribute provides a more granular, source-level
+```bash
+$ cat ignorelist1.txt
+# test.cc will not be instrumented.
+src:*
+src:*/mylib/*=sanitize
+src:*/mylib/test.cc
+
+$ cat ignorelist2.txt
+# test.cc will be instrumented.
+src:*
+src:*/mylib/test.cc
+src:*/mylib/*=sanitize
+
+$ cat ignorelist3.txt
+# Type T will not be instrumented.
+type:*
+type:T=sanitize
+type:T
+
+$ cat ignorelist4.txt
+# Function `bad_bar` will be instrumented.
+# Function `good_bar` will not be instrumented.
+fun:*
+fun:*bar
+fun:bad_bar=sanitize
+```
+
+### Interaction with Overflow Behavior Types
+
+The `overflow_behavior` attribute provides a more granular, source-level
control that takes precedence over the Sanitizer Special Case List. If a type
-is given an ``overflow_behavior`` attribute, it will override any matching
-``type:`` entry in a special case list.
+is given an `overflow_behavior` attribute, it will override any matching
+`type:` entry in a special case list.
This allows developers to enforce a specific overflow behavior for a critical
type, even if a broader rule in the special case list would otherwise disable
instrumentation for it.
-.. code-block:: bash
-
- $ cat ignorelist.txt
- # Disable signed overflow checks for all types by default.
- [signed-integer-overflow]
- type:*
+```bash
+$ cat ignorelist.txt
+# Disable signed overflow checks for all types by default.
+[signed-integer-overflow]
+type:*
- $ cat foo.c
- // Force 'critical_type' to always have overflow checks,
- // overriding the ignorelist.
- typedef int __attribute__((overflow_behavior(trap))) critical_type;
+$ cat foo.c
+// Force 'critical_type' to always have overflow checks,
+// overriding the ignorelist.
+typedef int __attribute__((overflow_behavior(trap))) critical_type;
- void foo(int x) {
- critical_type a = x;
- a++; // Overflow is checked here due to the 'trap' attribute.
+void foo(int x) {
+ critical_type a = x;
+ a++; // Overflow is checked here due to the 'trap' attribute.
- int b = x;
- b++; // Overflow is NOT checked here due to the ignorelist.
- }
+ int b = x;
+ b++; // Overflow is NOT checked here due to the ignorelist.
+}
+```
-For more details on overflow behavior types, see :doc:`OverflowBehaviorTypes`.
+For more details on overflow behavior types, see {doc}`OverflowBehaviorTypes`.
-Format
-======
+## Format
Ignorelists consist of entries, optionally grouped into sections. Empty lines
and lines starting with "#" are ignored.
-.. note::
+:::{note}
+Prior to Clang 18, section names and entries described below use a variant of
+regex where `*` is translated to `.*`. Clang 18 (`D154014
+<https://reviews.llvm.org/D154014>`) switches to glob and plans to remove
+regex support in Clang 19.
- Prior to Clang 18, section names and entries described below use a variant of
- regex where ``*`` is translated to ``.*``. Clang 18 (`D154014
- <https://reviews.llvm.org/D154014>`) switches to glob and plans to remove
- regex support in Clang 19.
+For Clang 18, regex is supported if `#!special-case-list-v1` is the first
+line of the file.
- For Clang 18, regex is supported if ``#!special-case-list-v1`` is the first
- line of the file.
-
- Many special case lists use ``.`` to indicate the literal character and do
- not use regex metacharacters such as ``(``, ``)``. They are unaffected by the
- regex to glob transition. For more details, see `this discourse post
- <https://discourse.llvm.org/t/use-glob-instead-of-regex-for-specialcaselists/71666>`_.
+Many special case lists use `.` to indicate the literal character and do
+not use regex metacharacters such as `(`, `)`. They are unaffected by the
+regex to glob transition. For more details, see [this discourse post](https://discourse.llvm.org/t/use-glob-instead-of-regex-for-specialcaselists/71666).
+:::
Section names are globs written in square brackets that denote
-which sanitizer the following entries apply to. For example, ``[address]``
-specifies AddressSanitizer while ``[{cfi-vcall,cfi-icall}]`` specifies Control
+which sanitizer the following entries apply to. For example, `[address]`
+specifies AddressSanitizer while `[{cfi-vcall,cfi-icall}]` specifies Control
Flow Integrity virtual and indirect call checking. Entries without a section
-will be placed under the ``[*]`` section applying to all enabled sanitizers.
+will be placed under the `[*]` section applying to all enabled sanitizers.
Entries contain an entity type, followed by a colon and a glob,
specifying the names of the entities, optionally followed by an equals sign and
-a tool-specific category, e.g. ``fun:*ExampleFunc=example_category``.
-Two generic entity types are ``src`` and
-``fun``, which allow users to specify source files and functions, respectively.
+a tool-specific category, e.g. `fun:*ExampleFunc=example_category`.
+Two generic entity types are `src` and
+`fun`, which allow users to specify source files and functions, respectively.
Some sanitizer tools may introduce custom entity types and categories - refer to
tool-specific docs.
-.. code-block:: bash
-
- # Lines starting with # are ignored.
- # Turn off checks for the source file
- # Entries without sections are placed into [*] and apply to all sanitizers
- src:path/to/source/file.c
- src:*/source/file.c
- # Turn off checks for this main file, including files included by it.
- # Useful when the main file instead of an included file should be ignored.
- mainfile:file.c
- # Turn off checks for a particular functions (use mangled names):
- fun:_Z8MyFooBarv
- # Glob brace expansions and character ranges are supported
- fun:bad_{foo,bar}
- src:bad_source[1-9].c
- # "*" matches zero or more characters
- src:bad/sources/*
- fun:*BadFunction*
- # Specific sanitizer tools may introduce categories.
- src:/special/path/*=special_sources
- # Sections can be used to limit ignorelist entries to specific sanitizers
- [address]
- fun:*BadASanFunc*
- # Section names are globs
- [{cfi-vcall,cfi-icall}]
- fun:*BadCfiCall
-
-
-.. note::
-
- By default, ``src`` and ``mainfile`` are matched against the filename as seen
- by LLVM. On Windows, this might involve a mix of forward and backslashes as
- file separators, and writing patterns to match both variants can be
- inconvenient.
-
- Starting with version 4 (indicated by ``#!special-case-list-v4``), path matching
- on Windows hosts is slash-agnostic: both forward slashes (``/``) and backslashes
- (``\``) match either path separator in both patterns and paths.
-
-.. note::
-
- By default, path matching (for ``src`` and ``mainfile``) matches the query
- path as-is. For example, a query with ``./foo.c`` will not match a rule
- defined as ``src:foo.c``.
-
- Starting with version 3 (indicated by ``#!special-case-list-v3``), leading
- ``./`` is canonicalized (removed) from paths before matching. This means
- a rule like ``src:foo.c`` will match both ``foo.c`` and ``./foo.c``, while
- a rule like ``src:./foo.c`` will no longer match.
-
- Version 4 (indicated by ``#!special-case-list-v4``) is a transition version
- that maintains backward compatibility by matching both canonicalized and
- non-canonicalized paths, but emits a warning if a match would be lost in
- Version 5 (i.e., if it only matches because of the deprecated leading ``./``
- in the rule).
-
- Version 5 (indicated by ``#!special-case-list-v5``) drops backward
- compatibility and behaves like Version 3.
-
-
-``mainfile`` is similar to applying ``-fno-sanitize=`` to a set of files but
+```bash
+# Lines starting with # are ignored.
+# Turn off checks for the source file
+# Entries without sections are placed into [*] and apply to all sanitizers
+src:path/to/source/file.c
+src:*/source/file.c
+# Turn off checks for this main file, including files included by it.
+# Useful when the main file instead of an included file should be ignored.
+mainfile:file.c
+# Turn off checks for a particular functions (use mangled names):
+fun:_Z8MyFooBarv
+# Glob brace expansions and character ranges are supported
+fun:bad_{foo,bar}
+src:bad_source[1-9].c
+# "*" matches zero or more characters
+src:bad/sources/*
+fun:*BadFunction*
+# Specific sanitizer tools may introduce categories.
+src:/special/path/*=special_sources
+# Sections can be used to limit ignorelist entries to specific sanitizers
+[address]
+fun:*BadASanFunc*
+# Section names are globs
+[{cfi-vcall,cfi-icall}]
+fun:*BadCfiCall
+```
+
+:::{note}
+By default, `src` and `mainfile` are matched against the filename as seen
+by LLVM. On Windows, this might involve a mix of forward and backslashes as
+file separators, and writing patterns to match both variants can be
+inconvenient.
+
+Starting with version 4 (indicated by `#!special-case-list-v4`), path matching
+on Windows hosts is slash-agnostic: both forward slashes (`/`) and backslashes
+(`\`) match either path separator in both patterns and paths.
+:::
+
+:::{note}
+By default, path matching (for `src` and `mainfile`) matches the query
+path as-is. For example, a query with `./foo.c` will not match a rule
+defined as `src:foo.c`.
+
+Starting with version 3 (indicated by `#!special-case-list-v3`), leading
+`./` is canonicalized (removed) from paths before matching. This means
+a rule like `src:foo.c` will match both `foo.c` and `./foo.c`, while
+a rule like `src:./foo.c` will no longer match.
+
+Version 4 (indicated by `#!special-case-list-v4`) is a transition version
+that maintains backward compatibility by matching both canonicalized and
+non-canonicalized paths, but emits a warning if a match would be lost in
+Version 5 (i.e., if it only matches because of the deprecated leading `./`
+in the rule).
+
+Version 5 (indicated by `#!special-case-list-v5`) drops backward
+compatibility and behaves like Version 3.
+:::
+
+`mainfile` is similar to applying `-fno-sanitize=` to a set of files but
does not need plumbing into the build system. This works well for internal
linkage functions but has a caveat for C++ vague linkage functions.
C++ vague linkage functions (e.g. inline functions, template instantiations) are
deduplicated at link time. A function (in an included file) ignored by a
-specific ``mainfile`` pattern may not be the prevailing copy picked by the
-linker. Therefore, using ``mainfile`` requires caution. It may still be useful,
+specific `mainfile` pattern may not be the prevailing copy picked by the
+linker. Therefore, using `mainfile` requires caution. It may still be useful,
e.g. when patterns are picked in a way to ensure the prevailing one is ignored.
(There is action-at-a-distance risk.)
-``mainfile`` can be useful enabling a ubsan check for a large code base when
+`mainfile` can be useful enabling a ubsan check for a large code base when
finding the direct stack frame triggering the failure for every failure is
difficult.
+
diff --git a/clang/docs/SanitizerStats.md b/clang/docs/SanitizerStats.md
index cbc3b37d31c53..5dc1cc34e83b4 100644
--- a/clang/docs/SanitizerStats.md
+++ b/clang/docs/SanitizerStats.md
@@ -1,39 +1,36 @@
-==============
-SanitizerStats
-==============
+# SanitizerStats
-.. contents::
- :local:
+```{contents}
+:local: true
+```
-Introduction
-============
+## Introduction
The sanitizers support a simple mechanism for gathering profiling statistics
to help understand the overhead associated with sanitizers.
-How to build and run
-====================
+## How to build and run
-SanitizerStats can currently only be used with :doc:`ControlFlowIntegrity`.
-In addition to ``-fsanitize=cfi*``, pass the ``-fsanitize-stats`` flag.
+SanitizerStats can currently only be used with {doc}`ControlFlowIntegrity`.
+In addition to `-fsanitize=cfi*`, pass the `-fsanitize-stats` flag.
This will cause the program to count the number of times that each control
flow integrity check in the program fires.
-At run time, set the ``SANITIZER_STATS_PATH`` environment variable to direct
+At run time, set the `SANITIZER_STATS_PATH` environment variable to direct
statistics output to a file. The file will be written on process exit.
The following substitutions will be applied to the environment variable:
- - ``%b`` -- The executable basename.
- - ``%p`` -- The process ID.
+> - `%b` -- The executable basename.
+> - `%p` -- The process ID.
-You can also send the ``SIGUSR2`` signal to a process to make it write
+You can also send the `SIGUSR2` signal to a process to make it write
sanitizer statistics immediately.
-The ``sanstats`` program can be used to dump statistics. It takes as a
+The `sanstats` program can be used to dump statistics. It takes as a
command line argument the path to a statistics file produced by a program
-compiled with ``-fsanitize-stats``.
+compiled with `-fsanitize-stats`.
-The output of ``sanstats`` is in four columns, separated by spaces. The first
+The output of `sanstats` is in four columns, separated by spaces. The first
column is the file and line number of the call site. The second column is
the function name. The third column is the type of statistic gathered (in
this case, the type of control flow integrity check). The fourth column is
@@ -41,22 +38,23 @@ the call count.
Example:
-.. code-block:: console
-
- $ cat -n vcall.cc
- 1 struct A {
- 2 virtual void f() {}
- 3 };
- 4
- 5 __attribute__((noinline)) void g(A *a) {
- 6 a->f();
- 7 }
- 8
- 9 int main() {
- 10 A a;
- 11 g(&a);
- 12 }
- $ clang++ -fsanitize=cfi -fvisibility=hidden -flto -fuse-ld=gold vcall.cc -fsanitize-stats -g
- $ SANITIZER_STATS_PATH=a.stats ./a.out
- $ sanstats a.stats
- vcall.cc:6 _Z1gP1A cfi-vcall 1
+```console
+$ cat -n vcall.cc
+ 1 struct A {
+ 2 virtual void f() {}
+ 3 };
+ 4
+ 5 __attribute__((noinline)) void g(A *a) {
+ 6 a->f();
+ 7 }
+ 8
+ 9 int main() {
+ 10 A a;
+ 11 g(&a);
+ 12 }
+$ clang++ -fsanitize=cfi -fvisibility=hidden -flto -fuse-ld=gold vcall.cc -fsanitize-stats -g
+$ SANITIZER_STATS_PATH=a.stats ./a.out
+$ sanstats a.stats
+vcall.cc:6 _Z1gP1A cfi-vcall 1
+```
+
diff --git a/clang/docs/ShadowCallStack.md b/clang/docs/ShadowCallStack.md
index 9b104cc3b7180..a9b4af4d72c3d 100644
--- a/clang/docs/ShadowCallStack.md
+++ b/clang/docs/ShadowCallStack.md
@@ -1,12 +1,10 @@
-===============
-ShadowCallStack
-===============
+# ShadowCallStack
-.. contents::
- :local:
+```{contents}
+:local: true
+```
-Introduction
-============
+## Introduction
ShadowCallStack is an instrumentation pass, currently only implemented for
aarch64 and RISC-V, that protects programs against return address overwrites
@@ -17,68 +15,57 @@ in the function epilog. The return address is also stored on the regular stack
for compatibility with unwinders, but is otherwise unused.
The aarch64 implementation is considered production ready, and
-an `implementation of the runtime`_ has been added to Android's libc
+an [implementation of the runtime] has been added to Android's libc
(bionic). An x86_64 implementation was evaluated using Chromium and was found
to have critical performance and security deficiencies--it was removed in
LLVM 9.0. Details on the x86_64 implementation can be found in the
-`Clang 7.0.1 documentation`_.
+[Clang 7.0.1 documentation].
-.. _`implementation of the runtime`: https://android.googlesource.com/platform/bionic/+/808d176e7e0dd727c7f929622ec017f6e065c582/libc/bionic/pthread_create.cpp#128
-.. _`Clang 7.0.1 documentation`: https://releases.llvm.org/7.0.1/tools/clang/docs/ShadowCallStack.html
-
-Comparison
-----------
+### Comparison
To optimize for memory consumption and cache locality, the shadow call
stack stores only an array of return addresses. This is in contrast to other
-schemes, like :doc:`SafeStack`, that mirror the entire stack and trade-off
+schemes, like {doc}`SafeStack`, that mirror the entire stack and trade-off
consuming more memory for shorter function prologs and epilogs with fewer
memory accesses.
-`Return Flow Guard`_ is a pure software implementation of shadow call stacks
+[Return Flow Guard] is a pure software implementation of shadow call stacks
on x86_64. Like the previous implementation of ShadowCallStack on x86_64, it is
inherently racy due to the architecture's use of the stack for calls and
returns.
-Intel `Control-flow Enforcement Technology`_ (CET) is a proposed hardware
+Intel [Control-flow Enforcement Technology] (CET) is a proposed hardware
extension that would add native support to use a shadow stack to store/check
return addresses at call/return time. Being a hardware implementation, it
would not suffer from race conditions and would not incur the overhead of
function instrumentation, but it does require operating system support.
-.. _`Return Flow Guard`: https://xlab.tencent.com/en/2016/11/02/return-flow-guard/
-.. _`Control-flow Enforcement Technology`: https://software.intel.com/sites/default/files/managed/4d/2a/control-flow-enforcement-technology-preview.pdf
-
-Compatibility
--------------
+### Compatibility
A runtime is not provided in compiler-rt so one must be provided by the
compiled application or the operating system. Integrating the runtime into
the operating system should be preferred since otherwise all thread creation
and destruction would need to be intercepted by the application.
-The instrumentation makes use of the platform register ``x18`` on AArch64,
-``x3`` (``gp``) on RISC-V with software shadow stack and ``ssp`` on RISC-V with
-hardware shadow stack, which needs `Zicfiss`_ and ``-fcf-protection=return``.
+The instrumentation makes use of the platform register `x18` on AArch64,
+`x3` (`gp`) on RISC-V with software shadow stack and `ssp` on RISC-V with
+hardware shadow stack, which needs [Zicfiss] and `-fcf-protection=return`.
Users can choose between the software and hardware based shadow stack
-implementation on RISC-V backend by passing ``-fsanitize=shadow-call-stack``
-or ``Zicfiss`` with ``-fcf-protection=return``.
-For simplicity we will refer to this as the ``SCSReg``. On some platforms,
-``SCSReg`` is reserved, and on others, it is designated as a scratch register.
+implementation on RISC-V backend by passing `-fsanitize=shadow-call-stack`
+or `Zicfiss` with `-fcf-protection=return`.
+For simplicity we will refer to this as the `SCSReg`. On some platforms,
+`SCSReg` is reserved, and on others, it is designated as a scratch register.
This generally means that any code that may run on the same thread as code
compiled with ShadowCallStack must either target one of the platforms whose ABI
-reserves ``SCSReg`` (currently Android, Darwin, Fuchsia and Windows) or be
-compiled with a flag to reserve that register (e.g., ``-ffixed-x18``). If
+reserves `SCSReg` (currently Android, Darwin, Fuchsia and Windows) or be
+compiled with a flag to reserve that register (e.g., `-ffixed-x18`). If
absolutely necessary, code compiled without reserving the register may be run on
the same thread as code that uses ShadowCallStack by saving the register value
-temporarily on the stack (`example in Android`_) but this should be done with
+temporarily on the stack ([example in Android]) but this should be done with
care since it risks leaking the shadow call stack address.
-.. _`Zicfiss`: https://github.com/riscv/riscv-cfi/blob/main/cfi_backward.adoc
-.. _`example in Android`: https://android-review.googlesource.com/c/platform/frameworks/base/+/803717
-
Because it requires a dedicated register, the ShadowCallStack feature is
-incompatible with any other feature that may use ``SCSReg``. However, there is
+incompatible with any other feature that may use `SCSReg`. However, there is
no inherent reason why ShadowCallStack needs to use a specific register; in
principle, a platform could choose to reserve and use another register for
ShadowCallStack, but this would be incompatible with the ABI standards
@@ -86,31 +73,26 @@ published in AAPCS64 and the RISC-V psABI.
Special unwind information is required on functions that are compiled
with ShadowCallStack and that may be unwound, i.e. functions compiled with
-``-fexceptions`` (which is the default in C++). Some unwinders (such as the
+`-fexceptions` (which is the default in C++). Some unwinders (such as the
libgcc 4.9 unwinder) do not understand this unwind info and will segfault
when encountering it. LLVM libunwind processes this unwind info correctly,
however. This means that if exceptions are used together with ShadowCallStack,
the program must use a compatible unwinder.
-Security
-========
+## Security
ShadowCallStack is intended to be a stronger alternative to
-``-fstack-protector``. It protects from non-linear overflows and arbitrary
+`-fstack-protector`. It protects from non-linear overflows and arbitrary
memory writes to the return address slot.
-The instrumentation makes use of the ``SCSReg`` register to reference the shadow
+The instrumentation makes use of the `SCSReg` register to reference the shadow
call stack, meaning that references to the shadow call stack do not have
to be stored in memory. This makes it possible to implement a runtime that
avoids exposing the address of the shadow call stack to attackers that can
read arbitrary memory. However, attackers could still try to exploit side
-channels exposed by the operating system `[1]`_ `[2]`_ or processor `[3]`_
+channels exposed by the operating system [[1]] [[2]] or processor [[3]]
to discover the address of the shadow call stack.
-.. _`[1]`: https://eyalitkin.wordpress.com/2017/09/01/cartography-lighting-up-the-shadows/
-.. _`[2]`: https://www.blackhat.com/docs/eu-16/materials/eu-16-Goktas-Bypassing-Clangs-SafeStack.pdf
-.. _`[3]`: https://www.vusec.net/projects/anc/
-
Unless care is taken when allocating the shadow call stack, it may be
possible for an attacker to guess its address using the addresses of
other allocations. Therefore, the address should be chosen to make this
@@ -118,21 +100,18 @@ difficult. One way to do this is to allocate a large guard region without
read/write permissions, randomly select a small region within it to be
used as the address of the shadow call stack and mark only that region as
read/write. This also mitigates somewhat against processor side channels.
-The intent is that the Android runtime `will do this`_, but the platform will
-first need to be `changed`_ to avoid using ``setrlimit(RLIMIT_AS)`` to limit
+The intent is that the Android runtime [will do this], but the platform will
+first need to be [changed] to avoid using `setrlimit(RLIMIT_AS)` to limit
memory allocations in certain processes, as this also limits the number of
guard regions that can be allocated.
-.. _`will do this`: https://android-review.googlesource.com/c/platform/bionic/+/891622
-.. _`changed`: https://android-review.googlesource.com/c/platform/frameworks/av/+/837745
-
The runtime will need the address of the shadow call stack in order to
deallocate it when destroying the thread. If the entire program is compiled
-with ``SCSReg`` reserved, this is trivial: the address can be derived from the
-value stored in ``SCSReg`` (e.g. by masking out the lower bits). If a guard
+with `SCSReg` reserved, this is trivial: the address can be derived from the
+value stored in `SCSReg` (e.g. by masking out the lower bits). If a guard
region is used, the address of the start of the guard region could then be
stored at the start of the shadow call stack itself. But if it is possible
-for code compiled without reserving ``SCSReg`` to run on a thread managed by the
+for code compiled without reserving `SCSReg` to run on a thread managed by the
runtime, which is the case on Android for example, the address must be stored
somewhere else instead. On Android we store the address of the start of the
guard region in TLS and deallocate the entire guard region including the
@@ -140,86 +119,93 @@ shadow call stack at thread exit. This is considered acceptable given that
the address of the start of the guard region is already somewhat guessable.
One way in which the address of the shadow call stack could leak is in the
-``jmp_buf`` data structure used by ``setjmp`` and ``longjmp``. The Android
-runtime `avoids this`_ by only storing the low bits of ``SCSReg`` in the
-``jmp_buf``, which requires the address of the shadow call stack to be
+`jmp_buf` data structure used by `setjmp` and `longjmp`. The Android
+runtime [avoids this] by only storing the low bits of `SCSReg` in the
+`jmp_buf`, which requires the address of the shadow call stack to be
aligned to its size.
-.. _`avoids this`: https://android.googlesource.com/platform/bionic/+/808d176e7e0dd727c7f929622ec017f6e065c582/libc/arch-arm64/bionic/setjmp.S#49
-
-The architecture's call and return instructions (``bl`` and ``ret``) operate on
+The architecture's call and return instructions (`bl` and `ret`) operate on
a register rather than the stack, which means that leaf functions are generally
protected from return address overwrites even without ShadowCallStack.
-Usage
-=====
+## Usage
-To enable ShadowCallStack, just pass the ``-fsanitize=shadow-call-stack`` flag
+To enable ShadowCallStack, just pass the `-fsanitize=shadow-call-stack` flag
to both compile and link command lines. On aarch64, you also need to pass
-``-ffixed-x18`` unless your target already reserves ``x18``. No additional flags
+`-ffixed-x18` unless your target already reserves `x18`. No additional flags
need to be passed on RISC-V because the software based shadow stack uses
-``x3`` (``gp``), which is always reserved, and the hardware based shadow call
-stack uses a dedicated register, ``ssp``.
+`x3` (`gp`), which is always reserved, and the hardware based shadow call
+stack uses a dedicated register, `ssp`.
However, it is important to disable GP relaxation in the linker when using the
software based shadow call stack on RISC-V. This can be done with the
-``--no-relax-gp`` flag in GNU ld, and is off by default in LLD.
+`--no-relax-gp` flag in GNU ld, and is off by default in LLD.
-Low-level API
--------------
+### Low-level API
-``__has_feature(shadow_call_stack)``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+#### `__has_feature(shadow_call_stack)`
In some cases one may need to execute different code depending on whether
-ShadowCallStack is enabled. The macro ``__has_feature(shadow_call_stack)`` can
+ShadowCallStack is enabled. The macro `__has_feature(shadow_call_stack)` can
be used for this purpose.
-.. code-block:: c
-
- #if defined(__has_feature)
- # if __has_feature(shadow_call_stack)
- // code that builds only under ShadowCallStack
- # endif
- #endif
+```c
+#if defined(__has_feature)
+# if __has_feature(shadow_call_stack)
+// code that builds only under ShadowCallStack
+# endif
+#endif
+```
-``__attribute__((no_sanitize("shadow-call-stack")))``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+#### `__attribute__((no_sanitize("shadow-call-stack")))`
-Use ``__attribute__((no_sanitize("shadow-call-stack")))`` on a function
+Use `__attribute__((no_sanitize("shadow-call-stack")))` on a function
declaration to specify that the shadow call stack instrumentation should not be
applied to that function, even if enabled globally.
-Example
-=======
+## Example
The following example code:
-.. code-block:: c++
-
- int foo() {
- return bar() + 1;
- }
-
-Generates the following aarch64 assembly when compiled with ``-O2``:
-
-.. code-block:: none
-
- stp x29, x30, [sp, #-16]!
- mov x29, sp
- bl bar
- add w0, w0, #1
- ldp x29, x30, [sp], #16
- ret
-
-Adding ``-fsanitize=shadow-call-stack`` would output the following assembly:
-
-.. code-block:: none
+```c++
+int foo() {
+ return bar() + 1;
+}
+```
+
+Generates the following aarch64 assembly when compiled with `-O2`:
+
+```none
+stp x29, x30, [sp, #-16]!
+mov x29, sp
+bl bar
+add w0, w0, #1
+ldp x29, x30, [sp], #16
+ret
+```
+
+Adding `-fsanitize=shadow-call-stack` would output the following assembly:
+
+```none
+str x30, [x18], #8
+stp x29, x30, [sp, #-16]!
+mov x29, sp
+bl bar
+add w0, w0, #1
+ldp x29, x30, [sp], #16
+ldr x30, [x18, #-8]!
+ret
+```
+
+[[1]]: https://eyalitkin.wordpress.com/2017/09/01/cartography-lighting-up-the-shadows/
+[[2]]: https://www.blackhat.com/docs/eu-16/materials/eu-16-Goktas-Bypassing-Clangs-SafeStack.pdf
+[[3]]: https://www.vusec.net/projects/anc/
+[avoids this]: https://android.googlesource.com/platform/bionic/+/808d176e7e0dd727c7f929622ec017f6e065c582/libc/arch-arm64/bionic/setjmp.S#49
+[changed]: https://android-review.googlesource.com/c/platform/frameworks/av/+/837745
+[clang 7.0.1 documentation]: https://releases.llvm.org/7.0.1/tools/clang/docs/ShadowCallStack.html
+[control-flow enforcement technology]: https://software.intel.com/sites/default/files/managed/4d/2a/control-flow-enforcement-technology-preview.pdf
+[example in android]: https://android-review.googlesource.com/c/platform/frameworks/base/+/803717
+[implementation of the runtime]: https://android.googlesource.com/platform/bionic/+/808d176e7e0dd727c7f929622ec017f6e065c582/libc/bionic/pthread_create.cpp#128
+[return flow guard]: https://xlab.tencent.com/en/2016/11/02/return-flow-guard/
+[will do this]: https://android-review.googlesource.com/c/platform/bionic/+/891622
+[zicfiss]: https://github.com/riscv/riscv-cfi/blob/main/cfi_backward.adoc
- str x30, [x18], #8
- stp x29, x30, [sp, #-16]!
- mov x29, sp
- bl bar
- add w0, w0, #1
- ldp x29, x30, [sp], #16
- ldr x30, [x18, #-8]!
- ret
diff --git a/clang/docs/SourceBasedCodeCoverage.md b/clang/docs/SourceBasedCodeCoverage.md
index 395f2bcc85ef0..4853149711fee 100644
--- a/clang/docs/SourceBasedCodeCoverage.md
+++ b/clang/docs/SourceBasedCodeCoverage.md
@@ -1,12 +1,10 @@
-==========================
-Source-based Code Coverage
-==========================
+# Source-based Code Coverage
-.. contents::
- :local:
+```{contents}
+:local: true
+```
-Introduction
-============
+## Introduction
This document explains how to use clang's source-based code coverage feature.
It's called "source-based" because it operates on AST and preprocessor
@@ -14,92 +12,81 @@ information directly. This allows it to generate very precise coverage data.
Clang ships two other code coverage implementations:
-* :doc:`SanitizerCoverage` - A low-overhead tool meant for use alongside the
+- {doc}`SanitizerCoverage` - A low-overhead tool meant for use alongside the
various sanitizers. It can provide up to edge-level coverage.
-
-* gcov - A GCC-compatible coverage implementation which operates on DebugInfo.
- This is enabled by ``-ftest-coverage`` or ``--coverage``.
+- gcov - A GCC-compatible coverage implementation which operates on DebugInfo.
+ This is enabled by `-ftest-coverage` or `--coverage`.
From this point onwards "code coverage" will refer to the source-based kind.
-The code coverage workflow
-==========================
+## The code coverage workflow
The code coverage workflow consists of three main steps:
-* Compiling with coverage enabled.
-
-* Running the instrumented program.
-
-* Creating coverage reports.
+- Compiling with coverage enabled.
+- Running the instrumented program.
+- Creating coverage reports.
The next few sections work through a complete, copy-'n-paste friendly example
based on this program:
-.. code-block:: cpp
-
- % cat <<EOF > foo.cc
- #define BAR(x) ((x) || (x))
- template <typename T> void foo(T x) {
- for (unsigned I = 0; I < 10; ++I) { BAR(I); }
- }
- int main() {
- foo<int>(0);
- foo<float>(0);
- return 0;
- }
- EOF
-
-Compiling with coverage enabled
-===============================
-
-To compile code with coverage enabled, pass ``-fprofile-instr-generate
--fcoverage-mapping`` to the compiler:
-
-.. code-block:: console
-
- # Step 1: Compile with coverage enabled.
- % clang++ -fprofile-instr-generate -fcoverage-mapping foo.cc -o foo
+```cpp
+% cat <<EOF > foo.cc
+#define BAR(x) ((x) || (x))
+template <typename T> void foo(T x) {
+ for (unsigned I = 0; I < 10; ++I) { BAR(I); }
+}
+int main() {
+ foo<int>(0);
+ foo<float>(0);
+ return 0;
+}
+EOF
+```
+
+## Compiling with coverage enabled
+
+To compile code with coverage enabled, pass `-fprofile-instr-generate
+-fcoverage-mapping` to the compiler:
+
+```console
+# Step 1: Compile with coverage enabled.
+% clang++ -fprofile-instr-generate -fcoverage-mapping foo.cc -o foo
+```
Note that linking together code with and without coverage instrumentation is
supported. Uninstrumented code simply won't be accounted for in reports.
To compile code with Modified Condition/Decision Coverage (MC/DC) enabled,
-pass ``-fcoverage-mcdc`` in addition to the clang options specified above.
+pass `-fcoverage-mcdc` in addition to the clang options specified above.
MC/DC is an advanced form of code coverage most applicable to the embedded
space.
-Running the instrumented program
-================================
+## Running the instrumented program
The next step is to run the instrumented program. When the program exits, it
-will write a **raw profile** to the path specified by the ``LLVM_PROFILE_FILE``
+will write a **raw profile** to the path specified by the `LLVM_PROFILE_FILE`
environment variable. If that variable does not exist, the profile is written
-to ``default.profraw`` in the current directory of the program. If
-``LLVM_PROFILE_FILE`` specifies a path to a non-existent directory, the missing
-directory structure will be created. Additionally, the following special
+to `default.profraw` in the current directory of the program. If
+`LLVM_PROFILE_FILE` specifies a path to a non-existent directory, the missing
+directory structure will be created. Additionally, the following special
**pattern strings** are rewritten:
-* "%p" expands out to the process ID.
-
-* "%h" expands out to the hostname of the machine running the program.
-
-* "%t" expands out to the value of the ``TMPDIR`` environment variable. On
+- "%p" expands out to the process ID.
+- "%h" expands out to the hostname of the machine running the program.
+- "%t" expands out to the value of the `TMPDIR` environment variable. On
Darwin, this is typically set to a temporary scratch directory.
-
-* "%Nm" expands out to the instrumented binary's signature. When this pattern
+- "%Nm" expands out to the instrumented binary's signature. When this pattern
is specified, the runtime creates a pool of N raw profiles which are used for
on-line profile merging. The runtime takes care of selecting a raw profile
- from the pool, locking it, and updating it before the program exits. If N is
- not specified (i.e the pattern is "%m"), it's assumed that ``N = 1``. The
+ from the pool, locking it, and updating it before the program exits. If N is
+ not specified (i.e the pattern is "%m"), it's assumed that `N = 1`. The
merge pool specifier can only occur once per filename pattern.
-
-* "%b" expands out to the binary ID (build ID). It can be used with "%Nm" to
+- "%b" expands out to the binary ID (build ID). It can be used with "%Nm" to
avoid binary signature collisions. To use it, the program should be compiled
- with the build ID linker option (``--build-id`` for GNU ld or LLD,
- ``/build-id`` for lld-link on Windows). Linux, Windows, and AIX are supported.
-
-* "%c" expands out to nothing, but enables a mode in which profile counter
+ with the build ID linker option (`--build-id` for GNU ld or LLD,
+ `/build-id` for lld-link on Windows). Linux, Windows, and AIX are supported.
+- "%c" expands out to nothing, but enables a mode in which profile counter
updates are continuously synced to a file. This means that if the
instrumented program crashes, or is killed by a signal, perfect coverage
information can still be recovered. Continuous mode does not support value
@@ -108,10 +95,10 @@ directory structure will be created. Additionally, the following special
may require more extensive changes: please get involved if you are interested
in porting this feature.
-.. code-block:: console
-
- # Step 2: Run the program.
- % LLVM_PROFILE_FILE="foo.profraw" ./foo
+```console
+# Step 2: Run the program.
+% LLVM_PROFILE_FILE="foo.profraw" ./foo
+```
Note that continuous mode is also used on Fuchsia where it's the only supported
mode, but the implementation is different. The Darwin and Linux implementation
@@ -121,7 +108,7 @@ for other platforms.
On Fuchsia, we rely on the ability to relocate counters at runtime using a
level of indirection. On every counter access, we add a bias to the counter
-address. This bias is stored in ``__llvm_profile_counter_bias`` symbol that's
+address. This bias is stored in `__llvm_profile_counter_bias` symbol that's
provided by the profile runtime and is initially set to zero, meaning no
relocation. The runtime can map the profile into memory at arbitrary locations,
and set bias to the offset between the original and the new counter location,
@@ -133,176 +120,172 @@ The disadvantage is the extra overhead due to additional instructions required
for each counter access (overhead both in terms of binary size and performance)
plus duplication of counters (i.e. one copy in the binary itself and another
copy that's mapped into memory). This implementation can be also enabled for
-other platforms by passing the ``-runtime-counter-relocation`` option to the
+other platforms by passing the `-runtime-counter-relocation` option to the
backend during compilation.
-For a program such as the `Lit <https://llvm.org/docs/CommandGuide/lit.html>`_
+For a program such as the [Lit](https://llvm.org/docs/CommandGuide/lit.html)
testing tool, which invokes other programs, it may be necessary to set
-``LLVM_PROFILE_FILE`` for each invocation. The pattern strings "%p" or "%Nm"
+`LLVM_PROFILE_FILE` for each invocation. The pattern strings "%p" or "%Nm"
may help to avoid corruption due to concurrency. Note that "%p" is also a Lit
token and needs to be escaped as "%%p".
-.. code-block:: console
-
- % clang++ -fprofile-instr-generate -fcoverage-mapping -mllvm -runtime-counter-relocation foo.cc -o foo
+```console
+% clang++ -fprofile-instr-generate -fcoverage-mapping -mllvm -runtime-counter-relocation foo.cc -o foo
+```
-Creating coverage reports
-=========================
+## Creating coverage reports
Raw profiles must be **indexed** before they can be used to generate
-coverage reports. This is done using the "merge" tool in ``llvm-profdata``
+coverage reports. This is done using the "merge" tool in `llvm-profdata`
(which can combine multiple raw profiles and index them at the same time):
-.. code-block:: console
-
- # Step 3(a): Index the raw profile.
- % llvm-profdata merge -sparse foo.profraw -o foo.profdata
+```console
+# Step 3(a): Index the raw profile.
+% llvm-profdata merge -sparse foo.profraw -o foo.profdata
+```
For an example of merging multiple profiles created by testing,
-see the LLVM `coverage build script <https://github.com/llvm/llvm-zorg/blob/main/zorg/jenkins/jobs/jobs/llvm-coverage>`_.
+see the LLVM [coverage build script](https://github.com/llvm/llvm-zorg/blob/main/zorg/jenkins/jobs/jobs/llvm-coverage).
There are multiple different ways to render coverage reports. The simplest
option is to generate a line-oriented report:
-.. code-block:: console
-
- # Step 3(b): Create a line-oriented coverage report.
- % llvm-cov show ./foo -instr-profile=foo.profdata
+```console
+# Step 3(b): Create a line-oriented coverage report.
+% llvm-cov show ./foo -instr-profile=foo.profdata
+```
This report includes a summary view as well as dedicated sub-views for
templated functions and their instantiations. For our example program, we get
-distinct views for ``foo<int>(...)`` and ``foo<float>(...)``. If
-``-show-line-counts-or-regions`` is enabled, ``llvm-cov`` displays sub-line
+distinct views for `foo<int>(...)` and `foo<float>(...)`. If
+`-show-line-counts-or-regions` is enabled, `llvm-cov` displays sub-line
region counts (even in macro expansions):
-.. code-block:: none
-
- 1| 20|#define BAR(x) ((x) || (x))
- ^20 ^2
- 2| 2|template <typename T> void foo(T x) {
- 3| 22| for (unsigned I = 0; I < 10; ++I) { BAR(I); }
- ^22 ^20 ^20^20
- 4| 2|}
- ------------------
- | void foo<int>(int):
- | 2| 1|template <typename T> void foo(T x) {
- | 3| 11| for (unsigned I = 0; I < 10; ++I) { BAR(I); }
- | ^11 ^10 ^10^10
- | 4| 1|}
- ------------------
- | void foo<float>(int):
- | 2| 1|template <typename T> void foo(T x) {
- | 3| 11| for (unsigned I = 0; I < 10; ++I) { BAR(I); }
- | ^11 ^10 ^10^10
- | 4| 1|}
- ------------------
-
-If ``--show-branches=count`` and ``--show-expansions`` are also enabled, the
+```none
+ 1| 20|#define BAR(x) ((x) || (x))
+ ^20 ^2
+ 2| 2|template <typename T> void foo(T x) {
+ 3| 22| for (unsigned I = 0; I < 10; ++I) { BAR(I); }
+ ^22 ^20 ^20^20
+ 4| 2|}
+------------------
+| void foo<int>(int):
+| 2| 1|template <typename T> void foo(T x) {
+| 3| 11| for (unsigned I = 0; I < 10; ++I) { BAR(I); }
+| ^11 ^10 ^10^10
+| 4| 1|}
+------------------
+| void foo<float>(int):
+| 2| 1|template <typename T> void foo(T x) {
+| 3| 11| for (unsigned I = 0; I < 10; ++I) { BAR(I); }
+| ^11 ^10 ^10^10
+| 4| 1|}
+------------------
+```
+
+If `--show-branches=count` and `--show-expansions` are also enabled, the
sub-views will show detailed branch coverage information in addition to the
region counts:
-.. code-block:: none
-
- ------------------
- | void foo<float>(int):
- | 2| 1|template <typename T> void foo(T x) {
- | 3| 11| for (unsigned I = 0; I < 10; ++I) { BAR(I); }
- | ^11 ^10 ^10^10
- | ------------------
- | | | 1| 10|#define BAR(x) ((x) || (x))
- | | | ^10 ^1
- | | | ------------------
- | | | | Branch (1:17): [True: 9, False: 1]
- | | | | Branch (1:24): [True: 0, False: 1]
- | | | ------------------
- | ------------------
- | | Branch (3:23): [True: 10, False: 1]
- | ------------------
- | 4| 1|}
- ------------------
+```none
+------------------
+| void foo<float>(int):
+| 2| 1|template <typename T> void foo(T x) {
+| 3| 11| for (unsigned I = 0; I < 10; ++I) { BAR(I); }
+| ^11 ^10 ^10^10
+| ------------------
+| | | 1| 10|#define BAR(x) ((x) || (x))
+| | | ^10 ^1
+| | | ------------------
+| | | | Branch (1:17): [True: 9, False: 1]
+| | | | Branch (1:24): [True: 0, False: 1]
+| | | ------------------
+| ------------------
+| | Branch (3:23): [True: 10, False: 1]
+| ------------------
+| 4| 1|}
+------------------
+```
If the application was instrumented for Modified Condition/Decision Coverage
-(MC/DC) using the clang option ``-fcoverage-mcdc``, an MC/DC subview can be
-enabled using ``--show-mcdc`` that will show detailed MC/DC information for
+(MC/DC) using the clang option `-fcoverage-mcdc`, an MC/DC subview can be
+enabled using `--show-mcdc` that will show detailed MC/DC information for
each complex condition boolean expression containing at most six conditions.
To generate a file-level summary of coverage statistics instead of a
line-oriented report, try:
-.. code-block:: console
-
- # Step 3(c): Create a coverage summary.
- % llvm-cov report ./foo -instr-profile=foo.profdata
- Filename Regions Missed Regions Cover Functions Missed Functions Executed Lines Missed Lines Cover Branches Missed Branches Cover
- --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
- /tmp/foo.cc 13 0 100.00% 3 0 100.00% 13 0 100.00% 12 2 83.33%
- --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
- TOTAL 13 0 100.00% 3 0 100.00% 13 0 100.00% 12 2 83.33%
-
-The ``llvm-cov`` tool supports specifying a custom demangler, writing out
+```console
+# Step 3(c): Create a coverage summary.
+% llvm-cov report ./foo -instr-profile=foo.profdata
+Filename Regions Missed Regions Cover Functions Missed Functions Executed Lines Missed Lines Cover Branches Missed Branches Cover
+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+/tmp/foo.cc 13 0 100.00% 3 0 100.00% 13 0 100.00% 12 2 83.33%
+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+TOTAL 13 0 100.00% 3 0 100.00% 13 0 100.00% 12 2 83.33%
+```
+
+The `llvm-cov` tool supports specifying a custom demangler, writing out
reports in a directory structure, and generating HTML reports. For the full
-list of options, please refer to the `command guide
-<https://llvm.org/docs/CommandGuide/llvm-cov.html>`_.
+list of options, please refer to the [command guide](https://llvm.org/docs/CommandGuide/llvm-cov.html).
A few final notes:
-* The ``-sparse`` flag is optional but can produce dramatically smaller
+- The `-sparse` flag is optional but can produce dramatically smaller
indexed profiles. This option should not be used if the indexed profile will
be reused for PGO.
-* Raw profiles can be discarded after they are indexed. Advanced use of the
+- Raw profiles can be discarded after they are indexed. Advanced use of the
profile runtime library allows an instrumented program to merge profiling
information directly into an existing raw profile on disk. The details are
out of scope.
-* The ``llvm-profdata`` tool can be used to merge multiple raw or
+- The `llvm-profdata` tool can be used to merge multiple raw or
indexed profiles. To combine profiling data from multiple runs of a program,
try e.g:
- .. code-block:: console
+ ```console
+ % llvm-profdata merge -sparse foo1.profraw foo2.profdata -o foo3.profdata
+ ```
- % llvm-profdata merge -sparse foo1.profraw foo2.profdata -o foo3.profdata
+## Exporting coverage data
-Exporting coverage data
-=======================
-
-Coverage data can be exported into JSON using the ``llvm-cov export``
+Coverage data can be exported into JSON using the `llvm-cov export`
sub-command. There is a comprehensive reference which defines the structure of
the exported data at a high level in the llvm-cov source code.
-Interpreting reports
-====================
+## Interpreting reports
There are six statistics tracked in a coverage summary:
-* Function coverage is the percentage of functions which have been executed at
+- Function coverage is the percentage of functions which have been executed at
least once. A function is considered to be executed if any of its
instantiations are executed.
-* Instantiation coverage is the percentage of function instantiations which
+- Instantiation coverage is the percentage of function instantiations which
have been executed at least once. Template functions and static inline
functions from headers are two kinds of functions which may have multiple
instantiations. This statistic is hidden by default in reports, but can be
- enabled via the ``-show-instantiation-summary`` option.
+ enabled via the `-show-instantiation-summary` option.
-* Line coverage is the percentage of code lines which have been executed at
+- Line coverage is the percentage of code lines which have been executed at
least once. Only executable lines within function bodies are considered to be
code lines.
-* Region coverage is the percentage of code regions which have been executed at
+- Region coverage is the percentage of code regions which have been executed at
least once. A code region may span multiple lines (e.g in a large function
body with no control flow). However, it's also possible for a single line to
contain multiple code regions (e.g in "return x || y && z").
-* Branch coverage is the percentage of "true" and "false" branches that have
+- Branch coverage is the percentage of "true" and "false" branches that have
been taken at least once. Each branch is tied to individual conditions in the
- source code that may each evaluate to either "true" or "false". These
+ source code that may each evaluate to either "true" or "false". These
conditions may comprise larger boolean expressions linked by boolean logical
operators. For example, "x = (y == 2) || (z < 10)" is a boolean expression
comprised of two individual conditions, each of which evaluates to
either true or false, producing four total branch outcomes.
-* Modified Condition/Decision Coverage (MC/DC) is the percentage of individual
+- Modified Condition/Decision Coverage (MC/DC) is the percentage of individual
branch conditions that have been shown to independently affect the decision
outcome of the boolean expression they comprise. This is accomplished using
the analysis of executed control flow through the expression (i.e. test
@@ -310,13 +293,13 @@ There are six statistics tracked in a coverage summary:
false", the decision's outcome also varies between "true" and false", while
the outcome of all other conditions is held fixed (or they are masked out as
unevaluatable, as happens in languages whose logical operators have
- short-circuit semantics). MC/DC builds on top of branch coverage and
- requires that all code blocks and all execution paths have been tested. This
+ short-circuit semantics). MC/DC builds on top of branch coverage and
+ requires that all code blocks and all execution paths have been tested. This
statistic is hidden by default in reports, but it can be enabled via the
- ``-show-mcdc-summary`` option as long as code was also compiled using the
- clang option ``-fcoverage-mcdc``.
+ `-show-mcdc-summary` option as long as code was also compiled using the
+ clang option `-fcoverage-mcdc`.
- * Boolean expressions comprised of only one condition (and therefore
+ - Boolean expressions comprised of only one condition (and therefore
have no logical operators) are not included in MC/DC analysis and are
trivially deducible using branch coverage.
@@ -325,29 +308,24 @@ branch coverage (with MC/DC) is the most granular. 100% branch coverage for a
function implies 100% region coverage for a function. The project-wide totals
for each statistic are listed in the summary.
-Format compatibility guarantees
-===============================
+## Format compatibility guarantees
-* There are no backwards or forwards compatibility guarantees for the raw
+- There are no backwards or forwards compatibility guarantees for the raw
profile format. Raw profiles may be dependent on the specific compiler
revision used to generate them. It's inadvisable to store raw profiles for
long periods of time.
-
-* Tools must retain **backwards** compatibility with indexed profile formats.
+- Tools must retain **backwards** compatibility with indexed profile formats.
These formats are not forwards-compatible: i.e, a tool which uses format
version X will not be able to understand format version (X+k).
-
-* Tools must also retain **backwards** compatibility with the format of the
+- Tools must also retain **backwards** compatibility with the format of the
coverage mappings emitted into instrumented binaries. These formats are not
forwards-compatible.
-
-* The JSON coverage export format has a (major, minor, patch) version triple.
+- The JSON coverage export format has a (major, minor, patch) version triple.
Only a major version increment indicates a backwards-incompatible change. A
minor version increment is for added functionality, and patch version
increments are for bugfixes.
-Impact of llvm optimizations on coverage reports
-================================================
+## Impact of llvm optimizations on coverage reports
llvm optimizations (such as inlining or CFG simplification) should have no
impact on coverage report quality. This is due to the fact that the mapping
@@ -359,104 +337,94 @@ program emits), and so leaves it alone.
Note that this coverage feature does not rely on information that can degrade
during the course of optimization, such as debug info line tables.
-Using the profiling runtime without static initializers
-=======================================================
+## Using the profiling runtime without static initializers
By default the compiler runtime uses a static initializer to determine the
profile output path and to register a writer function. To collect profiles
without using static initializers, do this manually:
-* Export an ``int __llvm_profile_runtime`` symbol from each instrumented shared
+- Export an `int __llvm_profile_runtime` symbol from each instrumented shared
library and executable. When the linker finds a definition of this symbol, it
knows to skip loading the object which contains the profiling runtime's
static initializer.
-
-* Forward-declare ``void __llvm_profile_initialize_file(void)`` and call it
+- Forward-declare `void __llvm_profile_initialize_file(void)` and call it
once from each instrumented executable. This function parses
- ``LLVM_PROFILE_FILE``, sets the output path, and truncates any existing files
+ `LLVM_PROFILE_FILE`, sets the output path, and truncates any existing files
at that path. To get the same behavior without truncating existing files,
- pass a filename pattern string to ``void __llvm_profile_set_filename(char
- *)``. These calls can be placed anywhere so long as they precede all calls
- to ``__llvm_profile_write_file``.
-
-* Forward-declare ``int __llvm_profile_write_file(void)`` and call it to write
+ pass a filename pattern string to `void __llvm_profile_set_filename(char
+ *)`. These calls can be placed anywhere so long as they precede all calls
+ to `__llvm_profile_write_file`.
+- Forward-declare `int __llvm_profile_write_file(void)` and call it to write
out a profile. This function returns 0 on success, and a non-zero value
otherwise. Calling this function multiple times appends profile data to an
existing on-disk raw profile.
-In C++ files, declare these as ``extern "C"``.
+In C++ files, declare these as `extern "C"`.
-Using the profiling runtime without a filesystem
-------------------------------------------------
+### Using the profiling runtime without a filesystem
The profiling runtime also supports freestanding environments that lack a
filesystem. The runtime ships as a static archive that's structured to make
dependencies on a hosted environment optional, depending on what features
the client application uses.
-The first step is to export ``__llvm_profile_runtime``, as above, to disable
-the default static initializers. Instead of calling the ``*_file()`` APIs
+The first step is to export `__llvm_profile_runtime`, as above, to disable
+the default static initializers. Instead of calling the `*_file()` APIs
described above, use the following to save the profile directly to a buffer
under your control:
-* Forward-declare ``uint64_t __llvm_profile_get_size_for_buffer(void)`` and
+- Forward-declare `uint64_t __llvm_profile_get_size_for_buffer(void)` and
call it to determine the size of the profile. You'll need to allocate a
buffer of this size.
-
-* Forward-declare ``int __llvm_profile_write_buffer(char *Buffer)`` and call it
- to copy the current counters to ``Buffer``, which is expected to already be
+- Forward-declare `int __llvm_profile_write_buffer(char *Buffer)` and call it
+ to copy the current counters to `Buffer`, which is expected to already be
allocated and big enough for the profile.
-
-* Optionally, forward-declare ``void __llvm_profile_reset_counters(void)`` and
+- Optionally, forward-declare `void __llvm_profile_reset_counters(void)` and
call it to reset the counters before entering a specific section to be
profiled. This is only useful if there is some setup that should be excluded
from the profile.
-In C++ files, declare these as ``extern "C"``.
+In C++ files, declare these as `extern "C"`.
-Collecting coverage reports for the llvm project
-================================================
+## Collecting coverage reports for the llvm project
To prepare a coverage report for llvm (and any of its sub-projects), add
-``-DLLVM_BUILD_INSTRUMENTED_COVERAGE=On`` to the CMake configuration. Raw
-profiles will be written to ``$BUILD_DIR/profiles/``. To prepare an html
-report, run ``llvm/utils/prepare-code-coverage-artifact.py``.
+`-DLLVM_BUILD_INSTRUMENTED_COVERAGE=On` to the CMake configuration. Raw
+profiles will be written to `$BUILD_DIR/profiles/`. To prepare an html
+report, run `llvm/utils/prepare-code-coverage-artifact.py`.
To specify an alternate directory for raw profiles, use
-``-DLLVM_PROFILE_DATA_DIR``. To change the size of the profile merge pool, use
-``-DLLVM_PROFILE_MERGE_POOL_SIZE``.
+`-DLLVM_PROFILE_DATA_DIR`. To change the size of the profile merge pool, use
+`-DLLVM_PROFILE_MERGE_POOL_SIZE`.
-Drawbacks and limitations
-=========================
+## Drawbacks and limitations
-* Prior to version 2.26, the GNU binutils BFD linker cannot link programs
- compiled with ``-fcoverage-mapping`` in its ``--gc-sections`` mode. Possible
- workarounds include disabling ``--gc-sections``, upgrading to a newer version
+- Prior to version 2.26, the GNU binutils BFD linker cannot link programs
+ compiled with `-fcoverage-mapping` in its `--gc-sections` mode. Possible
+ workarounds include disabling `--gc-sections`, upgrading to a newer version
of BFD, or using the Gold linker.
-* Code coverage does not handle unpredictable changes in control flow or stack
+- Code coverage does not handle unpredictable changes in control flow or stack
unwinding in the presence of exceptions precisely. Consider the following
function:
- .. code-block:: cpp
+ ```cpp
+ int f() {
+ may_throw();
+ return 0;
+ }
+ ```
- int f() {
- may_throw();
- return 0;
- }
+ If the call to `may_throw()` propagates an exception into `f`, the code
+ coverage tool may mark the `return` statement as executed even though it is
+ not. A call to `longjmp()` can have similar effects.
- If the call to ``may_throw()`` propagates an exception into ``f``, the code
- coverage tool may mark the ``return`` statement as executed even though it is
- not. A call to ``longjmp()`` can have similar effects.
-
-Clang implementation details
-============================
+## Clang implementation details
This section may be of interest to those wishing to understand or improve
the clang code coverage implementation.
-Gap regions
------------
+### Gap regions
Gap regions are source regions with counts. A reporting tool cannot set a line
execution count to the count from a gap region unless that region is the only
@@ -467,56 +435,54 @@ as red "unexecuted" highlights present at the end of an otherwise covered line,
or blue "executed" highlights present at the start of a line that is otherwise
not executed.
-Branch regions
---------------
+### Branch regions
+
When viewing branch coverage details in source-based file-level sub-views using
-``--show-branches``, it is recommended that users show all macro expansions
-(using option ``--show-expansions``) since macros may contain hidden branch
-conditions. The coverage summary report will always include these macro-based
+`--show-branches`, it is recommended that users show all macro expansions
+(using option `--show-expansions`) since macros may contain hidden branch
+conditions. The coverage summary report will always include these macro-based
boolean expressions in the overall branch coverage count for a function or
source file.
Branch coverage is not tracked for constant folded branch conditions since
-branches are not generated for these cases. In the source-based file-level
-sub-view, these branches will simply be shown as ``[Folded - Ignored]`` so that
+branches are not generated for these cases. In the source-based file-level
+sub-view, these branches will simply be shown as `[Folded - Ignored]` so that
users are informed about what happened.
Branch coverage is tied directly to branch-generating conditions in the source
-code. Users should not see hidden branches that aren't actually tied to the
+code. Users should not see hidden branches that aren't actually tied to the
source code.
-MC/DC Instrumentation
----------------------
+### MC/DC Instrumentation
When instrumenting for Modified Condition/Decision Coverage (MC/DC) using the
-clang option ``-fcoverage-mcdc``, there are two hard limits.
+clang option `-fcoverage-mcdc`, there are two hard limits.
The maximum number of terms is limited to 32767, which is practical for
handwritten expressions. To be more restrictive in order to enforce coding rules,
-use ``-Xclang -fmcdc-max-conditions=n``. Expressions with exceeded condition
-counts ``n`` will generate warnings and will be excluded in the MC/DC coverage.
+use `-Xclang -fmcdc-max-conditions=n`. Expressions with exceeded condition
+counts `n` will generate warnings and will be excluded in the MC/DC coverage.
The number of test vectors (the maximum number of possible combinations of
expressions) is limited to 2,147,483,646. In this case, approximately
256MiB (==2GiB/8) is used to record test vectors.
To reduce memory usage, users can limit the maximum number of test vectors per
-expression with ``-Xclang -fmcdc-max-test-vectors=m``.
+expression with `-Xclang -fmcdc-max-test-vectors=m`.
If the number of test vectors resulting from the analysis of an expression
-exceeds ``m``, a warning will be issued and the expression will be excluded
+exceeds `m`, a warning will be issued and the expression will be excluded
from the MC/DC coverage.
-The number of test vectors ``m``, for ``n`` terms in an expression, can be
-``m <= 2^n`` in the theoretical worst case, but is usually much smaller.
+The number of test vectors `m`, for `n` terms in an expression, can be
+`m <= 2^n` in the theoretical worst case, but is usually much smaller.
In simple cases, such as expressions consisting of a sequence of single
-operators, ``m == n+1``. For example, ``(a && b && c && d && e && f && g)``
+operators, `m == n+1`. For example, `(a && b && c && d && e && f && g)`
requires 8 test vectors.
-Expressions such as ``((a0 && b0) || (a1 && b1) || ...)`` can cause the
+Expressions such as `((a0 && b0) || (a1 && b1) || ...)` can cause the
number of test vectors to increase exponentially.
-Switch statements
------------------
+### Switch statements
The region mapping for a switch body consists of a gap region that covers the
entire body (starting from the '{' in 'switch (...) {', and terminating where the
@@ -525,15 +491,16 @@ between case statements, which contain no executable code, to appear uncovered.
When a switch case is visited, the parent region is extended: if the parent
region has no start location, its start location becomes the start of the case.
-This is used to support switch statements without a ``CompoundStmt`` body, in
+This is used to support switch statements without a `CompoundStmt` body, in
which the switch body and the single case share a count.
-For switches with ``CompoundStmt`` bodies, a new region is created at the start
+For switches with `CompoundStmt` bodies, a new region is created at the start
of each switch case.
Branch regions are also generated for each switch case, including the default
case. If there is no explicitly defined default case in the source code, a
branch region is generated to correspond to the implicit default case that is
-generated by the compiler. The implicit branch region is tied to the line and
+generated by the compiler. The implicit branch region is tied to the line and
column number of the switch statement condition since no source code for the
implicit case exists.
+
diff --git a/clang/docs/StandardCPlusPlusModules.md b/clang/docs/StandardCPlusPlusModules.md
index ec9c4a27a786b..6997ec3ced24e 100644
--- a/clang/docs/StandardCPlusPlusModules.md
+++ b/clang/docs/StandardCPlusPlusModules.md
@@ -1,376 +1,358 @@
-====================
-Standard C++ Modules
-====================
+# Standard C++ Modules
-.. contents::
- :local:
+```{contents}
+:local: true
+```
-Introduction
-============
+## Introduction
-The term ``module`` is ambiguous, as it is used to mean multiple things in
-Clang. For Clang users, a module may refer to an ``Objective-C Module``,
-`Clang Module <Modules.html>`_ (also called a ``Clang Header Module``) or a
-``C++20 Module`` (or a ``Standard C++ Module``). The implementation of all
+The term `module` is ambiguous, as it is used to mean multiple things in
+Clang. For Clang users, a module may refer to an `Objective-C Module`,
+[Clang Module](Modules.html) (also called a `Clang Header Module`) or a
+`C++20 Module` (or a `Standard C++ Module`). The implementation of all
these kinds of modules in Clang shares a lot of code, but from the perspective
of users their semantics and command line interfaces are very different. This
document is an introduction to the use of C++20 modules in Clang. In the
-remainder of this document, the term ``module`` will refer to Standard C++20
-modules and the term ``Clang module`` will refer to the Clang Modules
+remainder of this document, the term `module` will refer to Standard C++20
+modules and the term `Clang module` will refer to the Clang Modules
extension.
In terms of the C++ Standard, modules consist of two components: "Named
Modules" or "Header Units". This document covers both.
-Standard C++ Named modules
-==========================
+## Standard C++ Named modules
In order to better understand the compiler's behavior, it is helpful to
understand some terms and definitions for readers who are not familiar with the
C++ feature. This document is not a tutorial on C++; it only introduces
necessary concepts to better understand use of modules in a project. Other
-resources at `Wikipedia <https://en.wikipedia.org/wiki/Modules_(C++)>`_ and
-`cppreference <https://en.cppreference.com/w/cpp/language/modules.html>`_ can
+resources at [Wikipedia](<https://en.wikipedia.org/wiki/Modules_(C++)>) and
+[cppreference](https://en.cppreference.com/w/cpp/language/modules.html) can
provide more background information about modules if needed.
-Background and terminology
---------------------------
+### Background and terminology
-Module and module unit
-~~~~~~~~~~~~~~~~~~~~~~
+#### Module and module unit
A module consists of one or more module units. A module unit is a special kind
of translation unit. A module unit should almost always start with a module
declaration. The syntax of the module declaration is:
-.. code-block:: c++
+```c++
+[export] module module_name[:partition_name];
+```
- [export] module module_name[:partition_name];
-
-Terms enclosed in ``[]`` are optional. ``module_name`` and ``partition_name``
+Terms enclosed in `[]` are optional. `module_name` and `partition_name`
follow the rules for a C++ identifier, except that they may contain one or more
-period (``.``) characters. Note that a ``.`` in the name has no semantic
+period (`.`) characters. Note that a `.` in the name has no semantic
meaning and does not imply any hierarchy.
In this document, module units are classified as:
-* Primary module interface unit
-* Module implementation unit
-* Module partition interface unit
-* Internal module partition unit
+- Primary module interface unit
+- Module implementation unit
+- Module partition interface unit
+- Internal module partition unit
A primary module interface unit is a module unit whose module declaration is
-``export module module_name;`` where ``module_name`` denotes the name of the
+`export module module_name;` where `module_name` denotes the name of the
module. A module should have one and only one primary module interface unit.
A module implementation unit is a module unit whose module declaration is
-``module module_name;``. Multiple module implementation units can be declared
+`module module_name;`. Multiple module implementation units can be declared
in the same module.
A module partition interface unit is a module unit whose module declaration is
-``export module module_name:partition_name;``. The ``partition_name`` should be
+`export module module_name:partition_name;`. The `partition_name` should be
unique within any given module.
An internal module partition unit is a module unit whose module
-declaration is ``module module_name:partition_name;``. The ``partition_name``
+declaration is `module module_name:partition_name;`. The `partition_name`
should be unique within any given module.
In this document, we use the following terms:
-* A ``module interface unit`` refers to either a ``primary module interface unit``
- or a ``module partition interface unit``.
-
-* An ``importable module unit`` refers to either a ``module interface unit`` or
- an ``internal module partition unit``.
-
-* A ``module partition unit`` refers to either a ``module partition interface unit``
- or an ``internal module partition unit``.
+- A `module interface unit` refers to either a `primary module interface unit`
+ or a `module partition interface unit`.
+- An `importable module unit` refers to either a `module interface unit` or
+ an `internal module partition unit`.
+- A `module partition unit` refers to either a `module partition interface unit`
+ or an `internal module partition unit`.
-Built Module Interface
-~~~~~~~~~~~~~~~~~~~~~~
+#### Built Module Interface
-A ``Built Module Interface`` (or ``BMI``) is the precompiled result of an
+A `Built Module Interface` (or `BMI`) is the precompiled result of an
importable module unit.
-Global module fragment
-~~~~~~~~~~~~~~~~~~~~~~
+#### Global module fragment
-The ``global module fragment`` (or ``GMF``) is the code between the ``module;``
+The `global module fragment` (or `GMF`) is the code between the `module;`
and the module declaration within a module unit.
+### How to build projects using modules
-How to build projects using modules
------------------------------------
-
-Quick Start
-~~~~~~~~~~~
+#### Quick Start
Let's see a "hello world" example that uses modules.
-.. code-block:: c++
-
- // Hello.cppm
- module;
- #include <iostream>
- export module Hello;
- export void hello() {
- std::cout << "Hello World!\n";
- }
-
- // use.cpp
- import Hello;
- int main() {
- hello();
- return 0;
- }
+```c++
+// Hello.cppm
+module;
+#include <iostream>
+export module Hello;
+export void hello() {
+ std::cout << "Hello World!\n";
+}
+
+// use.cpp
+import Hello;
+int main() {
+ hello();
+ return 0;
+}
+```
Then, on the command line, invoke Clang like:
-.. code-block:: console
-
- $ clang++ -std=c++20 Hello.cppm --precompile -o Hello.pcm
- $ clang++ -std=c++20 use.cpp -fmodule-file=Hello=Hello.pcm Hello.pcm -o Hello.out
- $ ./Hello.out
- Hello World!
+```console
+$ clang++ -std=c++20 Hello.cppm --precompile -o Hello.pcm
+$ clang++ -std=c++20 use.cpp -fmodule-file=Hello=Hello.pcm Hello.pcm -o Hello.out
+$ ./Hello.out
+Hello World!
+```
-In this example, we make and use a simple module ``Hello`` which contains only a
-primary module interface unit named ``Hello.cppm``.
+In this example, we make and use a simple module `Hello` which contains only a
+primary module interface unit named `Hello.cppm`.
A more complex "hello world" example which uses the 4 kinds of module units is:
-.. code-block:: c++
-
- // M.cppm
- export module M;
- export import :interface_part;
- import :impl_part;
- export void Hello();
-
- // interface_part.cppm
- export module M:interface_part;
- export void World();
-
- // impl_part.cppm
- module;
- #include <iostream>
- #include <string>
- module M:impl_part;
- import :interface_part;
-
- std::string W = "World.";
- void World() {
- std::cout << W << std::endl;
- }
-
- // Impl.cpp
- module;
- #include <iostream>
- module M;
- void Hello() {
- std::cout << "Hello ";
- }
-
- // User.cpp
- import M;
- int main() {
- Hello();
- World();
- return 0;
- }
+```c++
+// M.cppm
+export module M;
+export import :interface_part;
+import :impl_part;
+export void Hello();
+
+// interface_part.cppm
+export module M:interface_part;
+export void World();
+
+// impl_part.cppm
+module;
+#include <iostream>
+#include <string>
+module M:impl_part;
+import :interface_part;
+
+std::string W = "World.";
+void World() {
+ std::cout << W << std::endl;
+}
+
+// Impl.cpp
+module;
+#include <iostream>
+module M;
+void Hello() {
+ std::cout << "Hello ";
+}
+
+// User.cpp
+import M;
+int main() {
+ Hello();
+ World();
+ return 0;
+}
+```
Then, back on the command line, invoke Clang with:
-.. code-block:: console
-
- # Precompiling the module
- $ clang++ -std=c++20 interface_part.cppm --precompile -o M-interface_part.pcm
- $ clang++ -std=c++20 impl_part.cppm --precompile -fprebuilt-module-path=. -o M-impl_part.pcm
- $ clang++ -std=c++20 M.cppm --precompile -fprebuilt-module-path=. -o M.pcm
- $ clang++ -std=c++20 Impl.cpp -fprebuilt-module-path=. -c -o Impl.o
+```console
+# Precompiling the module
+$ clang++ -std=c++20 interface_part.cppm --precompile -o M-interface_part.pcm
+$ clang++ -std=c++20 impl_part.cppm --precompile -fprebuilt-module-path=. -o M-impl_part.pcm
+$ clang++ -std=c++20 M.cppm --precompile -fprebuilt-module-path=. -o M.pcm
+$ clang++ -std=c++20 Impl.cpp -fprebuilt-module-path=. -c -o Impl.o
- # Compiling the user
- $ clang++ -std=c++20 User.cpp -fprebuilt-module-path=. -c -o User.o
+# Compiling the user
+$ clang++ -std=c++20 User.cpp -fprebuilt-module-path=. -c -o User.o
- # Compiling the module and linking it together
- $ clang++ -std=c++20 M-interface_part.pcm -fprebuilt-module-path=. -c -o M-interface_part.o
- $ clang++ -std=c++20 M-impl_part.pcm -fprebuilt-module-path=. -c -o M-impl_part.o
- $ clang++ -std=c++20 M.pcm -fprebuilt-module-path=. -c -o M.o
- $ clang++ User.o M-interface_part.o M-impl_part.o M.o Impl.o -o a.out
+# Compiling the module and linking it together
+$ clang++ -std=c++20 M-interface_part.pcm -fprebuilt-module-path=. -c -o M-interface_part.o
+$ clang++ -std=c++20 M-impl_part.pcm -fprebuilt-module-path=. -c -o M-impl_part.o
+$ clang++ -std=c++20 M.pcm -fprebuilt-module-path=. -c -o M.o
+$ clang++ User.o M-interface_part.o M-impl_part.o M.o Impl.o -o a.out
+```
We explain the options in the following sections.
-How to enable standard C++ modules
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+#### How to enable standard C++ modules
Standard C++ modules are enabled automatically when the language standard mode
-is ``-std=c++20`` or newer.
+is `-std=c++20` or newer.
-How to produce a BMI
-~~~~~~~~~~~~~~~~~~~~
+#### How to produce a BMI
-To generate a BMI for an importable module unit, use either the ``--precompile``,
-``--precompile-reduced-bmi``, or ``-fmodule-output`` command line options.
+To generate a BMI for an importable module unit, use either the `--precompile`,
+`--precompile-reduced-bmi`, or `-fmodule-output` command line options.
-The ``--precompile`` option generates the BMI as the output of the compilation
-with the output path specified using the ``-o`` option.
+The `--precompile` option generates the BMI as the output of the compilation
+with the output path specified using the `-o` option.
-The ``--precompile-reduced-bmi`` option generates a Reduced BMI (See the
+The `--precompile-reduced-bmi` option generates a Reduced BMI (See the
following section for the definition of Reduced BMI) as the output of
-the compilation with the output path specified using the ``-o`` option.
+the compilation with the output path specified using the `-o` option.
-The ``-fmodule-output`` option generates the BMI as a by-product of the
-compilation. If ``-fmodule-output=`` is specified, the BMI will be emitted to
-the specified location. If ``-fmodule-output`` and ``-c`` are specified, the
+The `-fmodule-output` option generates the BMI as a by-product of the
+compilation. If `-fmodule-output=` is specified, the BMI will be emitted to
+the specified location. If `-fmodule-output` and `-c` are specified, the
BMI will be emitted in the directory of the output file with the name of the
-input file with the extension ``.pcm``. Otherwise, the BMI will be emitted in
+input file with the extension `.pcm`. Otherwise, the BMI will be emitted in
the working directory with the name of the input file with the extension
-``.pcm``.
+`.pcm`.
-Generating BMIs with ``--precompile`` is referred to as two-phase compilation
+Generating BMIs with `--precompile` is referred to as two-phase compilation
because it takes two steps to compile a source file to an object file.
-Generating BMIs with ``-fmodule-output`` is called one-phase compilation. The
+Generating BMIs with `-fmodule-output` is called one-phase compilation. The
one-phase compilation model is simpler for build systems to implement while the
two-phase compilation has the potential to compile faster due to higher
-parallelism. As an example, if there are two module units ``A`` and ``B``, and
-``B`` depends on ``A``, the one-phase compilation model needs to compile them
+parallelism. As an example, if there are two module units `A` and `B`, and
+`B` depends on `A`, the one-phase compilation model needs to compile them
serially, whereas the two-phase compilation model can be compiled as
-soon as ``A.pcm`` is available, and thus can be compiled simultaneously with the
-``A.pcm`` to ``A.o`` compilation step.
+soon as `A.pcm` is available, and thus can be compiled simultaneously with the
+`A.pcm` to `A.o` compilation step.
-File name requirements
-~~~~~~~~~~~~~~~~~~~~~~
+#### File name requirements
-By convention, ``importable module unit`` files should use ``.cppm`` (or
-``.ccm``, ``.cxxm``, or ``.c++m``) as a file extension.
-``Module implementation unit`` files should use ``.cpp`` (or ``.cc``, ``.cxx``,
-or ``.c++``) as a file extension.
+By convention, `importable module unit` files should use `.cppm` (or
+`.ccm`, `.cxxm`, or `.c++m`) as a file extension.
+`Module implementation unit` files should use `.cpp` (or `.cc`, `.cxx`,
+or `.c++`) as a file extension.
-A BMI should use ``.pcm`` as a file extension. The file name of the BMI for a
-``primary module interface unit`` should be ``module_name.pcm``. The file name
-of a BMI for a ``module partition unit`` should be
-``module_name-partition_name.pcm``.
+A BMI should use `.pcm` as a file extension. The file name of the BMI for a
+`primary module interface unit` should be `module_name.pcm`. The file name
+of a BMI for a `module partition unit` should be
+`module_name-partition_name.pcm`.
Clang may fail to build the module if different extensions are used. For
-example, if the filename of an ``importable module unit`` ends with ``.cpp``
-instead of ``.cppm``, then Clang cannot generate a BMI for the
-``importable module unit`` with the ``--precompile`` option because the
-``--precompile`` option would only run the preprocessor (``-E``). If using a
-different extension than the conventional one for an ``importable module unit``
-you can specify ``-x c++-module`` before the file. For example,
-
-.. code-block:: c++
-
- // Hello.cpp
- module;
- #include <iostream>
- export module Hello;
- export void hello() {
- std::cout << "Hello World!\n";
- }
-
- // use.cpp
- import Hello;
- int main() {
- hello();
- return 0;
- }
-
-In this example, the extension used by the ``module interface`` is ``.cpp``
-instead of ``.cppm``, so it cannot be compiled like the previous example, but
+example, if the filename of an `importable module unit` ends with `.cpp`
+instead of `.cppm`, then Clang cannot generate a BMI for the
+`importable module unit` with the `--precompile` option because the
+`--precompile` option would only run the preprocessor (`-E`). If using a
+different extension than the conventional one for an `importable module unit`
+you can specify `-x c++-module` before the file. For example,
+
+```c++
+// Hello.cpp
+module;
+#include <iostream>
+export module Hello;
+export void hello() {
+ std::cout << "Hello World!\n";
+}
+
+// use.cpp
+import Hello;
+int main() {
+ hello();
+ return 0;
+}
+```
+
+In this example, the extension used by the `module interface` is `.cpp`
+instead of `.cppm`, so it cannot be compiled like the previous example, but
it can be compiled with:
-.. code-block:: console
-
- $ clang++ -std=c++20 -x c++-module Hello.cpp --precompile -o Hello.pcm
- $ clang++ -std=c++20 use.cpp -fprebuilt-module-path=. Hello.pcm -o Hello.out
- $ ./Hello.out
- Hello World!
+```console
+$ clang++ -std=c++20 -x c++-module Hello.cpp --precompile -o Hello.pcm
+$ clang++ -std=c++20 use.cpp -fprebuilt-module-path=. Hello.pcm -o Hello.out
+$ ./Hello.out
+Hello World!
+```
-Module name requirements
-~~~~~~~~~~~~~~~~~~~~~~~~
+#### Module name requirements
-..
+%
- [module.unit]p1:
-
- All module-names either beginning with an identifier consisting of std followed by zero
- or more digits or containing a reserved identifier ([lex.name]) are reserved and shall not
- be specified in a module-declaration; no diagnostic is required. If any identifier in a reserved
- module-name is a reserved identifier, the module name is reserved for use by C++ implementations;
- otherwise it is reserved for future standardization.
+> [module.unit]p1:
+>
+> All module-names either beginning with an identifier consisting of std followed by zero
+> or more digits or containing a reserved identifier ([lex.name]) are reserved and shall not
+> be specified in a module-declaration; no diagnostic is required. If any identifier in a reserved
+> module-name is a reserved identifier, the module name is reserved for use by C++ implementations;
+> otherwise it is reserved for future standardization.
Therefore, none of the following names are valid by default:
-.. code-block:: text
-
- std
- std1
- std.foo
- __test
- // and so on ...
+```text
+std
+std1
+std.foo
+__test
+// and so on ...
+```
Using a reserved module name is strongly discouraged, but
-``-Wno-reserved-module-identifier`` can be used to suppress the warning.
+`-Wno-reserved-module-identifier` can be used to suppress the warning.
-Specifying BMI dependencies
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+#### Specifying BMI dependencies
There are 3 ways to specify a BMI dependency:
-1. ``-fprebuilt-module-path=<path/to/directory>``.
-2. ``-fmodule-file=<path/to/BMI>`` (Deprecated).
-3. ``-fmodule-file=<module-name>=<path/to/BMI>``.
+1. `-fprebuilt-module-path=<path/to/directory>`.
+2. `-fmodule-file=<path/to/BMI>` (Deprecated).
+3. `-fmodule-file=<module-name>=<path/to/BMI>`.
-The ``-fprebuilt-module-path`` option specifies the path to search for
-BMI dependencies. Multiple paths may be specified, similar to using ``-I`` to
-specify a search path for header files. When importing a module ``M``, the
-compiler looks for ``M.pcm`` in the directories specified by
-``-fprebuilt-module-path``. Similarly, when importing a partition module unit
-``M:P``, the compiler looks for ``M-P.pcm`` in the directories specified by
-``-fprebuilt-module-path``.
+The `-fprebuilt-module-path` option specifies the path to search for
+BMI dependencies. Multiple paths may be specified, similar to using `-I` to
+specify a search path for header files. When importing a module `M`, the
+compiler looks for `M.pcm` in the directories specified by
+`-fprebuilt-module-path`. Similarly, when importing a partition module unit
+`M:P`, the compiler looks for `M-P.pcm` in the directories specified by
+`-fprebuilt-module-path`.
-The ``-fmodule-file=<path/to/BMI>`` option causes the compiler to load the
-specified BMI directly. The ``-fmodule-file=<module-name>=<path/to/BMI>``
+The `-fmodule-file=<path/to/BMI>` option causes the compiler to load the
+specified BMI directly. The `-fmodule-file=<module-name>=<path/to/BMI>`
option causes the compiler to load the specified BMI for the module specified
-by ``<module-name>`` when necessary. The main difference is that
-``-fmodule-file=<path/to/BMI>`` will load the BMI eagerly, whereas
-``-fmodule-file=<module-name>=<path/to/BMI>`` will only load the BMI lazily,
-as will ``-fprebuilt-module-path``. The ``-fmodule-file=<path/to/BMI>`` option
+by `<module-name>` when necessary. The main difference is that
+`-fmodule-file=<path/to/BMI>` will load the BMI eagerly, whereas
+`-fmodule-file=<module-name>=<path/to/BMI>` will only load the BMI lazily,
+as will `-fprebuilt-module-path`. The `-fmodule-file=<path/to/BMI>` option
for named modules is deprecated and will be removed in a future version of
Clang.
When these options are specified in the same invocation of the compiler, the
-``-fmodule-file=<path/to/BMI>`` option takes precedence over
-``-fmodule-file=<module-name>=<path/to/BMI>``, which takes precedence over
-``-fprebuilt-module-path=<path/to/directory>``.
+`-fmodule-file=<path/to/BMI>` option takes precedence over
+`-fmodule-file=<module-name>=<path/to/BMI>`, which takes precedence over
+`-fprebuilt-module-path=<path/to/directory>`.
Note: all BMI dependencies must be specified explicitly, either directly or
-indirectly. See https://github.com/llvm/llvm-project/issues/62707 for details.
+indirectly. See <https://github.com/llvm/llvm-project/issues/62707> for details.
-When compiling a ``module implementation unit``, the BMI of the corresponding
-``primary module interface unit`` must be specified because a module
+When compiling a `module implementation unit`, the BMI of the corresponding
+`primary module interface unit` must be specified because a module
implementation unit implicitly imports the primary module interface unit.
- [module.unit]p8
+> [module.unit]p8
+>
+> A module-declaration that contains neither an export-keyword nor a module-partition implicitly
+> imports the primary module interface unit of the module as if by a module-import-declaration.
- A module-declaration that contains neither an export-keyword nor a module-partition implicitly
- imports the primary module interface unit of the module as if by a module-import-declaration.
-
-The ``-fprebuilt-module-path=<path/to/directory>``, ``-fmodule-file=<path/to/BMI>``,
-and ``-fmodule-file=<module-name>=<path/to/BMI>`` options may be specified
-multiple times. For example, the command line to compile ``M.cppm`` in
+The `-fprebuilt-module-path=<path/to/directory>`, `-fmodule-file=<path/to/BMI>`,
+and `-fmodule-file=<module-name>=<path/to/BMI>` options may be specified
+multiple times. For example, the command line to compile `M.cppm` in
the previous example could be rewritten as:
-.. code-block:: console
-
- $ clang++ -std=c++20 M.cppm --precompile -fmodule-file=M:interface_part=M-interface_part.pcm -fmodule-file=M:impl_part=M-impl_part.pcm -o M.pcm
+```console
+$ clang++ -std=c++20 M.cppm --precompile -fmodule-file=M:interface_part=M-interface_part.pcm -fmodule-file=M:impl_part=M-impl_part.pcm -o M.pcm
+```
-When there are multiple ``-fmodule-file=<module-name>=`` options for the same
-``<module-name>``, the last ``-fmodule-file=<module-name>=`` overrides the
-previous ``-fmodule-file=<module-name>=`` option.
+When there are multiple `-fmodule-file=<module-name>=` options for the same
+`<module-name>`, the last `-fmodule-file=<module-name>=` overrides the
+previous `-fmodule-file=<module-name>=` option.
-Remember that module units still have an object counterpart to the BMI
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+#### Remember that module units still have an object counterpart to the BMI
While module interfaces resemble traditional header files, they still require
compilation. Module units are translation units, and need to be compiled to
@@ -379,77 +361,74 @@ show.
For example, the traditional compilation processes for headers are like:
-.. code-block:: text
-
- src1.cpp -+> clang++ src1.cpp --> src1.o ---,
- hdr1.h --' +-> clang++ src1.o src2.o -> executable
- hdr2.h --, |
- src2.cpp -+> clang++ src2.cpp --> src2.o ---'
+```text
+src1.cpp -+> clang++ src1.cpp --> src1.o ---,
+hdr1.h --' +-> clang++ src1.o src2.o -> executable
+hdr2.h --, |
+src2.cpp -+> clang++ src2.cpp --> src2.o ---'
+```
And the compilation processes for module units are like:
-.. code-block:: text
-
- src1.cpp ----------------------------------------+> clang++ src1.cpp -------> src1.o -,
- (header unit) hdr1.h -> clang++ hdr1.h ... -> hdr1.pcm --' +-> clang++ src1.o mod1.o src2.o -> executable
- mod1.cppm -> clang++ mod1.cppm ... -> mod1.pcm --,--> clang++ mod1.pcm ... -> mod1.o -+
- src2.cpp ----------------------------------------+> clang++ src2.cpp -------> src2.o -'
+```text
+ src1.cpp ----------------------------------------+> clang++ src1.cpp -------> src1.o -,
+(header unit) hdr1.h -> clang++ hdr1.h ... -> hdr1.pcm --' +-> clang++ src1.o mod1.o src2.o -> executable
+ mod1.cppm -> clang++ mod1.cppm ... -> mod1.pcm --,--> clang++ mod1.pcm ... -> mod1.o -+
+ src2.cpp ----------------------------------------+> clang++ src2.cpp -------> src2.o -'
+```
As the diagrams show, we need to compile the BMI from module units to object
files and then link the object files. (However, this cannot be done for the BMI
-from header units. See the section on :ref:`header units <header-units>` for
+from header units. See the section on {ref}`header units <header-units>` for
more details.)
BMIs cannot be shipped in an archive to create a module library. Instead, the
-BMIs(``*.pcm``) are compiled into object files(``*.o``) and those object files
+BMIs(`*.pcm`) are compiled into object files(`*.o`) and those object files
are added to the archive instead.
-clang-cl
-~~~~~~~~
+#### clang-cl
-``clang-cl`` supports the same options as ``clang++`` for modules as detailed above;
-there is no need to prefix these options with ``/clang:``. Note that ``cl.exe``
+`clang-cl` supports the same options as `clang++` for modules as detailed above;
+there is no need to prefix these options with `/clang:`. Note that `cl.exe`
`options to emit/consume IFC files <https://devblogs.microsoft.com/cppblog/using-cpp-modules-in-msvc-from-the-command-line-part-1/>` are *not* supported.
-The resulting precompiled modules are also not compatible for use with ``cl.exe``.
+The resulting precompiled modules are also not compatible for use with `cl.exe`.
-We recommend that build system authors use the above-mentioned ``clang++`` options with ``clang-cl`` to build modules.
+We recommend that build system authors use the above-mentioned `clang++` options with `clang-cl` to build modules.
-Consistency Requirements
-~~~~~~~~~~~~~~~~~~~~~~~~
+#### Consistency Requirements
Modules can be viewed as a kind of cache to speed up compilation. Thus, like
other caching techniques, it is important to maintain cache consistency, which
is why Clang does very strict checking for consistency.
-Options consistency
-^^^^^^^^^^^^^^^^^^^
+##### Options consistency
Compiler options related to the language dialect for a module unit and its
non-module-unit uses need to be consistent. Consider the following example:
-.. code-block:: c++
-
- // M.cppm
- export module M;
-
- // Use.cpp
- import M;
+```c++
+// M.cppm
+export module M;
-.. code-block:: console
+// Use.cpp
+import M;
+```
- $ clang++ -std=c++20 M.cppm --precompile -o M.pcm
- $ clang++ -std=c++23 Use.cpp -fprebuilt-module-path=.
+```console
+$ clang++ -std=c++20 M.cppm --precompile -o M.pcm
+$ clang++ -std=c++23 Use.cpp -fprebuilt-module-path=.
+```
Clang rejects the example due to the inconsistent language standard modes. Not
all compiler options are language-dialect options, though. For example:
-.. code-block:: console
-
- $ clang++ -std=c++20 M.cppm --precompile -o M.pcm
- # Inconsistent optimization level.
- $ clang++ -std=c++20 -O3 Use.cpp -fprebuilt-module-path=.
- # Inconsistent debugging level.
- $ clang++ -std=c++20 -g Use.cpp -fprebuilt-module-path=.
+```console
+$ clang++ -std=c++20 M.cppm --precompile -o M.pcm
+# Inconsistent optimization level.
+$ clang++ -std=c++20 -O3 Use.cpp -fprebuilt-module-path=.
+# Inconsistent debugging level.
+$ clang++ -std=c++20 -g Use.cpp -fprebuilt-module-path=.
+```
Although the optimization and debugging levels are inconsistent, these
compilations are accepted because the compiler options do not impact the
@@ -458,49 +437,47 @@ language dialect.
Note that the compiler **currently** doesn't reject inconsistent macro
definitions (this may change in the future). For example:
-.. code-block:: console
-
- $ clang++ -std=c++20 M.cppm --precompile -o M.pcm
- # Inconsistent optimization level.
- $ clang++ -std=c++20 -O3 -DNDEBUG Use.cpp -fprebuilt-module-path=.
+```console
+$ clang++ -std=c++20 M.cppm --precompile -o M.pcm
+# Inconsistent optimization level.
+$ clang++ -std=c++20 -O3 -DNDEBUG Use.cpp -fprebuilt-module-path=.
+```
Currently, Clang accepts the above example, though it may produce surprising
-results if the debugging code depends on consistent use of ``NDEBUG`` in other
+results if the debugging code depends on consistent use of `NDEBUG` in other
translation units.
-Source Files Consistency
-^^^^^^^^^^^^^^^^^^^^^^^^
+##### Source Files Consistency
-Clang may open the input files [1]_ of a BMI during the compilation. This implies that
+Clang may open the input files [^footnote-1] of a BMI during the compilation. This implies that
when Clang consumes a BMI, all the input files need to be present in the original path
and with the original contents.
To overcome these requirements and simplify cases like distributed builds and sandboxed
-builds, users can use the ``-fmodules-embed-all-files`` flag to embed all input files
+builds, users can use the `-fmodules-embed-all-files` flag to embed all input files
into the BMI so that Clang does not need to open the corresponding file on disk.
-When the ``-fmodules-embed-all-files`` flag is enabled, Clang explicitly emits the source
+When the `-fmodules-embed-all-files` flag is enabled, Clang explicitly emits the source
code into the BMI file; the BMI file contains a sufficiently verbose
representation to reproduce the original source file.
-.. [1] Input files: The source files which took part in the compilation of the BMI.
- For example:
-
- .. code-block:: c++
+[^footnote-1]: Input files: The source files which took part in the compilation of the BMI.
+ For example:
- // M.cppm
- module;
- #include "foo.h"
- export module M;
+ ```c++
+ // M.cppm
+ module;
+ #include "foo.h"
+ export module M;
- // foo.h
- #pragma once
- #include "bar.h"
+ // foo.h
+ #pragma once
+ #include "bar.h"
+ ```
- The ``M.cppm``, ``foo.h`` and ``bar.h`` are input files for the BMI of ``M.cppm``.
+ The `M.cppm`, `foo.h` and `bar.h` are input files for the BMI of `M.cppm`.
-Object definition consistency
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+##### Object definition consistency
The C++ language requires that declarations of the same entity in different
translation units have the same definition, which is known as the One
@@ -517,48 +494,45 @@ definitions. Further, true positive ODR violations are not always reported.
To give a better user experience, improve compilation performance, and for
consistency with MSVC, ODR checking of declarations in the global module
fragment is disabled by default. These checks can be enabled by specifying
-``-Xclang -fno-skip-odr-check-in-gmf`` when compiling. If the check is enabled
+`-Xclang -fno-skip-odr-check-in-gmf` when compiling. If the check is enabled
and you encounter incorrect or missing diagnostics, please report them via the
-`community issue tracker <https://github.com/llvm/llvm-project/issues/>`_.
+[community issue tracker](https://github.com/llvm/llvm-project/issues/).
-Privacy Issue
--------------
+### Privacy Issue
BMIs are not and should not be treated as an information hiding mechanism.
They should always be assumed to contain all the information that was used to
create them, in a recoverable form.
-ABI Impacts
------------
+### ABI Impacts
This section describes the new ABI changes brought by modules. Only changes to
the Itanium C++ ABI are covered.
-Name Mangling
-~~~~~~~~~~~~~
+#### Name Mangling
The declarations in a module unit which are not in the global module fragment
have new linkage names.
For example,
-.. code-block:: c++
+```c++
+export module M;
+namespace NS {
+ export int foo();
+}
+```
- export module M;
- namespace NS {
- export int foo();
- }
-
-The linkage name of ``NS::foo()`` is ``_ZN2NSW1M3fooEv``. This couldn't be
+The linkage name of `NS::foo()` is `_ZN2NSW1M3fooEv`. This couldn't be
demangled by previous versions of the debugger or demangler. As of LLVM 15.x,
-``llvm-cxxfilt`` can be used to demangle this:
-
-.. code-block:: console
+`llvm-cxxfilt` can be used to demangle this:
- $ llvm-cxxfilt _ZN2NSW1M3fooEv
- NS::foo at M()
+```console
+$ llvm-cxxfilt _ZN2NSW1M3fooEv
+ NS::foo at M()
+```
-The result should be read as ``NS::foo()`` in module ``M``.
+The result should be read as `NS::foo()` in module `M`.
The ABI implies that something cannot be declared in a module unit and defined
in a non-module unit (or vice-versa), as this would result in linking errors.
@@ -568,17 +542,16 @@ a module unit by using a language linkage specifier because the declarations in
the language linkage specifier are attached to the global module fragment. For
example:
-.. code-block:: c++
-
- export module M;
- namespace NS {
- export extern "C++" int foo();
- }
+```c++
+export module M;
+namespace NS {
+ export extern "C++" int foo();
+}
+```
-Now the linkage name of ``NS::foo()`` will be ``_ZN2NS3fooEv``.
+Now the linkage name of `NS::foo()` will be `_ZN2NS3fooEv`.
-Module Initializers
-~~~~~~~~~~~~~~~~~~~
+#### Module Initializers
All importable module units are required to emit an initializer function to
handle the dynamic initialization of non-inline variables in the module unit.
@@ -598,8 +571,7 @@ If the imported module is known to be empty, the call to its initializer may be
omitted. Additionally, if the imported module is known to have already been
imported, the call to its initializer may be omitted.
-Reduced BMI
------------
+### Reduced BMI
To support the two-phase compilation model, Clang puts everything needed to
produce an object into the BMI. However, other consumers of the BMI generally
@@ -608,36 +580,36 @@ unnecessary dependencies for the BMI. To mitigate the problem, Clang has a
compiler option to reduce the information contained in the BMI. These two
formats are known as Full BMI and Reduced BMI, respectively.
-Users can use the ``-fmodules-reduced-bmi`` or ``--precompile-reduced-bmi``
+Users can use the `-fmodules-reduced-bmi` or `--precompile-reduced-bmi`
option to produce a Reduced BMI.
-The ``--precompile-reduced-bmi`` option will produce the reduced BMI
-to the location specified by ``-o``.
+The `--precompile-reduced-bmi` option will produce the reduced BMI
+to the location specified by `-o`.
-Note that ``--precompile`` will always generate the full BMI. So that build
+Note that `--precompile` will always generate the full BMI. So that build
system which may generate the BMI only should take care of this.
For the one-phase compilation model (CMake implements this model), with
-``-fmodules-reduced-bmi``, the generated BMI will be a Reduced
+`-fmodules-reduced-bmi`, the generated BMI will be a Reduced
BMI automatically. (The output path of the BMI is specified by
-``-fmodule-output=`` as usual with the one-phase compilation model).
+`-fmodule-output=` as usual with the one-phase compilation model).
It is also possible to produce a Reduced BMI with the two-phase compilation
-model. When ``-fmodules-reduced-bmi``, ``--precompile``, and
-``-fmodule-output=`` are specified, the generated BMI specified by ``-o`` will
-be a full BMI and the BMI specified by ``-fmodule-output=`` will be a Reduced
+model. When `-fmodules-reduced-bmi`, `--precompile`, and
+`-fmodule-output=` are specified, the generated BMI specified by `-o` will
+be a full BMI and the BMI specified by `-fmodule-output=` will be a Reduced
BMI. The dependency graph in this case would look like:
-.. code-block:: none
+```none
+module-unit.cppm --> module-unit.full.pcm -> module-unit.o
+ |
+ -> module-unit.reduced.pcm -> consumer1.cpp
+ -> consumer2.cpp
+ -> ...
+ -> consumer_n.cpp
+```
- module-unit.cppm --> module-unit.full.pcm -> module-unit.o
- |
- -> module-unit.reduced.pcm -> consumer1.cpp
- -> consumer2.cpp
- -> ...
- -> consumer_n.cpp
-
-Clang does not emit diagnostics when ``-fmodules-reduced-bmi`` is
+Clang does not emit diagnostics when `-fmodules-reduced-bmi` is
used with a non-module unit. This design permits users of the one-phase
compilation model to try using reduced BMIs without needing to modify the build
system. The two-phase compilation module requires build system support.
@@ -648,67 +620,66 @@ variables. This may not be a transparent change.
Consider the following example:
-.. code-block:: c++
-
- // foo.h
- namespace N {
- struct X {};
- int d();
- int e();
- inline int f(X, int = d()) { return e(); }
- int g(X);
- int h(X);
- }
-
- // M.cppm
- module;
- #include "foo.h"
- export module M;
- template<typename T> int use_f() {
- N::X x; // N::X, N, and :: are decl-reachable from use_f
- return f(x, 123); // N::f is decl-reachable from use_f,
- // N::e is indirectly decl-reachable from use_f
- // because it is decl-reachable from N::f, and
- // N::d is decl-reachable from use_f
- // because it is decl-reachable from N::f
- // even though it is not used in this call
- }
- template<typename T> int use_g() {
- N::X x; // N::X, N, and :: are decl-reachable from use_g
- return g((T(), x)); // N::g is not decl-reachable from use_g
- }
- template<typename T> int use_h() {
- N::X x; // N::X, N, and :: are decl-reachable from use_h
- return h((T(), x)); // N::h is not decl-reachable from use_h, but
- // N::h is decl-reachable from use_h<int>
- }
- int k = use_h<int>();
- // use_h<int> is decl-reachable from k, so
- // N::h is decl-reachable from k
-
- // M-impl.cpp
- module M;
- int a = use_f<int>(); // OK
- int b = use_g<int>(); // error: no viable function for call to g;
- // g is not decl-reachable from purview of
- // module M's interface, so is discarded
- int c = use_h<int>(); // OK
-
-In the above example, the function definition of ``N::g`` is elided from the
-Reduced BMI of ``M.cppm``. Then the use of ``use_g<int>`` in ``M-impl.cpp``
-fails to instantiate. For such issues, users can add references to ``N::g`` in
-the `module purview <https://eel.is/c++draft/module.unit#5>`_ of ``M.cppm`` to
-ensure it is reachable, e.g. ``using N::g;``.
+```c++
+// foo.h
+namespace N {
+ struct X {};
+ int d();
+ int e();
+ inline int f(X, int = d()) { return e(); }
+ int g(X);
+ int h(X);
+}
+
+// M.cppm
+module;
+#include "foo.h"
+export module M;
+template<typename T> int use_f() {
+ N::X x; // N::X, N, and :: are decl-reachable from use_f
+ return f(x, 123); // N::f is decl-reachable from use_f,
+ // N::e is indirectly decl-reachable from use_f
+ // because it is decl-reachable from N::f, and
+ // N::d is decl-reachable from use_f
+ // because it is decl-reachable from N::f
+ // even though it is not used in this call
+}
+template<typename T> int use_g() {
+ N::X x; // N::X, N, and :: are decl-reachable from use_g
+ return g((T(), x)); // N::g is not decl-reachable from use_g
+}
+template<typename T> int use_h() {
+ N::X x; // N::X, N, and :: are decl-reachable from use_h
+ return h((T(), x)); // N::h is not decl-reachable from use_h, but
+ // N::h is decl-reachable from use_h<int>
+}
+int k = use_h<int>();
+ // use_h<int> is decl-reachable from k, so
+ // N::h is decl-reachable from k
+
+// M-impl.cpp
+module M;
+int a = use_f<int>(); // OK
+int b = use_g<int>(); // error: no viable function for call to g;
+ // g is not decl-reachable from purview of
+ // module M's interface, so is discarded
+int c = use_h<int>(); // OK
+```
+
+In the above example, the function definition of `N::g` is elided from the
+Reduced BMI of `M.cppm`. Then the use of `use_g<int>` in `M-impl.cpp`
+fails to instantiate. For such issues, users can add references to `N::g` in
+the [module purview](https://eel.is/c++draft/module.unit#5) of `M.cppm` to
+ensure it is reachable, e.g. `using N::g;`.
As of Clang 22.x, the Reduced BMI is enabled by default. You may still want to
-use Full BMI with ``-fno-modules-reduced-bmi`` in the following case:
-1. Your build system uses two-phase compilation, but it hasn't adjusted the
+use Full BMI with `-fno-modules-reduced-bmi` in the following case:
+1\. Your build system uses two-phase compilation, but it hasn't adjusted the
implementation for reduced BMI.
-2. You encounter a regression with Reduced BMI that you cannot work around. Please
+2\. You encounter a regression with Reduced BMI that you cannot work around. Please
report an issue for this case.
-Experimental Non-Cascading Changes
-----------------------------------
+### Experimental Non-Cascading Changes
This section is primarily for build system vendors. For end compiler users,
if you don't want to read it all, this is helpful to reduce recompilations.
@@ -721,70 +692,70 @@ results of the compilations. We expect that there are many more opportunities
for this optimization than we currently have realized and would appreciate
feedback about missed optimization opportunities. For example,
-.. code-block:: c++
-
- // m-partA.cppm
- export module m:partA;
-
- // m-partB.cppm
- export module m:partB;
- export int getB() { return 44; }
-
- // m.cppm
- export module m;
- export import :partA;
- export import :partB;
-
- // useBOnly.cppm
- export module useBOnly;
- import m;
- export int B() {
- return getB();
- }
-
- // Use.cc
- import useBOnly;
- int get() {
- return B();
- }
+```c++
+// m-partA.cppm
+export module m:partA;
+
+// m-partB.cppm
+export module m:partB;
+export int getB() { return 44; }
+
+// m.cppm
+export module m;
+export import :partA;
+export import :partB;
+
+// useBOnly.cppm
+export module useBOnly;
+import m;
+export int B() {
+ return getB();
+}
+
+// Use.cc
+import useBOnly;
+int get() {
+ return B();
+}
+```
To compile the project (for brevity, some commands are omitted.):
-.. code-block:: console
-
- $ clang++ -std=c++20 m-partA.cppm --precompile -o m-partA.pcm
- $ clang++ -std=c++20 m-partB.cppm --precompile -o m-partB.pcm
- $ clang++ -std=c++20 m.cppm --precompile -o m.pcm -fprebuilt-module-path=.
- $ clang++ -std=c++20 useBOnly.cppm --precompile -o useBOnly.pcm -fprebuilt-module-path=.
- $ md5sum useBOnly.pcm
- 07656bf4a6908626795729295f9608da useBOnly.pcm
-
-If the interface of ``m-partA.cppm`` is changed to:
-
-.. code-block:: c++
-
- // m-partA.v1.cppm
- export module m:partA;
- export int getA() { return 43; }
-
-and the BMI for ``useBOnly`` is recompiled as in:
-
-.. code-block:: console
-
- $ clang++ -std=c++20 m-partA.cppm --precompile -o m-partA.pcm
- $ clang++ -std=c++20 m-partB.cppm --precompile -o m-partB.pcm
- $ clang++ -std=c++20 m.cppm --precompile -o m.pcm -fprebuilt-module-path=.
- $ clang++ -std=c++20 useBOnly.cppm --precompile -o useBOnly.pcm -fprebuilt-module-path=.
- $ md5sum useBOnly.pcm
- 07656bf4a6908626795729295f9608da useBOnly.pcm
-
-then the contents of ``useBOnly.pcm`` remain unchanged.
+```console
+$ clang++ -std=c++20 m-partA.cppm --precompile -o m-partA.pcm
+$ clang++ -std=c++20 m-partB.cppm --precompile -o m-partB.pcm
+$ clang++ -std=c++20 m.cppm --precompile -o m.pcm -fprebuilt-module-path=.
+$ clang++ -std=c++20 useBOnly.cppm --precompile -o useBOnly.pcm -fprebuilt-module-path=.
+$ md5sum useBOnly.pcm
+07656bf4a6908626795729295f9608da useBOnly.pcm
+```
+
+If the interface of `m-partA.cppm` is changed to:
+
+```c++
+// m-partA.v1.cppm
+export module m:partA;
+export int getA() { return 43; }
+```
+
+and the BMI for `useBOnly` is recompiled as in:
+
+```console
+$ clang++ -std=c++20 m-partA.cppm --precompile -o m-partA.pcm
+$ clang++ -std=c++20 m-partB.cppm --precompile -o m-partB.pcm
+$ clang++ -std=c++20 m.cppm --precompile -o m.pcm -fprebuilt-module-path=.
+$ clang++ -std=c++20 useBOnly.cppm --precompile -o useBOnly.pcm -fprebuilt-module-path=.
+$ md5sum useBOnly.pcm
+07656bf4a6908626795729295f9608da useBOnly.pcm
+```
+
+then the contents of `useBOnly.pcm` remain unchanged.
Consequently, if the build system only bases recompilation decisions on directly imported modules,
-it becomes possible to skip the recompilation of ``Use.cc``.
-It should be fine because the altered interfaces do not affect ``Use.cc`` in any way;
+it becomes possible to skip the recompilation of `Use.cc`.
+It should be fine because the altered interfaces do not affect `Use.cc` in any way;
the changes do not cascade.
-When ``Clang`` generates a BMI, it records the hash values of all potentially contributory BMIs
+When `Clang` generates a BMI, it records the hash values of all potentially contributory BMIs
for the BMI being produced. This ensures that build systems are not required to consider
transitively imported modules when deciding whether to recompile.
@@ -803,58 +774,55 @@ Given that there are potential compiler bugs, we recommend that build systems
support this feature as a configurable option so that users
can go back to the transitive change mode safely at any time.
-Interactions with Reduced BMI
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+#### Interactions with Reduced BMI
With reduced BMI, non-cascading changes can be more powerful. For example,
-.. code-block:: c++
-
- // A.cppm
- export module A;
- export int a() { return 44; }
-
- // B.cppm
- export module B;
- import A;
- export int b() { return a(); }
-
-.. code-block:: console
+```c++
+// A.cppm
+export module A;
+export int a() { return 44; }
- $ clang++ -std=c++20 A.cppm -c -fmodule-output=A.pcm -fmodules-reduced-bmi -o A.o
- $ clang++ -std=c++20 B.cppm -c -fmodule-output=B.pcm -fmodules-reduced-bmi -o B.o -fmodule-file=A=A.pcm
- $ md5sum B.pcm
- 6c2bd452ca32ab418bf35cd141b060b9 B.pcm
+// B.cppm
+export module B;
+import A;
+export int b() { return a(); }
+```
-And let's change the implementation for ``A.cppm`` to:
+```console
+$ clang++ -std=c++20 A.cppm -c -fmodule-output=A.pcm -fmodules-reduced-bmi -o A.o
+$ clang++ -std=c++20 B.cppm -c -fmodule-output=B.pcm -fmodules-reduced-bmi -o B.o -fmodule-file=A=A.pcm
+$ md5sum B.pcm
+6c2bd452ca32ab418bf35cd141b060b9 B.pcm
+```
-.. code-block:: c++
+And let's change the implementation for `A.cppm` to:
- export module A;
- int a_impl() { return 99; }
- export int a() { return a_impl(); }
+```c++
+export module A;
+int a_impl() { return 99; }
+export int a() { return a_impl(); }
+```
and recompile the example:
-.. code-block:: console
+```console
+$ clang++ -std=c++20 A.cppm -c -fmodule-output=A.pcm -fmodules-reduced-bmi -o A.o
+$ clang++ -std=c++20 B.cppm -c -fmodule-output=B.pcm -fmodules-reduced-bmi -o B.o -fmodule-file=A=A.pcm
+$ md5sum B.pcm
+6c2bd452ca32ab418bf35cd141b060b9 B.pcm
+```
- $ clang++ -std=c++20 A.cppm -c -fmodule-output=A.pcm -fmodules-reduced-bmi -o A.o
- $ clang++ -std=c++20 B.cppm -c -fmodule-output=B.pcm -fmodules-reduced-bmi -o B.o -fmodule-file=A=A.pcm
- $ md5sum B.pcm
- 6c2bd452ca32ab418bf35cd141b060b9 B.pcm
-
-We should find the contents of ``B.pcm`` remain the same. In this case, the build system is
-allowed to skip recompilations of TUs which solely and directly depend on module ``B``.
+We should find the contents of `B.pcm` remain the same. In this case, the build system is
+allowed to skip recompilations of TUs which solely and directly depend on module `B`.
This only happens with a reduced BMI. With reduced BMIs, we won't record the function body
-of ``int b()`` in the BMI for ``B`` so that the module ``A`` doesn't contribute to the BMI of ``B``
+of `int b()` in the BMI for `B` so that the module `A` doesn't contribute to the BMI of `B`
and we have less dependencies.
-Performance Tips
-----------------
+### Performance Tips
-Reduce duplications
-~~~~~~~~~~~~~~~~~~~
+#### Reduce duplications
While it is valid to have duplicated declarations in the global module fragments
of different module units, it is not free for Clang to deal with the duplicated
@@ -862,88 +830,87 @@ declarations. A translation unit will compile more slowly if there are a lot of
duplicated declarations between the translation unit and modules it imports.
For example:
-.. code-block:: c++
-
- // M-partA.cppm
- module;
- #include "big.header.h"
- export module M:partA;
- ...
-
- // M-partB.cppm
- module;
- #include "big.header.h"
- export module M:partB;
- ...
-
- // other partitions
- ...
-
- // M-partZ.cppm
- module;
- #include "big.header.h"
- export module M:partZ;
- ...
-
- // M.cppm
- export module M;
- export import :partA;
- export import :partB;
- ...
- export import :partZ;
-
- // use.cpp
- import M;
- ... // use declarations from module M.
-
-When ``big.header.h`` is big enough and there are a lot of partitions, the
-compilation of ``use.cpp`` may be significantly slower than the following
+```c++
+// M-partA.cppm
+module;
+#include "big.header.h"
+export module M:partA;
+...
+
+// M-partB.cppm
+module;
+#include "big.header.h"
+export module M:partB;
+...
+
+// other partitions
+...
+
+// M-partZ.cppm
+module;
+#include "big.header.h"
+export module M:partZ;
+...
+
+// M.cppm
+export module M;
+export import :partA;
+export import :partB;
+...
+export import :partZ;
+
+// use.cpp
+import M;
+... // use declarations from module M.
+```
+
+When `big.header.h` is big enough and there are a lot of partitions, the
+compilation of `use.cpp` may be significantly slower than the following
approach:
-.. code-block:: c++
-
- module;
- #include "big.header.h"
- export module m:big.header.wrapper;
- export ... // export the needed declarations
-
- // M-partA.cppm
- export module M:partA;
- import :big.header.wrapper;
- ...
-
- // M-partB.cppm
- export module M:partB;
- import :big.header.wrapper;
- ...
-
- // other partitions
- ...
-
- // M-partZ.cppm
- export module M:partZ;
- import :big.header.wrapper;
- ...
-
- // M.cppm
- export module M;
- export import :partA;
- export import :partB;
- ...
- export import :partZ;
-
- // use.cpp
- import M;
- ... // use declarations from module M.
+```c++
+module;
+#include "big.header.h"
+export module m:big.header.wrapper;
+export ... // export the needed declarations
+
+// M-partA.cppm
+export module M:partA;
+import :big.header.wrapper;
+...
+
+// M-partB.cppm
+export module M:partB;
+import :big.header.wrapper;
+...
+
+// other partitions
+...
+
+// M-partZ.cppm
+export module M:partZ;
+import :big.header.wrapper;
+...
+
+// M.cppm
+export module M;
+export import :partA;
+export import :partB;
+...
+export import :partZ;
+
+// use.cpp
+import M;
+... // use declarations from module M.
+```
Reducing the duplication from textual includes is what improves compile-time
performance.
-To help users to identify such issues, we add a warning ``-Wdecls-in-multiple-modules``.
-This warning is disabled by default and it needs to be explicitly enabled or by ``-Weverything``.
+To help users to identify such issues, we add a warning `-Wdecls-in-multiple-modules`.
+This warning is disabled by default and it needs to be explicitly enabled or by `-Weverything`.
-Transitioning to modules
-------------------------
+### Transitioning to modules
It is best for new code and libraries to use modules from the start if
possible. However, it may be a breaking change for existing code or libraries
@@ -955,74 +922,71 @@ for existing libraries. **Note that this information is only intended as
guidance, rather than as requirements to use modules in Clang.** It presumes
the project is starting with no module-based dependencies.
-ABI non-breaking styles
-~~~~~~~~~~~~~~~~~~~~~~~
-
-export-using style
-^^^^^^^^^^^^^^^^^^
+#### ABI non-breaking styles
-.. code-block:: c++
+##### export-using style
- module;
- #include "header_1.h"
- #include "header_2.h"
+```c++
+module;
+#include "header_1.h"
+#include "header_2.h"
+...
+#include "header_n.h"
+export module your_library;
+export namespace your_namespace {
+ using decl_1;
+ using decl_2;
...
- #include "header_n.h"
- export module your_library;
- export namespace your_namespace {
- using decl_1;
- using decl_2;
- ...
- using decl_n;
- }
+ using decl_n;
+}
+```
This example shows how to include all the headers containing declarations which
need to be exported, and uses `using` declarations in an `export` block to
produce the module interface.
-export extern-C++ style
-^^^^^^^^^^^^^^^^^^^^^^^
-
-.. code-block:: c++
-
- module;
- #include "third_party/A/headers.h"
- #include "third_party/B/headers.h"
+##### export extern-C++ style
+
+```c++
+module;
+#include "third_party/A/headers.h"
+#include "third_party/B/headers.h"
+...
+#include "third_party/Z/headers.h"
+export module your_library;
+#define IN_MODULE_INTERFACE
+extern "C++" {
+ #include "header_1.h"
+ #include "header_2.h"
...
- #include "third_party/Z/headers.h"
- export module your_library;
- #define IN_MODULE_INTERFACE
- extern "C++" {
- #include "header_1.h"
- #include "header_2.h"
- ...
- #include "header_n.h"
- }
-
-Headers (from ``header_1.h`` to ``header_n.h``) need to define the macro:
+ #include "header_n.h"
+}
+```
-.. code-block:: c++
+Headers (from `header_1.h` to `header_n.h`) need to define the macro:
- #ifdef IN_MODULE_INTERFACE
- #define EXPORT export
- #else
- #define EXPORT
- #endif
+```c++
+#ifdef IN_MODULE_INTERFACE
+#define EXPORT export
+#else
+#define EXPORT
+#endif
+```
-and put ``EXPORT`` on the declarations you want to export.
+and put `EXPORT` on the declarations you want to export.
Also, it is recommended to refactor headers to include third-party headers
conditionally:
-.. code-block:: c++
+```c++
+#ifndef IN_MODULE_INTERFACE
+#include "third_party/A/headers.h"
+#endif
- #ifndef IN_MODULE_INTERFACE
- #include "third_party/A/headers.h"
- #endif
+#include "header_x.h"
- #include "header_x.h"
-
- ...
+...
+```
This can be helpful because it gives better diagnostic messages if the module
interface unit is not properly updated when modifying code.
@@ -1034,46 +998,45 @@ change.
While this style is more involved than the export-using style, it makes it
easier to further refactor the library to other styles.
-ABI breaking style
-~~~~~~~~~~~~~~~~~~
+#### ABI breaking style
-The term ``ABI breaking`` may sound like a bad approach. However, this style
+The term `ABI breaking` may sound like a bad approach. However, this style
forces consumers of the library use it in a consistent way. e.g., either always
include headers for the library or always import modules. The style prevents
the ability to mix includes and imports for the library.
The pattern for ABI breaking style is similar to the export extern-C++ style.
-.. code-block:: c++
-
- module;
- #include "third_party/A/headers.h"
- #include "third_party/B/headers.h"
- ...
- #include "third_party/Z/headers.h"
- export module your_library;
- #define IN_MODULE_INTERFACE
- #include "header_1.h"
- #include "header_2.h"
- ...
- #include "header_n.h"
-
- #if the number of .cpp files in your project are small
- module :private;
- #include "source_1.cpp"
- #include "source_2.cpp"
+```c++
+module;
+#include "third_party/A/headers.h"
+#include "third_party/B/headers.h"
+...
+#include "third_party/Z/headers.h"
+export module your_library;
+#define IN_MODULE_INTERFACE
+#include "header_1.h"
+#include "header_2.h"
+...
+#include "header_n.h"
+
+#if the number of .cpp files in your project are small
+module :private;
+#include "source_1.cpp"
+#include "source_2.cpp"
+...
+#include "source_n.cpp"
+#else // the number of .cpp files in your project are a lot
+// Using all the declarations from third-party libraries which are
+// used in the .cpp files.
+namespace third_party_namespace {
+ using third_party_decl_used_in_cpp_1;
+ using third_party_decl_used_in_cpp_2;
...
- #include "source_n.cpp"
- #else // the number of .cpp files in your project are a lot
- // Using all the declarations from third-party libraries which are
- // used in the .cpp files.
- namespace third_party_namespace {
- using third_party_decl_used_in_cpp_1;
- using third_party_decl_used_in_cpp_2;
- ...
- using third_party_decl_used_in_cpp_n;
- }
- #endif
+ using third_party_decl_used_in_cpp_n;
+}
+#endif
+```
(And add `EXPORT` and conditional include to the headers as suggested in the
export extern-C++ style section.)
@@ -1081,24 +1044,24 @@ export extern-C++ style section.)
The ABI with modules is different and thus we need to compile the source files
into the new ABI. This is done by an additional part of the interface unit:
-.. code-block:: c++
-
- #if the number of .cpp files in your project are small
- module :private;
- #include "source_1.cpp"
- #include "source_2.cpp"
+```c++
+#if the number of .cpp files in your project are small
+module :private;
+#include "source_1.cpp"
+#include "source_2.cpp"
+...
+#include "source_n.cpp"
+#else // the number of .cpp files in your project are a lot
+// Using all the declarations from third-party libraries which are
+// used in the .cpp files.
+namespace third_party_namespace {
+ using third_party_decl_used_in_cpp_1;
+ using third_party_decl_used_in_cpp_2;
...
- #include "source_n.cpp"
- #else // the number of .cpp files in your project are a lot
- // Using all the declarations from third-party libraries which are
- // used in the .cpp files.
- namespace third_party_namespace {
- using third_party_decl_used_in_cpp_1;
- using third_party_decl_used_in_cpp_2;
- ...
- using third_party_decl_used_in_cpp_n;
- }
- #endif
+ using third_party_decl_used_in_cpp_n;
+}
+#endif
+```
If the number of source files is small, everything can be put in the private
module fragment directly (it is recommended to add conditional includes to the
@@ -1112,19 +1075,19 @@ module fragment should be the only module unit of the corresponding module.**
In this case, source files (.cpp files) must be converted to module
implementation units:
-.. code-block:: c++
-
- #ifndef IN_MODULE_INTERFACE
- // List all the includes here.
- #include "third_party/A/headers.h"
- ...
- #include "header.h"
- #endif
+```c++
+#ifndef IN_MODULE_INTERFACE
+// List all the includes here.
+#include "third_party/A/headers.h"
+...
+#include "header.h"
+#endif
- module your_library;
+module your_library;
- // Following off should be unchanged.
- ...
+// Following off should be unchanged.
+...
+```
The module implementation unit will import the primary module implicitly. Do
not include any headers in the module implementation units as it avoids
@@ -1132,12 +1095,11 @@ duplicated declarations between translation units. This is why non-exported
using declarations should be added from third-party libraries in the primary
module interface unit.
-If the library is provided as ``libyour_library.so``, a modular library (e.g.,
-``libyour_library_modules.so``) may also need to be provided for ABI
+If the library is provided as `libyour_library.so`, a modular library (e.g.,
+`libyour_library_modules.so`) may also need to be provided for ABI
compatibility.
-What if there are headers only included by the source files
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+##### What if there are headers only included by the source files
The above practice may be problematic if there are headers only included by the
source files. When using a private module fragment, this issue may be solved by
@@ -1150,131 +1112,128 @@ This can potentially be improved by introducing a module partition
implementation unit. An internal module partition unit is an importable
module unit which is internal to the module itself.
-The ABI of your library
-^^^^^^^^^^^^^^^^^^^^^^^
+##### The ABI of your library
You can skip this section your library doesn't ship ABI.
-With the ABI breaking style, for every ABI you shipped in your library,
+With the ABI breaking style, for every ABI you shipped in your library,
you should provide a corresponding ABI within the modules version.
For example, if this your library before provding modules,
-.. code-block:: c++
-
- // header.h
- #pragma once
+```c++
+// header.h
+#pragma once
- #include <cstdint>
+#include <cstdint>
- namespace example {
- class C {
- public:
- std::size_t inline_get() { return 42; }
- std::size_t get();
- };
- }
+namespace example {
+class C {
+public:
+ std::size_t inline_get() { return 42; }
+ std::size_t get();
+};
+}
- // src.cpp
- #include "header.h"
+// src.cpp
+#include "header.h"
- std::size_t example::C::get() {
- return 43 + inline_get();
- }
+std::size_t example::C::get() {
+ return 43 + inline_get();
+}
+```
Then you will ship ABI may be like:
-.. code-block:: text
-
- $nm -ACD libexample.so
- libexample.so:0000000000001130 W example::C::inline_get()
- libexample.so:0000000000001110 T example::C::get()
+```text
+$nm -ACD libexample.so
+libexample.so:0000000000001130 W example::C::inline_get()
+libexample.so:0000000000001110 T example::C::get()
+```
Then with ABI breaking style, your code may look like:
-.. code-block:: c++
-
- // example.cppm
- export module example;
- import std;
- // and other third-party modules, if any
- #define IN_MODULE_WRAPPER
- #include "header.h" // omit changing of header.h for brevity
+```c++
+// example.cppm
+export module example;
+import std;
+// and other third-party modules, if any
+#define IN_MODULE_WRAPPER
+#include "header.h" // omit changing of header.h for brevity
- // src.module.cpp
- module example;
- #define IN_MODULE_IMPL
- #include "src.cpp" // omit changing of src.cpp for brevity
+// src.module.cpp
+module example;
+#define IN_MODULE_IMPL
+#include "src.cpp" // omit changing of src.cpp for brevity
+```
And your ABI should look like:
-.. code-block:: text
-
- $llvm-nm -ACD libexample.so
- libexample.so: 0000000000001060 T initializer for module example
- libexample.so: 0000000000001150 W example::C::inline_get()
- libexample.so: 0000000000001130 T example::C::get()
- libexample.so: 0000000000001180 T example::C at example::inline_get()
- libexample.so: 0000000000001160 T example::C at example::get()
-
-Here ``example::C at example::inline_get()`` and ``example::C at example::get()`` is
-the corresponding version for ``example::C::inline_get()`` and ``example::C::get()``
+```text
+$llvm-nm -ACD libexample.so
+libexample.so: 0000000000001060 T initializer for module example
+libexample.so: 0000000000001150 W example::C::inline_get()
+libexample.so: 0000000000001130 T example::C::get()
+libexample.so: 0000000000001180 T example::C at example::inline_get()
+libexample.so: 0000000000001160 T example::C at example::get()
+```
+
+Here `example::C at example::inline_get()` and `example::C at example::get()` is
+the corresponding version for `example::C::inline_get()` and `example::C::get()`
in modules version.
-Which part of the ABI will be broken?
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+##### Which part of the ABI will be broken?
While your library keeps ABI compatible by providing both ABI versions.
The users's ABI may be breaking if they used the ABI of modules' version.
-This is similar with
-`the famous ABI break in GCC 5's libstdc++ for C++11 <https://gcc.gnu.org/onlinedocs/libstdc++/manual/using_dual_abi.html>`_.
+This is similar with
+[the famous ABI break in GCC 5's libstdc++ for C++11](https://gcc.gnu.org/onlinedocs/libstdc++/manual/using_dual_abi.html).
Although your library remains compatible with both ABIs, for your library's users,
choosing the module-based ABI will also break their ABI. For example, if your user's
code contains:
-.. code-block:: c++
+```c++
+#include "header.h"
- #include "header.h"
+namespace user {
+ void user_def(example::C& c) {
- namespace user {
- void user_def(example::C& c) {
-
- }
- }
+ }
+}
+```
then, (if your user will ship ABI too), their shipped ABI may look like:
-.. code-block:: c++
-
- $ llvm-nm -ACD libuser.so
- libuser.so: 0000000000001100 T user::user_def(example::C&)
+```c++
+$ llvm-nm -ACD libuser.so
+libuser.so: 0000000000001100 T user::user_def(example::C&)
+```
But when your user switches to your ABI-breaking style module:
-.. code-block:: c++
+```c++
+import example;
- import example;
+namespace user {
+ void user_def(example::C& c) {
- namespace user {
- void user_def(example::C& c) {
-
- }
- }
+ }
+}
+```
The corresponding ABI may look like:
-.. code-block:: text
-
- $ llvm-nm -ACD libuser.so
- libuser.so: 0000000000001100 T user::user_def(example::C at example&)
+```text
+$ llvm-nm -ACD libuser.so
+libuser.so: 0000000000001100 T user::user_def(example::C at example&)
+```
-Here we can find the ABI break from ``user::user_def(example::C&)`` to
-``user::user_def(example::C at example&)``.
+Here we can find the ABI break from `user::user_def(example::C&)` to
+`user::user_def(example::C at example&)`.
-Less duplicated generated code
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+##### Less duplicated generated code
Another benefit of ABI breaking style is, it is more likely to modules native
style. So that compiler can generate the previously implicitly inline entities
@@ -1282,8 +1241,8 @@ style. So that compiler can generate the previously implicitly inline entities
to the module unit instead of generating them in every translation unit used.
e.g, for the above example, in header version, the definition of
-``example::C::inline_get()`` will be generated in every translation unit used.
-But in modules version, ``example::C::inline_get()`` will only be generated once
+`example::C::inline_get()` will be generated in every translation unit used.
+But in modules version, `example::C::inline_get()` will only be generated once
in the module unit.
This is helpful for the whole build process to generate less duplicated code,
@@ -1295,100 +1254,97 @@ ABI breaking style, it is suggestted to use a macro to control inliness of the e
e.g.,
-.. code-block:: c++
+```c++
+// your_header.h
+#include <cstdint>
- // your_header.h
- #include <cstdint>
-
- inline void your_interface() {}
+inline void your_interface() {}
+```
within ABI breaking style, we suggest,
-.. code-block:: c++
-
- // your_header.h
- #ifndef IN_MODULE_WRAPPER
- #include <cstdint>
- #endif
+```c++
+// your_header.h
+#ifndef IN_MODULE_WRAPPER
+#include <cstdint>
+#endif
- #ifdef IN_MODULE_WRAPPER
- #define MY_EXPORT export
- #else
- #define MY_EXPORT
- #endif
+#ifdef IN_MODULE_WRAPPER
+#define MY_EXPORT export
+#else
+#define MY_EXPORT
+#endif
- #ifdef IN_MODULE_WRAPPER
- #define MY_INLINE
- #else
- #define MY_INLINE inline
- #endif
+#ifdef IN_MODULE_WRAPPER
+#define MY_INLINE
+#else
+#define MY_INLINE inline
+#endif
- MY_EXPORT MY_INLINE void your_interface() {}
+MY_EXPORT MY_INLINE void your_interface() {}
- // your_module_interface.cppm
- export module your_library;
- import std;
- #define IN_MODULE_WRAPPER
- #include "your_header.h"
+// your_module_interface.cppm
+export module your_library;
+import std;
+#define IN_MODULE_WRAPPER
+#include "your_header.h"
+```
-So that ``your_interface()`` will not be inline in modules version.
+So that `your_interface()` will not be inline in modules version.
-Providing a header to skip parsing redundant headers
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+#### Providing a header to skip parsing redundant headers
Many redeclarations shared between translation units cause Clang to have
slower compile-time performance. Further, there are known issues with
-`include after import <https://github.com/llvm/llvm-project/issues/61465>`_.
+[include after import](https://github.com/llvm/llvm-project/issues/61465).
Even when that issue is resolved, users may still get slower compilation speed
and larger BMIs. For these reasons, it is recommended to not include headers
after importing the corresponding module. However, it is not always easy if the
library is included by other dependencies, as in:
-.. code-block:: c++
-
- #include "third_party/A.h" // #include "your_library/a_header.h"
- import your_library;
+```c++
+#include "third_party/A.h" // #include "your_library/a_header.h"
+import your_library;
+```
or
-.. code-block:: c++
-
- import your_library;
- #include "third_party/A.h" // #include "your_library/a_header.h"
+```c++
+import your_library;
+#include "third_party/A.h" // #include "your_library/a_header.h"
+```
For such cases, it is best if the library providing both module and header
interfaces also provides a header which skips parsing so that the library can
be imported with the following approach that skips redundant redeclarations:
-.. code-block:: c++
-
- import your_library;
- #include "your_library_imported.h"
- #include "third_party/A.h" // #include "your_library/a_header.h" but got skipped
+```c++
+import your_library;
+#include "your_library_imported.h"
+#include "third_party/A.h" // #include "your_library/a_header.h" but got skipped
+```
-The implementation of ``your_library_imported.h`` can be a set of controlling
+The implementation of `your_library_imported.h` can be a set of controlling
macros or an overall controlling macro if using `#pragma once`. Then headers
can be refactored to:
-.. code-block:: c++
-
- #pragma once
- #ifndef YOUR_LIBRARY_IMPORTED
- ...
- #endif
+```c++
+#pragma once
+#ifndef YOUR_LIBRARY_IMPORTED
+...
+#endif
+```
If the modules imported by the library provide such headers, remember to add
-them to ``your_library_imported.h`` too.
+them to `your_library_imported.h` too.
-Importing modules
-~~~~~~~~~~~~~~~~~
+#### Importing modules
When there are library dependencies providing modules, the module dependencies
should be imported in your module as well. Many existing libraries will fall
-into this category once the ``std`` module is more widely available.
+into this category once the `std` module is more widely available.
-All library dependencies providing modules
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+##### All library dependencies providing modules
Of course, most of the complexity disappears if all the library dependencies
provide modules.
@@ -1396,131 +1352,128 @@ provide modules.
Headers need to be converted to include third-party headers conditionally. Then,
for the export-using style:
-.. code-block:: c++
-
- module;
- import modules_from_third_party;
- #define IN_MODULE_INTERFACE
- #include "header_1.h"
- #include "header_2.h"
+```c++
+module;
+import modules_from_third_party;
+#define IN_MODULE_INTERFACE
+#include "header_1.h"
+#include "header_2.h"
+...
+#include "header_n.h"
+export module your_library;
+export namespace your_namespace {
+ using decl_1;
+ using decl_2;
...
- #include "header_n.h"
- export module your_library;
- export namespace your_namespace {
- using decl_1;
- using decl_2;
- ...
- using decl_n;
- }
+ using decl_n;
+}
+```
or, for the export extern-C++ style:
-.. code-block:: c++
-
- export module your_library;
- import modules_from_third_party;
- #define IN_MODULE_INTERFACE
- extern "C++" {
- #include "header_1.h"
- #include "header_2.h"
- ...
- #include "header_n.h"
- }
-
-or, for the ABI-breaking style,
-
-.. code-block:: c++
-
- export module your_library;
- import modules_from_third_party;
- #define IN_MODULE_INTERFACE
+```c++
+export module your_library;
+import modules_from_third_party;
+#define IN_MODULE_INTERFACE
+extern "C++" {
#include "header_1.h"
#include "header_2.h"
...
#include "header_n.h"
+}
+```
- #if the number of .cpp files in your project are small
- module :private;
- #include "source_1.cpp"
- #include "source_2.cpp"
- ...
- #include "source_n.cpp"
- #endif
+or, for the ABI-breaking style,
-Non-exported ``using`` declarations are unnecessary if using implementation
+```c++
+export module your_library;
+import modules_from_third_party;
+#define IN_MODULE_INTERFACE
+#include "header_1.h"
+#include "header_2.h"
+...
+#include "header_n.h"
+
+#if the number of .cpp files in your project are small
+module :private;
+#include "source_1.cpp"
+#include "source_2.cpp"
+...
+#include "source_n.cpp"
+#endif
+```
+
+Non-exported `using` declarations are unnecessary if using implementation
module units. Instead, third-party modules can be imported directly in
implementation module units.
-Partial library dependencies providing modules
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+##### Partial library dependencies providing modules
-If the library has to mix the use of ``include`` and ``import`` in its module,
+If the library has to mix the use of `include` and `import` in its module,
the primary goal is still the removal of duplicated declarations in translation
units as much as possible. If the imported modules provide headers to skip
parsing their headers, those should be included after the import. If the
imported modules don't provide such a header, one can be made manually for
improved compile time performance.
-Reachability of internal partition units
-----------------------------------------
+### Reachability of internal partition units
The internal partition units are sometimes called implementation partition units in other documentation.
However, the name may be confusing since implementation partition units are not implementation
units.
-According to `[module.reach]p1 <https://eel.is/c++draft/module.reach#1>`_ and
-`[module.reach]p2 <https://eel.is/c++draft/module.reach#2>`_ (from N4986):
-
- A translation unit U is necessarily reachable from a point P if U is a module
- interface unit on which the translation unit containing P has an interface
- dependency, or the translation unit containing P imports U, in either case
- prior to P.
+According to [[module.reach]p1](https://eel.is/c++draft/module.reach#1) and
+[[module.reach]p2](https://eel.is/c++draft/module.reach#2) (from N4986):
- All translation units that are necessarily reachable are reachable. Additional
- translation units on which the point within the program has an interface
- dependency may be considered reachable, but it is unspecified which are and
- under what circumstances.
+> A translation unit U is necessarily reachable from a point P if U is a module
+> interface unit on which the translation unit containing P has an interface
+> dependency, or the translation unit containing P imports U, in either case
+> prior to P.
+>
+> All translation units that are necessarily reachable are reachable. Additional
+> translation units on which the point within the program has an interface
+> dependency may be considered reachable, but it is unspecified which are and
+> under what circumstances.
For example,
-.. code-block:: c++
-
- // a.cpp
- import B;
- int main()
- {
- g<void>();
- }
-
- // b.cppm
- export module B;
- import :C;
- export template <typename T> inline void g() noexcept
- {
- return f<T>();
- }
-
- // c.cppm
- module B:C;
- template<typename> inline void f() noexcept {}
-
-The internal partition unit ``c.cppm`` is not necessarily reachable by
-``a.cpp`` because ``c.cppm`` is not a module interface unit and ``a.cpp``
-doesn't import ``c.cppm``. This leaves it up to the compiler to decide if
-``c.cppm`` is reachable by ``a.cpp`` or not. Clang's behavior is that
+```c++
+// a.cpp
+import B;
+int main()
+{
+ g<void>();
+}
+
+// b.cppm
+export module B;
+import :C;
+export template <typename T> inline void g() noexcept
+{
+ return f<T>();
+}
+
+// c.cppm
+module B:C;
+template<typename> inline void f() noexcept {}
+```
+
+The internal partition unit `c.cppm` is not necessarily reachable by
+`a.cpp` because `c.cppm` is not a module interface unit and `a.cpp`
+doesn't import `c.cppm`. This leaves it up to the compiler to decide if
+`c.cppm` is reachable by `a.cpp` or not. Clang's behavior is that
indirectly imported internal partition units are not reachable.
The suggested approach for using an internal partition unit in Clang is
to only import them in the implementation unit.
-Using Clang Module Map to Avoid mixing #include and import problems
--------------------------------------------------------------------
+### Using Clang Module Map to Avoid mixing #include and import problems
-.. note::
- Discussion in this section is experimental.
+:::{note}
+Discussion in this section is experimental.
+:::
-Problems Background
-~~~~~~~~~~~~~~~~~~~
+#### Problems Background
As discussed before, the redeclaration in different TU is one of the major problems
of using modules from the perspective of the compiler. The redeclaration pattern
@@ -1529,24 +1482,24 @@ pattern as expected, the compilation performance will be affected too.
e.g,
-.. code-block:: c++
-
- // a.h
- #pragma once
- class A { ... };
+```c++
+// a.h
+#pragma once
+class A { ... };
- // a.cppm
- module;
- #include "a.h"
- export module a;
- export using ::A;
+// a.cppm
+module;
+#include "a.h"
+export module a;
+export using ::A;
- // a.cc
- import a;
- #include "a.h"
- A a;
+// a.cc
+import a;
+#include "a.h"
+A a;
+```
-Here in ``a.cc``, we have redeclaration for ``A``, one from ``a.cppm`` and one from ``a.cc``
+Here in `a.cc`, we have redeclaration for `A`, one from `a.cppm` and one from `a.cc`
itself.
To avoid the redeclaration pattern, in previous section, we suggested users to comment
@@ -1555,29 +1508,25 @@ out thirdparty headers manually.
And here we will introduce another approach to avoid such redeclaration pattern by using
clang module map.
-Clang Module Map Background
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+#### Clang Module Map Background
-Clang Module Map is a feature of Clang Header Modules. See `Clang Module <Modules.html>`_
+Clang Module Map is a feature of Clang Header Modules. See [Clang Module](Modules.html)
for full introduction of Clang Header Modules. Here we would only introduce Clang Header
Modules to make this document self contained.
-Clang Implicit Header Modules
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+##### Clang Implicit Header Modules
In Clang Implicit Header Module mode, Clang will read the module map and compile the
-header in the module map into a module file and use the module file automatically.
+header in the module map into a module file and use the module file automatically.
This sounds very nice. But due to the complexity, this is not so wonderful in practice.
-Clang has to compile the same header in different preprocessor context into
+Clang has to compile the same header in different preprocessor context into
different module file for correctness conservatively. Then this may trigger the
redeclaration in different TU problems. So that the user of implicit header modules
-has to design a module system bottom up carefully. And clang implicit header module
-`has many issues with soundness and performance due to tradeoffs made for module
-reuse and filesystem contention
-<https://discourse.llvm.org/t/clang-modules-build-daemon-build-system-agnostic-support-for-explicitly-built-modules>`_.
+has to design a module system bottom up carefully. And clang implicit header module
+[has many issues with soundness and performance due to tradeoffs made for module
+reuse and filesystem contention](https://discourse.llvm.org/t/clang-modules-build-daemon-build-system-agnostic-support-for-explicitly-built-modules).
-Clang Explicit Header Modules
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+##### Clang Explicit Header Modules
Clang explicit header modules offloads the job of creating and managing module files
to the build system. Given the C++20 modules and clang header modules actually share the
@@ -1589,34 +1538,33 @@ For the above example,
e.g,
-.. code-block:: c++
+```c++
+// a.h
+#pragma once
+class A { ... };
- // a.h
- #pragma once
- class A { ... };
+// a.cppm
+module;
+#include "a.h"
+export module a;
+export using ::A;
- // a.cppm
- module;
- #include "a.h"
- export module a;
- export using ::A;
+// a.cc
+import a;
+#include "a.h"
+A a;
+```
- // a.cc
- import a;
- #include "a.h"
- A a;
+The build system can build the header into a module file and use it in both `a.cppm` and `a.cc`.
+Then there is no redeclaration in the example. All the declaration of `class A` come from the
+synthesized TU `a.h`.
-The build system can build the header into a module file and use it in both ``a.cppm`` and ``a.cc``.
-Then there is no redeclaration in the example. All the declaration of ``class A`` come from the
-synthesized TU ``a.h``.
-
-But there are problems: (1) the build system needs to support clang explicit module.
+But there are problems: (1) the build system needs to support clang explicit module.
(2) The interaction between clang named modules and clang header modules are theoriticall fine but
not verified in practice. And also the document itself is about standard C++ modules, so we won't
expand here.
-Examples
-~~~~~~~~
+#### Examples
To use Clang Module Map for C++20 Named Modules, end users have to wait for the support
from build systems. Here we ignore the build systems to help users to understand the
@@ -1624,143 +1572,142 @@ mechanism.
Here is an example of using clang module map to replace a header to an import of a module.
-.. code-block:: c++
-
- // a.h
- #pragma once
- static_assert(false, "don't include a.h");
-
- // main.cpp
- #include "a.h"
- int main() {
- return 0;
- }
-
- // a.cppm
- module;
- #include <iostream>
- export module a;
- struct Init {
- Init() {
- std::cout << "Module 'a' got imported" << std::endl;
- }
- };
- Init a;
-
- // a.cppm.modulemap
- module a {
- header "a.h"
- }
+```c++
+// a.h
+#pragma once
+static_assert(false, "don't include a.h");
-Then invoke Clang with:
+// main.cpp
+#include "a.h"
+int main() {
+ return 0;
+}
+
+// a.cppm
+module;
+#include <iostream>
+export module a;
+struct Init {
+ Init() {
+ std::cout << "Module 'a' got imported" << std::endl;
+ }
+};
+Init a;
+
+// a.cppm.modulemap
+module a {
+ header "a.h"
+}
+```
-.. code-block:: console
+Then invoke Clang with:
- $ clang++ -std=c++20 a.cppm -c -fmodule-output=a.pcm -o a.o
- $ clang++ -std=c++20 main.cpp -fmodule-map-file=a.cppm.modulemap -fmodule-file=a=a.pcm a.o -o main
- $ ./main
- Module 'a' got imported
+```console
+$ clang++ -std=c++20 a.cppm -c -fmodule-output=a.pcm -o a.o
+$ clang++ -std=c++20 main.cpp -fmodule-map-file=a.cppm.modulemap -fmodule-file=a=a.pcm a.o -o main
+$ ./main
+Module 'a' got imported
+```
-We can find that the header file ``a.h`` is not included actually (otherwise the compilation should fail due to the static assert).
-And it imports the module ``a`` and then the varaible in module ``a`` got initialized.
+We can find that the header file `a.h` is not included actually (otherwise the compilation should fail due to the static assert).
+And it imports the module `a` and then the varaible in module `a` got initialized.
-The secret comes from the flag ``-fmodule-map-file=a.cppm.modulemap``, the content of ``a.cppm.modulemap`` says:
-map the #include of ``a.h`` to the import to module ``a``. Then when the compiler sees ``#include "a.h"``, the compiler
-won't include ``a.h`` actually but tries to import the module ``a``. And the from the command line ``-fmodule-file=a=a.pcm``,
-the compiler get the module file of module ``a``, then module file of module ``a`` get imported and the inclusion of ``a.h``
+The secret comes from the flag `-fmodule-map-file=a.cppm.modulemap`, the content of `a.cppm.modulemap` says:
+map the #include of `a.h` to the import to module `a`. Then when the compiler sees `#include "a.h"`, the compiler
+won't include `a.h` actually but tries to import the module `a`. And the from the command line `-fmodule-file=a=a.pcm`,
+the compiler get the module file of module `a`, then module file of module `a` get imported and the inclusion of `a.h`
is skipped.
Then we can try to use the mechanism to avoid redeclaration pattern for header wrapping modules.
-.. code-block:: c++
-
- // a.h
- #pragma once
- class A { ... };
+```c++
+// a.h
+#pragma once
+class A { ... };
- // a.cppm
- module;
- #include "a.h"
- export module a;
- export using ::A;
+// a.cppm
+module;
+#include "a.h"
+export module a;
+export using ::A;
- // a.cc
- import a;
- #include "a.h"
- A a;
+// a.cc
+import a;
+#include "a.h"
+A a;
- // a.cppm.modulemap
- module a {
- header "a.h"
- }
+// a.cppm.modulemap
+module a {
+ header "a.h"
+}
+```
-Similarly, when we compile ``a.cc``, if we add the flag ``-fmodule-map-file=a.cppm.modulemap``, the compiler
-will map the inclusion of ``a.h`` to the import of module ``a``. And the module ``a`` is already imported.
-So we avoid the redeclaration of class ``A`` in ``a.cc``.
+Similarly, when we compile `a.cc`, if we add the flag `-fmodule-map-file=a.cppm.modulemap`, the compiler
+will map the inclusion of `a.h` to the import of module `a`. And the module `a` is already imported.
+So we avoid the redeclaration of class `A` in `a.cc`.
An imaginable problem with this approach maybe the hidden inclusion. e.g,
-.. code-block:: c++
-
- // b.h
- #pragma once
- struct B {};
-
- // a.h
- #pragma once
- #include "b.h"
- struct A { B b; };
-
- // b.cppm
- export module b;
- export extern "C++" struct B { };
-
- // a.cppm
- export module a;
- import b;
- export extern "C++" struct A { B b; };
-
- // test.cc
- import a;
- #include "a.h"
- A a;
- B b;
-
- // a.cppm.modulemap
- module a {
- header "a.h"
- }
-
- // b.cppm.modulemap
- module b {
- header "b.h"
- }
+```c++
+// b.h
+#pragma once
+struct B {};
+
+// a.h
+#pragma once
+#include "b.h"
+struct A { B b; };
+
+// b.cppm
+export module b;
+export extern "C++" struct B { };
+
+// a.cppm
+export module a;
+import b;
+export extern "C++" struct A { B b; };
+
+// test.cc
+import a;
+#include "a.h"
+A a;
+B b;
+
+// a.cppm.modulemap
+module a {
+ header "a.h"
+}
+
+// b.cppm.modulemap
+module b {
+ header "b.h"
+}
+```
The example is valid if we don't use the module map:
-.. code-block:: console
-
- $ clang++ -std=c++20 b.cppm -c -fmodule-output=b.pcm -o b.o
- $ clang++ -std=c++20 a.cppm -c -fmodule-output=a.pcm -fmodule-file=b=b.pcm -o a.o
- $ clang++ -std=c++20 test.cc -fmodule-file=a=a.pcm -fmodule-file=b=b.pcm -fsyntax-only
+```console
+$ clang++ -std=c++20 b.cppm -c -fmodule-output=b.pcm -o b.o
+$ clang++ -std=c++20 a.cppm -c -fmodule-output=a.pcm -fmodule-file=b=b.pcm -o a.o
+$ clang++ -std=c++20 test.cc -fmodule-file=a=a.pcm -fmodule-file=b=b.pcm -fsyntax-only
+```
But if we enable the module map, the example is invalid:
-.. code-block:: console
-
- $ clang++ -std=c++20 test.cc -fmodule-map-file=a.cppm.modulemap -fmodule-file=a=a.pcm -fmodule-map-file=b.cppm.modulemap -fmodule-file=b=b.pcm -fsyntax-only
- test.cc:4:1: error: declaration of 'B' must be imported from module 'b' before it is required
- 4 | B b;
- | ^
- b.cppm:2:28: note: declaration here is not visible
- 2 | export extern "C++" struct B { };
- | ^
- 1 error generated.
+```console
+$ clang++ -std=c++20 test.cc -fmodule-map-file=a.cppm.modulemap -fmodule-file=a=a.pcm -fmodule-map-file=b.cppm.modulemap -fmodule-file=b=b.pcm -fsyntax-only
+test.cc:4:1: error: declaration of 'B' must be imported from module 'b' before it is required
+ 4 | B b;
+ | ^
+b.cppm:2:28: note: declaration here is not visible
+ 2 | export extern "C++" struct B { };
+ | ^
+1 error generated.
+```
-A suggested convention for end users and build systems
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+#### A suggested convention for end users and build systems
-As said, the build system is a vital role in this strategy.
+As said, the build system is a vital role in this strategy.
However, for build systems, it is not easy to support clang explicit header modules or
support the module map with C++20 named modules generally. The complexity for build system
won't be less than supporting C++20 named modules.
@@ -1772,324 +1719,309 @@ and import.
For end users who is the author of header based library offering named module wrappers, The header's interface
should be a subset of the module interface excluding user-facing macros.
-* Extract all user facing headers into a single header file. Since C++20 named modules
-* For each named module interface, provide a module map file to map the interface headers to the named module. The name of the module map should be the name of the module interface unit plus ``.modulemap``.
+- Extract all user facing headers into a single header file. Since C++20 named modules
+- For each named module interface, provide a module map file to map the interface headers to the named module. The name of the module map should be the name of the module interface unit plus `.modulemap`.
The number of the module map may not be a lot sicne this is still a
header based library.
For build systems,
-* For each Translation Units, if the unit doesn't import any named modules, stop. This is not what we want.
-* If the TU imports named module, for all imported named module unit, look up for the module map file in the same path of the imported module unit with the name of the module unit plus ``.modulemap``. e.g., if the name of the module unit is ``a.cppm``, we should lookup for ``a.cppm.modulemap``.
-* For the found module map, pass ``-fmodule-map-file=<module_map_file_path>`` to the clang compiler.
+- For each Translation Units, if the unit doesn't import any named modules, stop. This is not what we want.
+- If the TU imports named module, for all imported named module unit, look up for the module map file in the same path of the imported module unit with the name of the module unit plus `.modulemap`. e.g., if the name of the module unit is `a.cppm`, we should lookup for `a.cppm.modulemap`.
+- For the found module map, pass `-fmodule-map-file=<module_map_file_path>` to the clang compiler.
The point of the approach is, the build system can reuse the result of C++20 named modules to manage depencies. So that
the implementation burden of build systems is largely reduced.
-Known Issues
-------------
+### Known Issues
The following describes issues in the current implementation of modules. Please
see
-`the issues list for modules <https://github.com/llvm/llvm-project/labels/clang%3Amodules>`_
+[the issues list for modules](https://github.com/llvm/llvm-project/labels/clang%3Amodules)
for a list of issues or to file a new issue if you don't find an existing one.
When creating a new issue for standard C++ modules, please start the title with
-``[C++20] [Modules]`` (or ``[C++23] [Modules]``, etc) and add the label
-``clang:modules`` if possible.
+`[C++20] [Modules]` (or `[C++23] [Modules]`, etc) and add the label
+`clang:modules` if possible.
A high-level overview of support for standards features, including modules, can
-be found on the `C++ Feature Status <https://clang.llvm.org/cxx_status.html>`_
+be found on the [C++ Feature Status](https://clang.llvm.org/cxx_status.html)
page.
-Including headers after import is not well-supported
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+#### Including headers after import is not well-supported
The following example is accepted:
-.. code-block:: c++
+```c++
+#include <iostream>
+import foo; // assume module 'foo' contain the declarations from `<iostream>`
- #include <iostream>
- import foo; // assume module 'foo' contain the declarations from `<iostream>`
-
- int main(int argc, char *argv[])
- {
- std::cout << "Test\n";
- return 0;
- }
+int main(int argc, char *argv[])
+{
+ std::cout << "Test\n";
+ return 0;
+}
+```
-but if the order of ``#include <iostream>`` and ``import foo;`` is reversed,
+but if the order of `#include <iostream>` and `import foo;` is reversed,
then the code is currently rejected:
-.. code-block:: c++
-
- import foo; // assume module 'foo' contain the declarations from `<iostream>`
- #include <iostream>
+```c++
+import foo; // assume module 'foo' contain the declarations from `<iostream>`
+#include <iostream>
- int main(int argc, char *argv[])
- {
- std::cout << "Test\n";
- return 0;
- }
+int main(int argc, char *argv[])
+{
+ std::cout << "Test\n";
+ return 0;
+}
+```
Both of the above examples should be accepted.
This is a limitation of the implementation. In the first example, the compiler
-will see and parse ``<iostream>`` first then it will see the ``import``. In
+will see and parse `<iostream>` first then it will see the `import`. In
this case, ODR checking and declaration merging will happen in the
-deserializer. In the second example, the compiler will see the ``import`` first
-and the ``#include`` second which results in ODR checking and declarations
+deserializer. In the second example, the compiler will see the `import` first
+and the `#include` second which results in ODR checking and declarations
merging happening in the semantic analyzer. This is due to a divergence in the
implementation path. This is tracked by
-`#61465 <https://github.com/llvm/llvm-project/issues/61465>`_.
+[#61465](https://github.com/llvm/llvm-project/issues/61465).
-Ignored ``preferred_name`` Attribute
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+#### Ignored `preferred_name` Attribute
-When Clang writes BMIs, it will ignore the ``preferred_name`` attribute on
+When Clang writes BMIs, it will ignore the `preferred_name` attribute on
declarations which use it. Thus, the preferred name will not be displayed in
the debugger as expected. This is tracked by
-`#56490 <https://github.com/llvm/llvm-project/issues/56490>`_.
+[#56490](https://github.com/llvm/llvm-project/issues/56490).
-Inconsistent filename suffix requirement for importable module units
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+#### Inconsistent filename suffix requirement for importable module units
-Currently, Clang requires the file name of an ``importable module unit`` to
-have ``.cppm`` (or ``.ccm``, ``.cxxm``, ``.c++m``) as the file extension.
+Currently, Clang requires the file name of an `importable module unit` to
+have `.cppm` (or `.ccm`, `.cxxm`, `.c++m`) as the file extension.
However, the behavior is inconsistent with other compilers. This is tracked by
-`#57416 <https://github.com/llvm/llvm-project/issues/57416>`_.
+[#57416](https://github.com/llvm/llvm-project/issues/57416).
-Incorrect ODR violation diagnostics
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+#### Incorrect ODR violation diagnostics
ODR violations are a common issue when using modules. Clang sometimes produces
false-positive diagnostics or fails to produce true-positive diagnostics of the
One Definition Rule. One often-reported example is:
-.. code-block:: c++
-
- // part.cc
- module;
- typedef long T;
- namespace ns {
- inline void fun() {
- (void)(T)0;
- }
- }
- export module repro:part;
-
- // repro.cc
- module;
- typedef long T;
- namespace ns {
- using ::T;
- }
- namespace ns {
- inline void fun() {
- (void)(T)0;
- }
- }
- export module repro;
- export import :part;
+```c++
+// part.cc
+module;
+typedef long T;
+namespace ns {
+inline void fun() {
+ (void)(T)0;
+}
+}
+export module repro:part;
+
+// repro.cc
+module;
+typedef long T;
+namespace ns {
+ using ::T;
+}
+namespace ns {
+inline void fun() {
+ (void)(T)0;
+}
+}
+export module repro;
+export import :part;
+```
Currently the compiler incorrectly diagnoses the inconsistent definition of
-``fun()`` in two module units. Because both definitions of ``fun()`` have the
-same spelling and ``T`` refers to the same type entity, there is no ODR
+`fun()` in two module units. Because both definitions of `fun()` have the
+same spelling and `T` refers to the same type entity, there is no ODR
violation. This is tracked by
-`#78850 <https://github.com/llvm/llvm-project/issues/78850>`_.
+[#78850](https://github.com/llvm/llvm-project/issues/78850).
-Using TU-local entity in other units
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+#### Using TU-local entity in other units
Module units are translation units, so the entities which should be local to
the module unit itself should never be used by other units.
-The C++ standard defines the concept of ``TU-local`` and ``exposure`` in
-`basic.link/p14 <https://eel.is/c++draft/basic.link#14>`_,
-`basic.link/p15 <https://eel.is/c++draft/basic.link#15>`_,
-`basic.link/p16 <https://eel.is/c++draft/basic.link#16>`_,
-`basic.link/p17 <https://eel.is/c++draft/basic.link#17>`_, and
-`basic.link/p18 <https://eel.is/c++draft/basic.link#18>`_.
+The C++ standard defines the concept of `TU-local` and `exposure` in
+[basic.link/p14](https://eel.is/c++draft/basic.link#14),
+[basic.link/p15](https://eel.is/c++draft/basic.link#15),
+[basic.link/p16](https://eel.is/c++draft/basic.link#16),
+[basic.link/p17](https://eel.is/c++draft/basic.link#17), and
+[basic.link/p18](https://eel.is/c++draft/basic.link#18).
However, Clang doesn't formally support these two concepts. This results in
unclear or confusing diagnostic messages. Further, Clang may import
-``TU-local`` entities to other units without any diagnostics. This is tracked
-by `#78173 <https://github.com/llvm/llvm-project/issues/78173>`_.
-
-.. _header-units:
+`TU-local` entities to other units without any diagnostics. This is tracked
+by [#78173](https://github.com/llvm/llvm-project/issues/78173).
-Header Units
-============
+(header-units)=
-How to build projects using header units
-----------------------------------------
+## Header Units
-.. warning::
+### How to build projects using header units
- The support for header units, including related command line options, is
- experimental. There are still many unanswered questions about how tools
- should interact with header units. The details described here may change in
- the future.
+:::{warning}
+The support for header units, including related command line options, is
+experimental. There are still many unanswered questions about how tools
+should interact with header units. The details described here may change in
+the future.
+:::
-Quick Start
-~~~~~~~~~~~
+#### Quick Start
The following example:
-.. code-block:: c++
-
- import <iostream>;
- int main() {
- std::cout << "Hello World.\n";
- }
+```c++
+import <iostream>;
+int main() {
+ std::cout << "Hello World.\n";
+}
+```
could be compiled with:
-.. code-block:: console
+```console
+$ clang++ -std=c++20 -xc++-system-header --precompile iostream -o iostream.pcm
+$ clang++ -std=c++20 -fmodule-file=iostream.pcm main.cpp
+```
- $ clang++ -std=c++20 -xc++-system-header --precompile iostream -o iostream.pcm
- $ clang++ -std=c++20 -fmodule-file=iostream.pcm main.cpp
+#### How to produce BMIs
-How to produce BMIs
-~~~~~~~~~~~~~~~~~~~
-
-Similar to named modules, ``--precompile`` can be used to produce a BMI.
+Similar to named modules, `--precompile` can be used to produce a BMI.
However, that requires specifying that the input file is a header by using
-``-xc++-system-header`` or ``-xc++-user-header``.
+`-xc++-system-header` or `-xc++-user-header`.
-The ``-fmodule-header={user,system}`` option can also be used to produce a BMI
+The `-fmodule-header={user,system}` option can also be used to produce a BMI
for header units which have a file extension like `.h` or `.hh`. The argument to
-``-fmodule-header`` specifies either the user search path or the system search
-path. The default value for ``-fmodule-header`` is ``user``. For example:
-
-.. code-block:: c++
-
- // foo.h
- #include <iostream>
- void Hello() {
- std::cout << "Hello World.\n";
- }
-
- // use.cpp
- import "foo.h";
- int main() {
- Hello();
- }
+`-fmodule-header` specifies either the user search path or the system search
+path. The default value for `-fmodule-header` is `user`. For example:
+
+```c++
+// foo.h
+#include <iostream>
+void Hello() {
+ std::cout << "Hello World.\n";
+}
+
+// use.cpp
+import "foo.h";
+int main() {
+ Hello();
+}
+```
could be compiled with:
-.. code-block:: console
-
- $ clang++ -std=c++20 -fmodule-header foo.h -o foo.pcm
- $ clang++ -std=c++20 -fmodule-file=foo.pcm use.cpp
+```console
+$ clang++ -std=c++20 -fmodule-header foo.h -o foo.pcm
+$ clang++ -std=c++20 -fmodule-file=foo.pcm use.cpp
+```
-For headers which do not have a file extension, ``-xc++-header`` (or
-``-xc++-system-header``, ``-xc++-user-header``) must be used to specify the
+For headers which do not have a file extension, `-xc++-header` (or
+`-xc++-system-header`, `-xc++-user-header`) must be used to specify the
file as a header. For example:
-.. code-block:: c++
-
- // use.cpp
- import "foo.h";
- int main() {
- Hello();
- }
+```c++
+// use.cpp
+import "foo.h";
+int main() {
+ Hello();
+}
+```
-.. code-block:: console
+```console
+$ clang++ -std=c++20 -fmodule-header=system -xc++-header iostream -o iostream.pcm
+$ clang++ -std=c++20 -fmodule-file=iostream.pcm use.cpp
+```
- $ clang++ -std=c++20 -fmodule-header=system -xc++-header iostream -o iostream.pcm
- $ clang++ -std=c++20 -fmodule-file=iostream.pcm use.cpp
+#### How to specify BMI dependencies
-How to specify BMI dependencies
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-``-fmodule-file`` can be used to specify a BMI dependency (or multiple times for
+`-fmodule-file` can be used to specify a BMI dependency (or multiple times for
more than one BMI dependency).
-With the existing implementation, ``-fprebuilt-module-path`` cannot be used for
+With the existing implementation, `-fprebuilt-module-path` cannot be used for
header units (because they are nominally anonymous). For header units, use
-``-fmodule-file`` to include the relevant PCM file for each header unit.
+`-fmodule-file` to include the relevant PCM file for each header unit.
This is expected to be solved in a future version of Clang either by the compiler
-finding and specifying ``-fmodule-file`` automatically, or by the use of a
+finding and specifying `-fmodule-file` automatically, or by the use of a
module-mapper that understands how to map the header name to their PCMs.
-Compiling a header unit to an object file
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+#### Compiling a header unit to an object file
A header unit cannot be compiled to an object file due to the semantics of
header units. For example:
-.. code-block:: console
-
- $ clang++ -std=c++20 -xc++-system-header --precompile iostream -o iostream.pcm
- # This is not allowed!
- $ clang++ iostream.pcm -c -o iostream.o
+```console
+$ clang++ -std=c++20 -xc++-system-header --precompile iostream -o iostream.pcm
+# This is not allowed!
+$ clang++ iostream.pcm -c -o iostream.o
+```
-Include translation
-~~~~~~~~~~~~~~~~~~~
+#### Include translation
-The C++ standard allows vendors to convert ``#include header-name`` to
-``import header-name;`` when possible. Currently, Clang does this translation
-for the ``#include`` in the global module fragment. For example, the following
+The C++ standard allows vendors to convert `#include header-name` to
+`import header-name;` when possible. Currently, Clang does this translation
+for the `#include` in the global module fragment. For example, the following
example:
-.. code-block:: c++
-
- module;
- import <iostream>;
- export module M;
- export void Hello() {
- std::cout << "Hello.\n";
- }
+```c++
+module;
+import <iostream>;
+export module M;
+export void Hello() {
+ std::cout << "Hello.\n";
+}
+```
is the same as this example:
-.. code-block:: c++
-
- module;
- #include <iostream>
- export module M;
- export void Hello() {
- std::cout << "Hello.\n";
- }
-
-.. code-block:: console
+```c++
+module;
+#include <iostream>
+export module M;
+export void Hello() {
+ std::cout << "Hello.\n";
+}
+```
- $ clang++ -std=c++20 -xc++-system-header --precompile iostream -o iostream.pcm
- $ clang++ -std=c++20 -fmodule-file=iostream.pcm --precompile M.cppm -o M.cpp
+```console
+$ clang++ -std=c++20 -xc++-system-header --precompile iostream -o iostream.pcm
+$ clang++ -std=c++20 -fmodule-file=iostream.pcm --precompile M.cppm -o M.cpp
+```
-In the latter example, Clang can find the BMI for ``<iostream>`` and so it
-tries to replace the ``#include <iostream>`` with ``import <iostream>;``
+In the latter example, Clang can find the BMI for `<iostream>` and so it
+tries to replace the `#include <iostream>` with `import <iostream>;`
automatically.
-
-Differences between Clang modules and header units
---------------------------------------------------
+### Differences between Clang modules and header units
Header units have similar semantics to Clang modules. The semantics of both are
like headers. Therefore, header units can be mimicked by Clang modules as in
the following example:
-.. code-block:: c++
+```c++
+module "iostream" {
+ export *
+ header "/path/to/libstdcxx/iostream"
+}
+```
- module "iostream" {
- export *
- header "/path/to/libstdcxx/iostream"
- }
-
-.. code-block:: console
-
- $ clang++ -std=c++20 -fimplicit-modules -fmodule-map-file=.modulemap main.cpp
+```console
+$ clang++ -std=c++20 -fimplicit-modules -fmodule-map-file=.modulemap main.cpp
+```
This example is simplified when using libc++:
-.. code-block:: console
-
- $ clang++ -std=c++20 main.cpp -fimplicit-modules -fimplicit-module-maps
+```console
+$ clang++ -std=c++20 main.cpp -fimplicit-modules -fimplicit-module-maps
+```
because libc++ already supplies a
-`module map <https://github.com/llvm/llvm-project/blob/main/libcxx/include/module.modulemap.in>`_.
+[module map](https://github.com/llvm/llvm-project/blob/main/libcxx/include/module.modulemap.in).
This raises the question: why are header units not implemented through Clang
modules?
@@ -2100,358 +2032,355 @@ Standard C++ Header units. We want to avoid the impression that these
additional semantics get interpreted as Standard C++ behavior.
Another reason is that there are proposals to introduce module mappers to the
-C++ standard (for example, https://wg21.link/p1184r2). Reusing Clang's
-``modulemap`` may be more difficult if we need to introduce another module
+C++ standard (for example, <https://wg21.link/p1184r2>). Reusing Clang's
+`modulemap` may be more difficult if we need to introduce another module
mapper.
-Discovering Dependencies
-========================
+## Discovering Dependencies
Without use of modules, all the translation units in a project can be compiled
in parallel. However, the presence of module units requires compiling the
translation units in a topological order.
-The ``clang-scan-deps`` tool can extract dependency information and produce a
+The `clang-scan-deps` tool can extract dependency information and produce a
JSON file conforming to the specification described in
-`P1689 <https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2022/p1689r5.html>`_.
+[P1689](https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2022/p1689r5.html).
Only named modules are supported currently.
-A compilation database is needed when using ``clang-scan-deps``. See
-`JSON Compilation Database Format Specification <JSONCompilationDatabase.html>`_
-for more information about compilation databases. Note that the ``output``
-JSON attribute is necessary for ``clang-scan-deps`` to scan using the P1689
+A compilation database is needed when using `clang-scan-deps`. See
+[JSON Compilation Database Format Specification](JSONCompilationDatabase.html)
+for more information about compilation databases. Note that the `output`
+JSON attribute is necessary for `clang-scan-deps` to scan using the P1689
format. For example:
-.. code-block:: c++
-
- //--- M.cppm
- export module M;
- export import :interface_part;
- import :impl_part;
- export int Hello();
-
- //--- interface_part.cppm
- export module M:interface_part;
- export void World();
-
- //--- Impl.cpp
- module;
- #include <iostream>
- module M;
- void Hello() {
- std::cout << "Hello ";
- }
-
- //--- impl_part.cppm
- module;
- #include <string>
- #include <iostream>
- module M:impl_part;
- import :interface_part;
-
- std::string W = "World.";
- void World() {
- std::cout << W << std::endl;
- }
-
- //--- User.cpp
- import M;
- import third_party_module;
- int main() {
- Hello();
- World();
- return 0;
- }
+```c++
+//--- M.cppm
+export module M;
+export import :interface_part;
+import :impl_part;
+export int Hello();
+
+//--- interface_part.cppm
+export module M:interface_part;
+export void World();
+
+//--- Impl.cpp
+module;
+#include <iostream>
+module M;
+void Hello() {
+ std::cout << "Hello ";
+}
+
+//--- impl_part.cppm
+module;
+#include <string>
+#include <iostream>
+module M:impl_part;
+import :interface_part;
+
+std::string W = "World.";
+void World() {
+ std::cout << W << std::endl;
+}
+
+//--- User.cpp
+import M;
+import third_party_module;
+int main() {
+ Hello();
+ World();
+ return 0;
+}
+```
And here is the compilation database:
-.. code-block:: text
-
- [
- {
- "directory": ".",
- "command": "<path-to-compiler-executable>/clang++ -std=c++20 M.cppm -c -o M.o",
- "file": "M.cppm",
- "output": "M.o"
- },
- {
- "directory": ".",
- "command": "<path-to-compiler-executable>/clang++ -std=c++20 Impl.cpp -c -o Impl.o",
- "file": "Impl.cpp",
- "output": "Impl.o"
- },
- {
- "directory": ".",
- "command": "<path-to-compiler-executable>/clang++ -std=c++20 impl_part.cppm -c -o impl_part.o",
- "file": "impl_part.cppm",
- "output": "impl_part.o"
- },
- {
- "directory": ".",
- "command": "<path-to-compiler-executable>/clang++ -std=c++20 interface_part.cppm -c -o interface_part.o",
- "file": "interface_part.cppm",
- "output": "interface_part.o"
- },
- {
- "directory": ".",
- "command": "<path-to-compiler-executable>/clang++ -std=c++20 User.cpp -c -o User.o",
- "file": "User.cpp",
- "output": "User.o"
- }
- ]
+```text
+[
+{
+ "directory": ".",
+ "command": "<path-to-compiler-executable>/clang++ -std=c++20 M.cppm -c -o M.o",
+ "file": "M.cppm",
+ "output": "M.o"
+},
+{
+ "directory": ".",
+ "command": "<path-to-compiler-executable>/clang++ -std=c++20 Impl.cpp -c -o Impl.o",
+ "file": "Impl.cpp",
+ "output": "Impl.o"
+},
+{
+ "directory": ".",
+ "command": "<path-to-compiler-executable>/clang++ -std=c++20 impl_part.cppm -c -o impl_part.o",
+ "file": "impl_part.cppm",
+ "output": "impl_part.o"
+},
+{
+ "directory": ".",
+ "command": "<path-to-compiler-executable>/clang++ -std=c++20 interface_part.cppm -c -o interface_part.o",
+ "file": "interface_part.cppm",
+ "output": "interface_part.o"
+},
+{
+ "directory": ".",
+ "command": "<path-to-compiler-executable>/clang++ -std=c++20 User.cpp -c -o User.o",
+ "file": "User.cpp",
+ "output": "User.o"
+}
+]
+```
To get the dependency information in P1689 format, use:
-.. code-block:: console
-
- $ clang-scan-deps -format=p1689 -compilation-database P1689.json
+```console
+$ clang-scan-deps -format=p1689 -compilation-database P1689.json
+```
to get:
-.. code-block:: text
-
- {
- "revision": 0,
- "rules": [
- {
- "primary-output": "Impl.o",
- "requires": [
- {
- "logical-name": "M",
- "source-path": "M.cppm"
- }
- ]
- },
- {
- "primary-output": "M.o",
- "provides": [
- {
- "is-interface": true,
- "logical-name": "M",
- "source-path": "M.cppm"
- }
- ],
- "requires": [
- {
- "logical-name": "M:interface_part",
- "source-path": "interface_part.cppm"
- },
- {
- "logical-name": "M:impl_part",
- "source-path": "impl_part.cppm"
- }
- ]
- },
- {
- "primary-output": "User.o",
- "requires": [
- {
- "logical-name": "M",
- "source-path": "M.cppm"
- },
- {
- "logical-name": "third_party_module"
- }
- ]
- },
- {
- "primary-output": "impl_part.o",
- "provides": [
- {
- "is-interface": false,
- "logical-name": "M:impl_part",
- "source-path": "impl_part.cppm"
- }
- ],
- "requires": [
- {
- "logical-name": "M:interface_part",
- "source-path": "interface_part.cppm"
- }
- ]
- },
- {
- "primary-output": "interface_part.o",
- "provides": [
- {
- "is-interface": true,
- "logical-name": "M:interface_part",
- "source-path": "interface_part.cppm"
- }
- ]
- }
- ],
- "version": 1
- }
+```text
+{
+ "revision": 0,
+ "rules": [
+ {
+ "primary-output": "Impl.o",
+ "requires": [
+ {
+ "logical-name": "M",
+ "source-path": "M.cppm"
+ }
+ ]
+ },
+ {
+ "primary-output": "M.o",
+ "provides": [
+ {
+ "is-interface": true,
+ "logical-name": "M",
+ "source-path": "M.cppm"
+ }
+ ],
+ "requires": [
+ {
+ "logical-name": "M:interface_part",
+ "source-path": "interface_part.cppm"
+ },
+ {
+ "logical-name": "M:impl_part",
+ "source-path": "impl_part.cppm"
+ }
+ ]
+ },
+ {
+ "primary-output": "User.o",
+ "requires": [
+ {
+ "logical-name": "M",
+ "source-path": "M.cppm"
+ },
+ {
+ "logical-name": "third_party_module"
+ }
+ ]
+ },
+ {
+ "primary-output": "impl_part.o",
+ "provides": [
+ {
+ "is-interface": false,
+ "logical-name": "M:impl_part",
+ "source-path": "impl_part.cppm"
+ }
+ ],
+ "requires": [
+ {
+ "logical-name": "M:interface_part",
+ "source-path": "interface_part.cppm"
+ }
+ ]
+ },
+ {
+ "primary-output": "interface_part.o",
+ "provides": [
+ {
+ "is-interface": true,
+ "logical-name": "M:interface_part",
+ "source-path": "interface_part.cppm"
+ }
+ ]
+ }
+ ],
+ "version": 1
+}
+```
See the P1689 paper for the meaning of the fields.
Getting dependency information per file with finer-grained control (such as
scanning generated source files) is possible. For example:
-.. code-block:: console
-
- $ clang-scan-deps -format=p1689 -- <path-to-compiler-executable>/clang++ -std=c++20 impl_part.cppm -c -o impl_part.o
+```console
+$ clang-scan-deps -format=p1689 -- <path-to-compiler-executable>/clang++ -std=c++20 impl_part.cppm -c -o impl_part.o
+```
will produce:
-.. code-block:: text
-
- {
- "revision": 0,
- "rules": [
- {
- "primary-output": "impl_part.o",
- "provides": [
- {
- "is-interface": false,
- "logical-name": "M:impl_part",
- "source-path": "impl_part.cppm"
- }
- ],
- "requires": [
- {
- "logical-name": "M:interface_part"
- }
- ]
- }
- ],
- "version": 1
- }
-
-Individual command line options can be specified after ``--``.
-``clang-scan-deps`` will extract the necessary information from the specified
+```text
+{
+ "revision": 0,
+ "rules": [
+ {
+ "primary-output": "impl_part.o",
+ "provides": [
+ {
+ "is-interface": false,
+ "logical-name": "M:impl_part",
+ "source-path": "impl_part.cppm"
+ }
+ ],
+ "requires": [
+ {
+ "logical-name": "M:interface_part"
+ }
+ ]
+ }
+ ],
+ "version": 1
+}
+```
+
+Individual command line options can be specified after `--`.
+`clang-scan-deps` will extract the necessary information from the specified
options. Note that the path to the compiler executable needs to be specified
-explicitly instead of using ``clang++`` directly.
+explicitly instead of using `clang++` directly.
Users may want the scanner to get the transitive dependency information for
headers. Otherwise, the project has to be scanned twice, once for headers and
-once for modules. To address this, ``clang-scan-deps`` will recognize the
+once for modules. To address this, `clang-scan-deps` will recognize the
specified preprocessor options in the given command line and generate the
corresponding dependency information. For example:
-.. code-block:: console
-
- $ clang-scan-deps -format=p1689 -- ../bin/clang++ -std=c++20 impl_part.cppm -c -o impl_part.o -MD -MT impl_part.ddi -MF impl_part.dep
- $ cat impl_part.dep
+```console
+$ clang-scan-deps -format=p1689 -- ../bin/clang++ -std=c++20 impl_part.cppm -c -o impl_part.o -MD -MT impl_part.ddi -MF impl_part.dep
+$ cat impl_part.dep
+```
will produce:
-.. code-block:: text
-
- impl_part.ddi: \
- /usr/include/bits/wchar.h /usr/include/bits/types/wint_t.h \
- /usr/include/bits/types/mbstate_t.h \
- /usr/include/bits/types/__mbstate_t.h /usr/include/bits/types/__FILE.h \
- /usr/include/bits/types/FILE.h /usr/include/bits/types/locale_t.h \
- /usr/include/bits/types/__locale_t.h \
- ...
+```text
+impl_part.ddi: \
+ /usr/include/bits/wchar.h /usr/include/bits/types/wint_t.h \
+ /usr/include/bits/types/mbstate_t.h \
+ /usr/include/bits/types/__mbstate_t.h /usr/include/bits/types/__FILE.h \
+ /usr/include/bits/types/FILE.h /usr/include/bits/types/locale_t.h \
+ /usr/include/bits/types/__locale_t.h \
+ ...
+```
-When ``clang-scan-deps`` detects the ``-MF`` option, it will try to write the
-dependency information for headers to the file specified by ``-MF``.
+When `clang-scan-deps` detects the `-MF` option, it will try to write the
+dependency information for headers to the file specified by `-MF`.
-Possible Issues: Failed to find system headers
-----------------------------------------------
+### Possible Issues: Failed to find system headers
-If encountering an error like ``fatal error: 'stddef.h' file not found``,
-the specified ``<path-to-compiler-executable>/clang++`` probably refers to a
+If encountering an error like `fatal error: 'stddef.h' file not found`,
+the specified `<path-to-compiler-executable>/clang++` probably refers to a
symlink instead of a real binary. There are four potential solutions to the
problem:
1. Point the specified compiler executable to the real binary instead of the
symlink.
-2. Invoke ``<path-to-compiler-executable>/clang++ -print-resource-dir`` to get
+
+2. Invoke `<path-to-compiler-executable>/clang++ -print-resource-dir` to get
the corresponding resource directory for your compiler and add that
directory to the include search paths manually in the build scripts.
+
3. For build systems that use a compilation database as the input for
- ``clang-scan-deps``, the build system can add the
- ``--resource-dir-recipe invoke-compiler`` option when executing
- ``clang-scan-deps`` to calculate the resource directory dynamically.
- The calculation happens only once for a unique ``<path-to-compiler-executable>/clang++``.
-4. For build systems that invoke ``clang-scan-deps`` per file, repeatedly
+ `clang-scan-deps`, the build system can add the
+ `--resource-dir-recipe invoke-compiler` option when executing
+ `clang-scan-deps` to calculate the resource directory dynamically.
+ The calculation happens only once for a unique `<path-to-compiler-executable>/clang++`.
+
+4. For build systems that invoke `clang-scan-deps` per file, repeatedly
calculating the resource directory may be inefficient. In such cases, the
build system can cache the resource directory and specify
- ``-resource-dir <resource-dir>`` explicitly, as in:
-
- .. code-block:: console
-
- $ clang-scan-deps -format=p1689 -- <path-to-compiler-executable>/clang++ -std=c++20 -resource-dir <resource-dir> mod.cppm -c -o mod.o
+ `-resource-dir <resource-dir>` explicitly, as in:
+ ```console
+ $ clang-scan-deps -format=p1689 -- <path-to-compiler-executable>/clang++ -std=c++20 -resource-dir <resource-dir> mod.cppm -c -o mod.o
+ ```
-Import modules with clang-repl
-==============================
+## Import modules with clang-repl
-``clang-repl`` supports importing C++20 named modules. For example:
+`clang-repl` supports importing C++20 named modules. For example:
-.. code-block:: c++
-
- // M.cppm
- export module M;
- export const char* Hello() {
- return "Hello Interpreter for Modules!";
- }
+```c++
+// M.cppm
+export module M;
+export const char* Hello() {
+ return "Hello Interpreter for Modules!";
+}
+```
The named module still needs to be compiled ahead of time.
-.. code-block:: console
-
- $ clang++ -std=c++20 M.cppm --precompile -o M.pcm
- $ clang++ M.pcm -c -o M.o
- $ clang++ -shared M.o -o libM.so
+```console
+$ clang++ -std=c++20 M.cppm --precompile -o M.pcm
+$ clang++ M.pcm -c -o M.o
+$ clang++ -shared M.o -o libM.so
+```
Note that the module unit needs to be compiled as a dynamic library so that
-``clang-repl`` can load the object files of the module units. Then it is
-possible to import module ``M`` in clang-repl.
-
-.. code-block:: console
+`clang-repl` can load the object files of the module units. Then it is
+possible to import module `M` in clang-repl.
- $ clang-repl -Xcc=-std=c++20 -Xcc=-fprebuilt-module-path=.
- # We need to load the dynamic library first before importing the modules.
- clang-repl> %lib libM.so
- clang-repl> import M;
- clang-repl> extern "C" int printf(const char *, ...);
- clang-repl> printf("%s\n", Hello());
- Hello Interpreter for Modules!
- clang-repl> %quit
+```console
+$ clang-repl -Xcc=-std=c++20 -Xcc=-fprebuilt-module-path=.
+# We need to load the dynamic library first before importing the modules.
+clang-repl> %lib libM.so
+clang-repl> import M;
+clang-repl> extern "C" int printf(const char *, ...);
+clang-repl> printf("%s\n", Hello());
+Hello Interpreter for Modules!
+clang-repl> %quit
+```
-Possible Questions
-==================
+## Possible Questions
-How modules speed up compilation
---------------------------------
+### How modules speed up compilation
A classic theory for the reason why modules speed up the compilation is: if
-there are ``n`` headers and ``m`` source files and each header is included by
-each source file, then the complexity of the compilation is ``O(n*m)``.
-However, if there are ``n`` module interfaces and ``m`` source files, the
-complexity of the compilation is ``O(n+m)``. Therefore, using modules would be
+there are `n` headers and `m` source files and each header is included by
+each source file, then the complexity of the compilation is `O(n*m)`.
+However, if there are `n` module interfaces and `m` source files, the
+complexity of the compilation is `O(n+m)`. Therefore, using modules would be
a significant improvement at scale. More simply, use of modules causes many of
the redundant compilations to no longer be necessary.
While this is accurate at a high level, this depends greatly on the
optimization level, as illustrated below.
-First is ``-O0``. The compilation process is described in the following graph.
+First is `-O0`. The compilation process is described in the following graph.
-.. code-block:: none
+```none
+├-------------frontend----------┼-------------middle end----------------┼----backend----┤
+│ │ │ │
+└---parsing----sema----codegen--┴----- transformations ---- codegen ----┴---- codegen --┘
- ├-------------frontend----------┼-------------middle end----------------┼----backend----┤
- │ │ │ │
- └---parsing----sema----codegen--┴----- transformations ---- codegen ----┴---- codegen --┘
+├---------------------------------------------------------------------------------------┐
+| │
+| source file │
+| │
+└---------------------------------------------------------------------------------------┘
- ├---------------------------------------------------------------------------------------┐
- | │
- | source file │
- | │
- └---------------------------------------------------------------------------------------┘
-
- ├--------┐
- │ │
- │imported│
- │ │
- │ code │
- │ │
- └--------┘
+ ├--------┐
+ │ │
+ │imported│
+ │ │
+ │ code │
+ │ │
+ └--------┘
+```
In this case, the source file (which could be a non-module unit or a module
unit) would get processed by the entire pipeline. However, the imported code
@@ -2460,29 +2389,29 @@ lookup, overload resolution, and template instantiation. All of these processes
are fast relative to the whole compilation process. More importantly, the
imported code only needs to be processed once during frontend code generation,
as well as the whole middle end and backend. So we could get a big win for the
-compilation time in ``-O0``.
+compilation time in `-O0`.
-But with optimizations, things are different (the ``code generation`` part for
+But with optimizations, things are different (the `code generation` part for
each end is omitted due to limited space):
-.. code-block:: none
-
- ├-------- frontend ---------┼--------------- middle end --------------------┼------ backend ----┤
- │ │ │ │
- └--- parsing ---- sema -----┴--- optimizations --- IPO ---- optimizations---┴--- optimizations -┘
-
- ├-----------------------------------------------------------------------------------------------┐
- │ │
- │ source file │
- │ │
- └-----------------------------------------------------------------------------------------------┘
- ├---------------------------------------┐
- │ │
- │ │
- │ imported code │
- │ │
- │ │
- └---------------------------------------┘
+```none
+├-------- frontend ---------┼--------------- middle end --------------------┼------ backend ----┤
+│ │ │ │
+└--- parsing ---- sema -----┴--- optimizations --- IPO ---- optimizations---┴--- optimizations -┘
+
+├-----------------------------------------------------------------------------------------------┐
+│ │
+│ source file │
+│ │
+└-----------------------------------------------------------------------------------------------┘
+ ├---------------------------------------┐
+ │ │
+ │ │
+ │ imported code │
+ │ │
+ │ │
+ └---------------------------------------┘
+```
It would be very unfortunate if we end up with worse performance when using
modules. The main concern is that when a source file is compiled, the compiler
@@ -2496,17 +2425,17 @@ part in whole compilation process. So from this perspective, it might not be
possible to get the compile time improvements described, but there could be
time savings for optimizations after IPO and the whole backend.
-Overall, at ``-O0`` the implementations of functions defined in a module will
+Overall, at `-O0` the implementations of functions defined in a module will
not impact module users, but at higher optimization levels the definitions of
such functions are provided to user compilations for the purposes of
optimization (but definitions of these functions are still not included in the
use's object file). This means the build speedup at higher optimization levels
-may be lower than expected given ``-O0`` experience, but does provide more
+may be lower than expected given `-O0` experience, but does provide more
optimization opportunities.
-Interoperability with Clang Modules
------------------------------------
+### Interoperability with Clang Modules
We **wish** to support Clang modules and standard C++ modules at the same time,
but the mixing them together is not well used/tested yet. Please file new
GitHub issues as you find interoperability problems.
+
diff --git a/clang/docs/StructureProtection.md b/clang/docs/StructureProtection.md
index a5ca1e64c35b9..8d541c0e7a206 100644
--- a/clang/docs/StructureProtection.md
+++ b/clang/docs/StructureProtection.md
@@ -1,50 +1,43 @@
-====================
-Structure Protection
-====================
+# Structure Protection
-.. contents::
- :local:
+```{contents}
+:local: true
+```
-
-Introduction
-============
+## Introduction
Structure protection is an *experimental* mitigation
against use-after-free vulnerabilities. For
-more information, please see the original `RFC
-<https://discourse.llvm.org/t/rfc-structure-protection-a-family-of-uaf-mitigation-techniques/85555>`_.
+more information, please see the original [RFC](https://discourse.llvm.org/t/rfc-structure-protection-a-family-of-uaf-mitigation-techniques/85555).
An independent set of documentation will be contributed when the feature
is promoted to stable.
-Usage
-=====
+## Usage
To use structure protection, build your program using one or more of these flags:
-- ``-fexperimental-allow-pointer-field-protection-attr``: Makes the
- ``[[clang::pointer_field_protection]]`` attribute described below
+- `-fexperimental-allow-pointer-field-protection-attr`: Makes the
+ `[[clang::pointer_field_protection]]` attribute described below
available for use in code. Without this flag, use of the attribute will
cause an error. This flag acts as a guard against use of the feature
before it is stabilized. When the feature is stabilized, the intent
is that this flag will become a no-op and the attribute will always
be available.
-
-- ``-fexperimental-pointer-field-protection-abi``: Enable pointer
+- `-fexperimental-pointer-field-protection-abi`: Enable pointer
field protection on all types that are not considered standard-layout
according to the C++ rules for standard layout. Because this
flag changes the C++ ABI, we refer to this as the pointer
field protection ABI. Specifying this flag also defines the
- predefined macro ``__POINTER_FIELD_PROTECTION_ABI__``. Implies
- ``-fexperimental-allow-pointer-field-protection-attr``.
-
-- ``-fexperimental-pointer-field-protection-tagged``: On architectures
+ predefined macro `__POINTER_FIELD_PROTECTION_ABI__`. Implies
+ `-fexperimental-allow-pointer-field-protection-attr`.
+- `-fexperimental-pointer-field-protection-tagged`: On architectures
that support it (currently only AArch64), for types that are not
considered trivially copyable, use the address of the object to compute
the pointer encoding. Specifying this flag also defines the predefined
- macro ``__POINTER_FIELD_PROTECTION_TAGGED__``.
+ macro `__POINTER_FIELD_PROTECTION_TAGGED__`.
It is also possible to specify the attribute
-``[[clang::pointer_field_protection]]`` on a struct type to opt the
+`[[clang::pointer_field_protection]]` on a struct type to opt the
struct's pointer fields into pointer field protection, even if the type is
standard layout or none of the command line flags are specified. Note that
this means that the type will not comply with pointer interconvertibility
@@ -55,41 +48,40 @@ members.
In order to avoid ABI breakage, the entire C++ part
of the program must be built with a consistent set of
-``-fexperimental-pointer-field-protection*`` flags, and the C++ standard
+`-fexperimental-pointer-field-protection*` flags, and the C++ standard
library must also be built with the same flags and statically linked
into the program.
To build libc++ with pointer field protection support, pass the following
CMake flags:
-.. code-block:: console
+```console
+"-DRUNTIMES_${triple}_LIBCXXABI_ENABLE_SHARED=OFF" \
+"-DRUNTIMES_${triple}_LIBCXX_USE_COMPILER_RT=ON" \
+"-DRUNTIMES_${triple}_LIBCXX_PFP=untagged" \
+"-DRUNTIMES_${triple}_LIBCXX_ENABLE_SHARED=OFF" \
+"-DRUNTIMES_${triple}_LIBCXX_TEST_CONFIG=llvm-libc++-static.cfg.in" \
+"-DRUNTIMES_${triple}_LIBUNWIND_ENABLE_SHARED=OFF" \
+```
- "-DRUNTIMES_${triple}_LIBCXXABI_ENABLE_SHARED=OFF" \
- "-DRUNTIMES_${triple}_LIBCXX_USE_COMPILER_RT=ON" \
- "-DRUNTIMES_${triple}_LIBCXX_PFP=untagged" \
- "-DRUNTIMES_${triple}_LIBCXX_ENABLE_SHARED=OFF" \
- "-DRUNTIMES_${triple}_LIBCXX_TEST_CONFIG=llvm-libc++-static.cfg.in" \
- "-DRUNTIMES_${triple}_LIBUNWIND_ENABLE_SHARED=OFF" \
-
-where ``${triple}`` is your target triple, such as
-``aarch64-unknown-linux``.
+where `${triple}` is your target triple, such as
+`aarch64-unknown-linux`.
The resulting toolchain may then be used to build programs
-with pointer field protection by passing ``-stdlib=libc++
--fexperimental-pointer-field-protection-abi`` at compile time
-and ``-Wl,-Bstatic -lc++ -lc++abi -Wl,-Bdynamic -lm -fuse-ld=lld
--static-libstdc++`` at link time.
+with pointer field protection by passing `-stdlib=libc++
+-fexperimental-pointer-field-protection-abi` at compile time
+and `-Wl,-Bstatic -lc++ -lc++abi -Wl,-Bdynamic -lm -fuse-ld=lld
+-static-libstdc++` at link time.
-Implementation
-==============
+## Implementation
TODO: Document everything else.
The implementation uses deactivation symbols as a mechanism for
globally disabling pointer field protection for a particular field. For
-more information, see the `deactivation symbol section of the LangRef
-<https://llvm.org/docs/LangRef.html#deactivation-symbol-operand-bundles>`_.
+more information, see the [deactivation symbol section of the LangRef](https://llvm.org/docs/LangRef.html#deactivation-symbol-operand-bundles).
These symbols are named as follows:
-``__pfp_ds_`` followed by the ABI encoding of the type's RTTI object
-symbol name followed by ``.`` followed by the name of the field.
+`__pfp_ds_` followed by the ABI encoding of the type's RTTI object
+symbol name followed by `.` followed by the name of the field.
+
diff --git a/clang/docs/ThinLTO.md b/clang/docs/ThinLTO.md
index 8cb3e0b2b0d11..905874e1c538a 100644
--- a/clang/docs/ThinLTO.md
+++ b/clang/docs/ThinLTO.md
@@ -1,12 +1,10 @@
-=======
-ThinLTO
-=======
+# ThinLTO
-.. contents::
- :local:
+```{contents}
+:local: true
+```
-Introduction
-============
+## Introduction
*ThinLTO* compilation is a new type of LTO that is both scalable and
incremental. *LTO* (Link Time Optimization) achieves better
@@ -24,106 +22,101 @@ whole-program analysis is then performed on the combined summary index.
However, all transformations, including function importing, occur
later when the modules are optimized in fully parallel backends.
-By default, linkers_ that support ThinLTO are set up to launch
+By default, [linkers] that support ThinLTO are set up to launch
the ThinLTO backends in threads. So the usage model is not affected
as the distinction between the fast serial thin link step and the backends
is transparent to the user.
For more information on the ThinLTO design and current performance,
-see the LLVM blog post `ThinLTO: Scalable and Incremental LTO
-<http://blog.llvm.org/2016/06/thinlto-scalable-and-incremental-lto.html>`_.
+see the LLVM blog post [ThinLTO: Scalable and Incremental LTO](http://blog.llvm.org/2016/06/thinlto-scalable-and-incremental-lto.html).
While tuning is still in progress, results in the blog post show that
ThinLTO already performs well compared to LTO, in many cases matching
the performance improvement.
-Current Status
-==============
+## Current Status
-Clang/LLVM
-----------
-.. _compiler:
+### Clang/LLVM
+
+(compiler)=
The 3.9 release of clang includes ThinLTO support. However, ThinLTO
is under active development, and new features, improvements and bugfixes
are being added for the next release. For the latest ThinLTO support,
-`build a recent version of clang and LLVM
-<https://llvm.org/docs/CMake.html>`_.
+[build a recent version of clang and LLVM](https://llvm.org/docs/CMake.html).
+
+### Linkers
-Linkers
--------
-.. _linkers:
-.. _linker:
+(linkers-1)=
+
+(linker)=
ThinLTO is currently supported for the following linkers:
- **gold (via the gold-plugin)**:
Similar to monolithic LTO, this requires using
- a `gold linker configured with plugins enabled
- <https://llvm.org/docs/GoldPlugin.html>`_.
+ a [gold linker configured with plugins enabled](https://llvm.org/docs/GoldPlugin.html).
- **ld64**:
- Starting with `Xcode 8 <https://developer.apple.com/xcode/>`_.
+ Starting with [Xcode 8](https://developer.apple.com/xcode/).
- **lld**:
Starting with r284050 for ELF, r298942 for COFF.
-Usage
-=====
+## Usage
-Basic
------
+### Basic
To utilize ThinLTO, simply add the -flto=thin option to compile and link. E.g.
-.. code-block:: console
-
- % clang -flto=thin -O2 file1.c file2.c -c
- % clang -flto=thin -O2 file1.o file2.o -o a.out
+```console
+% clang -flto=thin -O2 file1.c file2.c -c
+% clang -flto=thin -O2 file1.o file2.o -o a.out
+```
When using lld-link, the -flto option need only be added to the compile step:
-.. code-block:: console
-
- % clang-cl -flto=thin -O2 -c file1.c file2.c
- % lld-link /out:a.exe file1.obj file2.obj
+```console
+% clang-cl -flto=thin -O2 -c file1.c file2.c
+% lld-link /out:a.exe file1.obj file2.obj
+```
As mentioned earlier, by default the linkers will launch the ThinLTO backend
threads in parallel, passing the resulting native object files back to the
-linker for the final native link. As such, the usage model is the same as
+linker for the final native link. As such, the usage model is the same as
non-LTO.
With gold, if you see an error during the link of the form:
-.. code-block:: console
-
- /usr/bin/ld: error: /path/to/clang/bin/../lib/LLVMgold.so: could not load plugin library: /path/to/clang/bin/../lib/LLVMgold.so: cannot open shared object file: No such file or directory
+```console
+/usr/bin/ld: error: /path/to/clang/bin/../lib/LLVMgold.so: could not load plugin library: /path/to/clang/bin/../lib/LLVMgold.so: cannot open shared object file: No such file or directory
+```
Then either gold was not configured with plugins enabled, or clang
-was not built with ``-DLLVM_BINUTILS_INCDIR`` set properly. See
+was not built with `-DLLVM_BINUTILS_INCDIR` set properly. See
the instructions for the
-`LLVM gold plugin <https://llvm.org/docs/GoldPlugin.html#how-to-build-it>`_.
+[LLVM gold plugin](https://llvm.org/docs/GoldPlugin.html#how-to-build-it).
+
+### Controlling Backend Parallelism
-Controlling Backend Parallelism
--------------------------------
-.. _parallelism:
+(parallelism)=
By default, the ThinLTO link step will launch as many
threads in parallel as there are cores. If the number of
cores can't be computed for the architecture, then it will launch
-``std::thread::hardware_concurrency`` number of threads in parallel.
+`std::thread::hardware_concurrency` number of threads in parallel.
For machines with hyper-threading, this is the total number of
virtual cores. For some applications and machine configurations this
may be too aggressive, in which case the amount of parallelism can
-be reduced to ``N`` via:
+be reduced to `N` via:
- gold:
- ``-Wl,-plugin-opt,jobs=N``
+ `-Wl,-plugin-opt,jobs=N`
- ld64:
- ``-Wl,-mllvm,-threads=N``
+ `-Wl,-mllvm,-threads=N`
- ld.lld, ld64.lld:
- ``-Wl,--thinlto-jobs=N``
+ `-Wl,--thinlto-jobs=N`
- lld-link:
- ``/opt:lldltojobs=N``
+ `/opt:lldltojobs=N`
-Other possible values for ``N`` are:
+Other possible values for `N` are:
- 0:
Use one thread per physical core (default)
@@ -132,25 +125,24 @@ Other possible values for ``N`` are:
- all:
Use one thread per logical core (uses all hyper-threads)
-Incremental
------------
-.. _incremental:
+### Incremental
+
+(incremental-1)=
ThinLTO supports fast incremental builds through the use of a cache,
which currently must be enabled through a linker option.
- gold (as of LLVM 4.0):
- ``-Wl,-plugin-opt,cache-dir=/path/to/cache``
+ `-Wl,-plugin-opt,cache-dir=/path/to/cache`
- ld64 (supported since clang 3.9 and Xcode 8) and Mach-O ld64.lld (as of LLVM
15.0):
- ``-Wl,-cache_path_lto,/path/to/cache``
+ `-Wl,-cache_path_lto,/path/to/cache`
- ELF ld.lld (as of LLVM 5.0):
- ``-Wl,--thinlto-cache-dir=/path/to/cache``
+ `-Wl,--thinlto-cache-dir=/path/to/cache`
- COFF lld-link (as of LLVM 6.0):
- ``/lldltocache:/path/to/cache``
+ `/lldltocache:/path/to/cache`
-Cache Pruning
--------------
+### Cache Pruning
To help keep the size of the cache under control, ThinLTO supports cache
pruning. Cache pruning is supported with gold, ld64, and lld, but currently only
@@ -158,138 +150,132 @@ gold and lld allow you to control the policy with a policy string. The cache
policy must be specified with a linker option.
- gold (as of LLVM 6.0):
- ``-Wl,-plugin-opt,cache-policy=POLICY``
+ `-Wl,-plugin-opt,cache-policy=POLICY`
- ELF ld.lld (as of LLVM 5.0), Mach-O ld64.lld (as of LLVM 15.0):
- ``-Wl,--thinlto-cache-policy=POLICY``
+ `-Wl,--thinlto-cache-policy=POLICY`
- COFF lld-link (as of LLVM 6.0):
- ``/lldltocachepolicy:POLICY``
+ `/lldltocachepolicy:POLICY`
-A policy string is a series of key-value pairs separated by ``:`` characters.
+A policy string is a series of key-value pairs separated by `:` characters.
Possible key-value pairs are:
-- ``cache_size=X%``: The maximum size for the cache directory is ``X`` percent
+- `cache_size=X%`: The maximum size for the cache directory is `X` percent
of the available space on the disk. Set to 100 to indicate no limit,
50 to indicate that the cache size will not be left over half the available
disk space. A value over 100 is invalid. A value of 0 disables the percentage
size-based pruning. The default is 75%.
-- ``cache_size_bytes=X``, ``cache_size_bytes=Xk``, ``cache_size_bytes=Xm``,
- ``cache_size_bytes=Xg``:
- Sets the maximum size for the cache directory to ``X`` bytes (or KB, MB,
+- `cache_size_bytes=X`, `cache_size_bytes=Xk`, `cache_size_bytes=Xm`,
+ `cache_size_bytes=Xg`:
+ Sets the maximum size for the cache directory to `X` bytes (or KB, MB,
GB respectively). A value over the amount of available space on the disk
will be reduced to the amount of available space. A value of 0 disables
the byte size-based pruning. The default is no byte size-based pruning.
Note that ThinLTO will apply both size-based pruning policies simultaneously,
and changing one does not affect the other. For example, a policy of
- ``cache_size_bytes=1g`` on its own will cause both the 1GB and default 75%
- policies to be applied unless the default ``cache_size`` is overridden.
+ `cache_size_bytes=1g` on its own will cause both the 1GB and default 75%
+ policies to be applied unless the default `cache_size` is overridden.
-- ``cache_size_files=X``:
+- `cache_size_files=X`:
Set the maximum number of files in the cache directory. Set to 0 to indicate
no limit. The default is 1000000 files.
-- ``prune_after=Xs``, ``prune_after=Xm``, ``prune_after=Xh``: Sets the
- expiration time for cache files to ``X`` seconds (or minutes, hours
- respectively). When a file hasn't been accessed for ``prune_after`` seconds,
+- `prune_after=Xs`, `prune_after=Xm`, `prune_after=Xh`: Sets the
+ expiration time for cache files to `X` seconds (or minutes, hours
+ respectively). When a file hasn't been accessed for `prune_after` seconds,
it is removed from the cache. A value of 0 disables the expiration-based
pruning. The default is 1 week.
-- ``prune_interval=Xs``, ``prune_interval=Xm``, ``prune_interval=Xh``:
- Sets the pruning interval to ``X`` seconds (or minutes, hours
+- `prune_interval=Xs`, `prune_interval=Xm`, `prune_interval=Xh`:
+ Sets the pruning interval to `X` seconds (or minutes, hours
respectively). This is intended to be used to avoid scanning the directory
too often. It does not impact the decision of which files to prune. A
value of 0 forces the scan to occur. The default is every 20 minutes.
-Clang Bootstrap
----------------
+### Clang Bootstrap
-To `bootstrap clang/LLVM <https://llvm.org/docs/AdvancedBuilds.html#bootstrap-builds>`_
+To [bootstrap clang/LLVM](https://llvm.org/docs/AdvancedBuilds.html#bootstrap-builds)
with ThinLTO, follow these steps:
-1. The host compiler_ must be a version of clang that supports ThinLTO.
-#. The host linker_ must support ThinLTO (and in the case of gold, must be
- `configured with plugins enabled <https://llvm.org/docs/GoldPlugin.html>`_).
-#. Use the following additional `CMake variables
- <https://llvm.org/docs/CMake.html#options-and-variables>`_
+1. The host [compiler] must be a version of clang that supports ThinLTO.
+2. The host [linker] must support ThinLTO (and in the case of gold, must be
+ [configured with plugins enabled](https://llvm.org/docs/GoldPlugin.html)).
+3. Use the following additional [CMake variables](https://llvm.org/docs/CMake.html#options-and-variables)
when configuring the bootstrap compiler build:
- * ``-DLLVM_ENABLE_LTO=Thin``
- * ``-DCMAKE_C_COMPILER=/path/to/host/clang``
- * ``-DCMAKE_CXX_COMPILER=/path/to/host/clang++``
- * ``-DCMAKE_RANLIB=/path/to/host/llvm-ranlib``
- * ``-DCMAKE_AR=/path/to/host/llvm-ar``
-
- Or, on Windows:
-
- * ``-DLLVM_ENABLE_LTO=Thin``
- * ``-DCMAKE_C_COMPILER=/path/to/host/clang-cl.exe``
- * ``-DCMAKE_CXX_COMPILER=/path/to/host/clang-cl.exe``
- * ``-DCMAKE_LINKER=/path/to/host/lld-link.exe``
- * ``-DCMAKE_RANLIB=/path/to/host/llvm-ranlib.exe``
- * ``-DCMAKE_AR=/path/to/host/llvm-ar.exe``
-
-#. To use additional linker arguments for controlling the backend
- parallelism_ or enabling incremental_ builds of the bootstrap compiler,
+> - `-DLLVM_ENABLE_LTO=Thin`
+> - `-DCMAKE_C_COMPILER=/path/to/host/clang`
+> - `-DCMAKE_CXX_COMPILER=/path/to/host/clang++`
+> - `-DCMAKE_RANLIB=/path/to/host/llvm-ranlib`
+> - `-DCMAKE_AR=/path/to/host/llvm-ar`
+>
+> Or, on Windows:
+>
+> - `-DLLVM_ENABLE_LTO=Thin`
+> - `-DCMAKE_C_COMPILER=/path/to/host/clang-cl.exe`
+> - `-DCMAKE_CXX_COMPILER=/path/to/host/clang-cl.exe`
+> - `-DCMAKE_LINKER=/path/to/host/lld-link.exe`
+> - `-DCMAKE_RANLIB=/path/to/host/llvm-ranlib.exe`
+> - `-DCMAKE_AR=/path/to/host/llvm-ar.exe`
+
+1. To use additional linker arguments for controlling the backend
+ [parallelism] or enabling [incremental] builds of the bootstrap compiler,
after configuring the build, modify the resulting CMakeCache.txt file in the
build directory. Specify any additional linker options after
- ``CMAKE_EXE_LINKER_FLAGS:STRING=``. Note the configure may fail if
+ `CMAKE_EXE_LINKER_FLAGS:STRING=`. Note the configure may fail if
linker plugin options are instead specified directly in the previous step.
-The ``BOOTSTRAP_LLVM_ENABLE_LTO=Thin`` will enable ThinLTO for stage 2 and
+The `BOOTSTRAP_LLVM_ENABLE_LTO=Thin` will enable ThinLTO for stage 2 and
stage 3 in case the compiler used for stage 1 does not support the ThinLTO
option.
-Integrated Distributed ThinLTO (DTLTO)
---------------------------------------
+### Integrated Distributed ThinLTO (DTLTO)
Integrated Distributed ThinLTO (DTLTO) enables the distribution of backend
ThinLTO compilations via external distribution systems, such as Incredibuild,
during the traditional link step.
-The implementation is documented here: https://llvm.org/docs/DTLTO.html.
+The implementation is documented here: <https://llvm.org/docs/DTLTO.html>.
-Command-Line Options
-^^^^^^^^^^^^^^^^^^^^
+#### Command-Line Options
-DTLTO requires the LLD linker (``-fuse-ld=lld``).
+DTLTO requires the LLD linker (`-fuse-ld=lld`).
-``-fthinlto-distributor=<path>``
- - Specifies the ``<path>`` to the distributor process executable for DTLTO.
- - If specified, ThinLTO backend compilations will be distributed by LLD.
+`-fthinlto-distributor=<path>`
+: - Specifies the `<path>` to the distributor process executable for DTLTO.
+ - If specified, ThinLTO backend compilations will be distributed by LLD.
-``-Xthinlto-distributor=<arg>``
- - Passes ``<arg>`` to the distributor process (see ``-fthinlto-distributor=``).
- - Can be specified multiple times to pass multiple options.
- - Multiple options can also be specified by separating them with commas.
+`-Xthinlto-distributor=<arg>`
+: - Passes `<arg>` to the distributor process (see `-fthinlto-distributor=`).
+ - Can be specified multiple times to pass multiple options.
+ - Multiple options can also be specified by separating them with commas.
-If ``-fthinlto-distributor=`` is specified, Clang supplies the path to a
+If `-fthinlto-distributor=` is specified, Clang supplies the path to a
compiler to be executed remotely to perform the ThinLTO backend
compilations. Currently, this is Clang itself.
-Usage
-^^^^^
+#### Usage
Compilation is unchanged from ThinLTO. DTLTO options need to supplied for the link step:
-.. code-block:: console
-
- % clang -flto=thin -fthinlto-distributor=distribute.sh -Xthinlto-distributor=--verbose,--j10 -fuse-ld=lld file1.o file2.o
- % clang -flto=thin -fthinlto-distributor=$(which python) -Xthinlto-distributor=distribute.py -fuse-ld=lld file1.o file2.o
+```console
+% clang -flto=thin -fthinlto-distributor=distribute.sh -Xthinlto-distributor=--verbose,--j10 -fuse-ld=lld file1.o file2.o
+% clang -flto=thin -fthinlto-distributor=$(which python) -Xthinlto-distributor=distribute.py -fuse-ld=lld file1.o file2.o
+```
When using lld-link:
-.. code-block:: console
-
- % lld-link /out:a.exe file1.obj file2.obj /thinlto-distributor:distribute.exe /thinlto-remote-compiler:${LLVM}\bin\clang.exe /thinlto-distributor-arg:--verbose
+```console
+% lld-link /out:a.exe file1.obj file2.obj /thinlto-distributor:distribute.exe /thinlto-remote-compiler:${LLVM}\bin\clang.exe /thinlto-distributor-arg:--verbose
+```
Note that currently, DTLTO is only supported in some LLD flavors. Support can
be added to other LLD flavours in the future.
-See `DTLTO <https://lld.llvm.org/DTLTO.html>`_ for more information.
+See [DTLTO](https://lld.llvm.org/DTLTO.html) for more information.
+
+## More Information
-More Information
-================
+- From LLVM project blog:
+ [ThinLTO: Scalable and Incremental LTO](http://blog.llvm.org/2016/06/thinlto-scalable-and-incremental-lto.html)
-* From LLVM project blog:
- `ThinLTO: Scalable and Incremental LTO
- <http://blog.llvm.org/2016/06/thinlto-scalable-and-incremental-lto.html>`_
diff --git a/clang/docs/UsersManual.md b/clang/docs/UsersManual.md
index cabbd22b69f2e..8aaeefbf6b426 100644
--- a/clang/docs/UsersManual.md
+++ b/clang/docs/UsersManual.md
@@ -1,49 +1,49 @@
-============================
-Clang Compiler User's Manual
-============================
+# Clang Compiler User's Manual
+```{eval-rst}
.. include:: <isonum.txt>
+```
-.. contents::
- :local:
+```{contents}
+:local: true
+```
-Introduction
-============
+## Introduction
The Clang Compiler is an open-source compiler for the C family of
programming languages, aiming to be the best-in-class implementation of
these languages. Clang builds on the LLVM optimizer and code generator,
allowing it to provide high-quality optimization and code generation
support for many targets. For more general information, please see the
-`Clang Web Site <https://clang.llvm.org>`_ or the `LLVM Web
-Site <https://llvm.org>`_.
+[Clang Web Site](https://clang.llvm.org) or the [LLVM Web
+Site](https://llvm.org).
This document describes important notes about using Clang as a compiler
for an end-user, documenting the supported features, command line
options, etc. If you are interested in using Clang to build a tool that
-processes code, please see :doc:`InternalsManual`. If you are interested in the
-`Clang Static Analyzer <https://clang-analyzer.llvm.org>`_, please see its web
+processes code, please see {doc}`InternalsManual`. If you are interested in the
+[Clang Static Analyzer](https://clang-analyzer.llvm.org), please see its web
page.
Clang is one component in a complete toolchain for C family languages.
A separate document describes the other pieces necessary to
-:doc:`assemble a complete toolchain <Toolchain>`.
+{doc}`assemble a complete toolchain <Toolchain>`.
Clang is designed to support the C family of programming languages,
-which includes :ref:`C <c>`, :ref:`Objective-C <objc>`, :ref:`C++ <cxx>`, and
-:ref:`Objective-C++ <objcxx>` as well as many dialects of those. For
+which includes {ref}`C <c>`, {ref}`Objective-C <objc>`, {ref}`C++ <cxx>`, and
+{ref}`Objective-C++ <objcxx>` as well as many dialects of those. For
language-specific information, please see the corresponding language
specific section:
-- :ref:`C Language <c>`: K&R C, ANSI C89, ISO C90, C95 (C90+AMD1), C99 (+TC1,
- TC2, TC3), C11, C17, C23, and C2y.
-- :ref:`Objective-C Language <objc>`: ObjC 1, ObjC 2, ObjC 2.1, plus
- variants depending on base language.
-- :ref:`C++ Language <cxx>`: C++98, C++03, C++11, C++14, C++17, C++20, C++23,
- C++26, and C++29.
-- :ref:`Objective C++ Language <objcxx>`
-- :ref:`OpenCL Kernel Language <opencl>`: OpenCL C 1.0, 1.1, 1.2, 2.0, 3.0,
- and C++ for OpenCL 1.0 and 2021.
+- {ref}`C Language <c>`: K&R C, ANSI C89, ISO C90, C95 (C90+AMD1), C99 (+TC1,
+ TC2, TC3), C11, C17, C23, and C2y.
+- {ref}`Objective-C Language <objc>`: ObjC 1, ObjC 2, ObjC 2.1, plus
+ variants depending on base language.
+- {ref}`C++ Language <cxx>`: C++98, C++03, C++11, C++14, C++17, C++20, C++23,
+ C++26, and C++29.
+- {ref}`Objective C++ Language <objcxx>`
+- {ref}`OpenCL Kernel Language <opencl>`: OpenCL C 1.0, 1.1, 1.2, 2.0, 3.0,
+ and C++ for OpenCL 1.0 and 2021.
In addition to these base languages and their dialects, Clang supports a
broad variety of language extensions, which are documented in the
@@ -53,139 +53,162 @@ as to improve functionality through Clang-specific features. The Clang
driver and language features are intentionally designed to be as
compatible with the GNU GCC compiler as reasonably possible, easing
migration from GCC to Clang. In most cases, code "just works".
-Clang also provides an alternative driver, :ref:`clang-cl`, that is designed
+Clang also provides an alternative driver, {ref}`clang-cl`, that is designed
to be compatible with the Visual C++ compiler, cl.exe.
In addition to language-specific features, Clang has a variety of
features that depend on what CPU architecture or operating system is
-being compiled for. Please see the :ref:`Target-Specific Features and
+being compiled for. Please see the {ref}`Target-Specific Features and
Limitations <target_features>` section for more details.
-.. _terminology:
+(terminology)=
-Terminology
------------
-* Lexer -- the part of the compiler responsible for converting source code into
+### Terminology
+
+- Lexer -- the part of the compiler responsible for converting source code into
abstract representations called tokens.
-* Preprocessor -- the part of the compiler responsible for in-place textual
+- Preprocessor -- the part of the compiler responsible for in-place textual
replacement of source constructs. When the lexer is required to produce a
token, it will run the preprocessor while determining which token to produce.
In other words, when the lexer encounters something like `#include` or a macro
name, the preprocessor will be used to perform the inclusion or expand the
macro name into its replacement list, and return the resulting non-preprocessor
token.
-* Parser -- the part of the compiler responsible for determining syntactic
+- Parser -- the part of the compiler responsible for determining syntactic
correctness of the source code. The parser will request tokens from the lexer
and after performing semantic analysis of the production, generates an
abstract representation of the source called an AST.
-* Sema -- the part of the compiler responsible for determining semantic
+- Sema -- the part of the compiler responsible for determining semantic
correctness of the source code. It is closely related to the parser and is
where many diagnostics are produced.
-* Diagnostic -- a message to the user about properties of the source code. For
+- Diagnostic -- a message to the user about properties of the source code. For
example, errors or warnings and their associated notes.
-* Undefined behavior -- behavior for which the standard imposes no requirements
+- Undefined behavior -- behavior for which the standard imposes no requirements
on how the code behaves. Generally speaking, undefined behavior is a bug in
the user's code. However, it can also be a place for the compiler to define
the behavior, called an extension.
-* Optimizer -- the part of the compiler responsible for transforming code to
+- Optimizer -- the part of the compiler responsible for transforming code to
have better performance characteristics without changing the semantics of how
the code behaves. Note, the optimizer assumes the code has no undefined
behavior, so if the code does contain undefined behavior, it will often behave
differently depending on which optimization level is enabled.
-* Frontend -- the Lexer, Preprocessor, Parser, Sema, and LLVM IR code generation
+- Frontend -- the Lexer, Preprocessor, Parser, Sema, and LLVM IR code generation
parts of the compiler.
-* Middle-end -- a term used for the of the subset of the backend that does
+- Middle-end -- a term used for the of the subset of the backend that does
(typically not target specific) optimizations prior to assembly code
generation.
-* Backend -- the parts of the compiler which run after LLVM IR code generation,
+- Backend -- the parts of the compiler which run after LLVM IR code generation,
such as the optimizer and generation of assembly code.
-See the :doc:`InternalsManual` for more details about the internal construction
+See the {doc}`InternalsManual` for more details about the internal construction
of the compiler.
-Support
--------
-Clang releases happen roughly `every six months <https://llvm.org/docs/HowToReleaseLLVM.html#annual-release-schedule>`_.
+### Support
+
+Clang releases happen roughly [every six months](https://llvm.org/docs/HowToReleaseLLVM.html#annual-release-schedule).
Only the current public release is officially supported. Bug-fix releases for
the current release will be produced on an as-needed basis, but bug fixes are
not backported to releases older than the current one.
-
-Command Line Options
-====================
+## Command Line Options
This section is generally an index into other sections. It does not go
into depth on the ones that are covered by other sections. However, the
first part introduces the language selection and other high level
-options like :option:`-c`, :option:`-g`, etc.
+options like {option}`-c`, {option}`-g`, etc.
-Options to Control Error and Warning Messages
----------------------------------------------
+### Options to Control Error and Warning Messages
+```{eval-rst}
.. option:: -Werror
Turn warnings into errors.
+```
+
+% This is in plain monospaced font because it generates the same label as
-.. This is in plain monospaced font because it generates the same label as
-.. -Werror, and Sphinx complains.
+% -Werror, and Sphinx complains.
+```{eval-rst}
.. option:: -Werror=foo
Turn warning "foo" into an error.
+```
+```{eval-rst}
.. option:: -Wno-error=foo
Turn warning "foo" into a warning even if :option:`-Werror` is specified.
+```
+```{eval-rst}
.. option:: -Wfoo
Enable warning "foo".
See the :doc:`diagnostics reference <DiagnosticsReference>` for a complete
list of the warning flags that can be specified in this way.
+```
+```{eval-rst}
.. option:: -Wno-foo
Disable warning "foo".
+```
+```{eval-rst}
.. option:: -w
Disable all warning diagnostics. Errors are still emitted.
+```
+```{eval-rst}
.. option:: -Weverything
:ref:`Enable all diagnostics. <diagnostics_enable_everything>`
+```
+```{eval-rst}
.. option:: -pedantic
Warn on language extensions.
+```
+```{eval-rst}
.. option:: -pedantic-errors
Error on language extensions.
+```
+```{eval-rst}
.. option:: -Wsystem-headers
Enable warnings from system headers.
+```
+```{eval-rst}
.. option:: -ferror-limit=123
Stop emitting diagnostics after 123 errors have been produced. The default is
20, and the error limit can be disabled with `-ferror-limit=0`.
+```
+```{eval-rst}
.. option:: -ftemplate-backtrace-limit=123
Only emit up to 123 template instantiation notes within the template
instantiation backtrace for a single warning or error. The default is 10, and
the limit can be disabled with `-ftemplate-backtrace-limit=0`.
+```
+```{eval-rst}
.. option:: --warning-suppression-mappings=foo.txt
:ref:`Suppress certain diagnostics for certain files. <warning_suppression_mappings>`
+```
-.. _cl_diag_formatting:
+(cl-diag-formatting)=
-Formatting of Diagnostics
-^^^^^^^^^^^^^^^^^^^^^^^^^
+#### Formatting of Diagnostics
Clang aims to produce beautiful diagnostics by default, particularly for
new users that first come to Clang. However, different people have
@@ -194,8 +217,9 @@ but by a program that wants consistent and easily parsable output. For
these cases, Clang provides a wide range of options to control the exact
output format of the diagnostics that it generates.
-.. _opt_fshow-column:
+(opt-fshow-column)=
+```{eval-rst}
.. option:: -f[no-]show-column
Print column number in diagnostic.
@@ -216,9 +240,11 @@ output format of the diagnostics that it generates.
The printed column numbers count bytes from the beginning of the
line; take care if your source contains multibyte characters.
+```
-.. _opt_fshow-source-location:
+(opt-fshow-source-location)=
+```{eval-rst}
.. option:: -f[no-]show-source-location
Print source file/line/column information in diagnostic.
@@ -236,9 +262,11 @@ output format of the diagnostics that it generates.
When this is disabled, Clang will not print the "test.c:28:8: "
part.
+```
-.. _opt_fcaret-diagnostics:
+(opt-fcaret-diagnostics)=
+```{eval-rst}
.. option:: -f[no-]caret-diagnostics
Print source line and ranges from source code in diagnostic.
@@ -253,7 +281,9 @@ output format of the diagnostics that it generates.
#endif bad
^
//
+```
+```{eval-rst}
.. option:: -f[no-]color-diagnostics
This option, which defaults to on when a color-capable terminal is
@@ -286,13 +316,17 @@ output format of the diagnostics that it generates.
(regardless of value), color diagnostics are disabled. If ``NO_COLOR`` is
defined and ``-fcolor-diagnostics`` is passed on the command line, Clang
will honor the command line argument.
+```
+```{eval-rst}
.. option:: -fansi-escape-codes
Controls whether ANSI escape codes are used instead of the Windows Console
API to output colored diagnostics. This option is only used on Windows and
defaults to off.
+```
+```{eval-rst}
.. option:: -fdiagnostics-format=clang/msvc/vi
Changes diagnostic output format to better match IDEs and command line tools.
@@ -315,9 +349,11 @@ output format of the diagnostics that it generates.
::
t.c +3:11: warning: conversion specifies type 'char *' but the argument has type 'int'
+```
-.. _opt_fdiagnostics-show-option:
+(opt-fdiagnostics-show-option)=
+```{eval-rst}
.. option:: -f[no-]diagnostics-show-option
Enable ``[-Woption]`` information in diagnostic line.
@@ -339,7 +375,9 @@ output format of the diagnostics that it generates.
the diagnostic. This information tells you the flag needed to enable
or disable the diagnostic, either from the command line or through
:ref:`#pragma GCC diagnostic <pragma_GCC_diagnostic>`.
+```
+```{eval-rst}
.. option:: -fdiagnostics-show-category=none/id/name
Enable printing category information in diagnostic line.
@@ -362,9 +400,11 @@ output format of the diagnostics that it generates.
This category can be used by clients that want to group diagnostics
by category, so it should be a high-level category. We want dozens
of these, not hundreds or thousands of them.
+```
-.. _opt_fsave-optimization-record:
+(opt-fsave-optimization-record)=
+```{eval-rst}
.. option:: -f[no-]save-optimization-record[=<format>]
Enable optimization remarks during compilation and write them to a separate
@@ -436,7 +476,9 @@ output format of the diagnostics that it generates.
Note that this is incompatible with passing the
:option:`-foptimization-record-file` option.
+```
+```{eval-rst}
.. option:: -foptimization-record-file
Control the file to which optimization reports are written. This implies
@@ -444,7 +486,9 @@ output format of the diagnostics that it generates.
On Darwin platforms, this is incompatible with passing multiple
``-arch <arch>`` options.
+```
+```{eval-rst}
.. option:: -foptimization-record-passes
Only include passes which match a specified regular expression.
@@ -455,9 +499,11 @@ output format of the diagnostics that it generates.
If this option is not used, all the passes are included in the optimization
record.
+```
-.. _opt_fdiagnostics-show-hotness:
+(opt-fdiagnostics-show-hotness)=
+```{eval-rst}
.. option:: -f[no-]diagnostics-show-hotness
Enable profile hotness information in diagnostic line.
@@ -481,7 +527,9 @@ output format of the diagnostics that it generates.
This option is implied when
:ref:`-fsave-optimization-record <opt_fsave-optimization-record>` is used.
Otherwise, it defaults to off.
+```
+```{eval-rst}
.. option:: -fdiagnostics-hotness-threshold
Prevent optimization remarks from being output if they do not have at least
@@ -493,9 +541,11 @@ output format of the diagnostics that it generates.
Optimization Reports <rpass>`) when profile hotness information in
diagnostics is enabled (see
:ref:`-fdiagnostics-show-hotness <opt_fdiagnostics-show-hotness>`).
+```
-.. _opt_fdiagnostics-fixit-info:
+(opt-fdiagnostics-fixit-info)=
+```{eval-rst}
.. option:: -f[no-]diagnostics-fixit-info
Enable "FixIt" information in the diagnostics output.
@@ -515,9 +565,11 @@ output format of the diagnostics that it generates.
printing the "//" line at the end of the message. This information
is useful for users who may not understand what is wrong, but can be
confusing for machine parsing.
+```
-.. _opt_fdiagnostics-print-source-range-info:
+(opt-fdiagnostics-print-source-range-info)=
+```{eval-rst}
.. option:: -fdiagnostics-print-source-range-info
Print machine parsable information about source ranges.
@@ -536,7 +588,9 @@ output format of the diagnostics that it generates.
The printed column numbers count bytes from the beginning of the
line; take care if your source contains multibyte characters.
+```
+```{eval-rst}
.. option:: -fdiagnostics-parseable-fixits
Print Fix-Its in a machine parseable form.
@@ -560,7 +614,9 @@ output format of the diagnostics that it generates.
The printed column numbers count bytes from the beginning of the
line; take care if your source contains multibyte characters.
+```
+```{eval-rst}
.. option:: -fno-elide-type
Turns off elision in template type printing.
@@ -582,7 +638,9 @@ output format of the diagnostics that it generates.
::
t.cc:4:5: note: candidate function not viable: no known conversion from 'vector<map<int, map<float, int>>>' to 'vector<map<int, map<double, int>>>' for 1st argument;
+```
+```{eval-rst}
.. option:: -fdiagnostics-show-template-tree
Template type diffing prints a text tree.
@@ -610,13 +668,17 @@ output format of the diagnostics that it generates.
[float != double],
[...]>>>
+```
+```{eval-rst}
.. option:: -fcaret-diagnostics-max-lines:
Controls how many lines of code clang prints for diagnostics. By default,
clang prints a maximum of 16 lines of code.
+```
+```{eval-rst}
.. option:: -fdiagnostics-show-line-numbers:
Controls whether clang will print a margin containing the line number on
@@ -642,14 +704,15 @@ output format of the diagnostics that it generates.
int
+```
-.. _cl_diag_warning_groups:
+(cl-diag-warning-groups)=
-Individual Warning Groups
-^^^^^^^^^^^^^^^^^^^^^^^^^
+#### Individual Warning Groups
TODO: Generate this from tblgen. Define one anchor per warning group.
+```{eval-rst}
.. option:: -Wextra-tokens
Warn about excess tokens at the end of a preprocessor directive.
@@ -665,7 +728,9 @@ TODO: Generate this from tblgen. Define one anchor per warning group.
These extra tokens are not strictly conforming, and are usually best
handled by commenting them out.
+```
+```{eval-rst}
.. option:: -Wambiguous-member-template
Warn about unqualified uses of a member template whose name resolves to
@@ -689,7 +754,9 @@ TODO: Generate this from tblgen. Define one anchor per warning group.
C++ [basic.lookup.classref] requires this to be an error, but,
because it's hard to work around, Clang downgrades it to a warning
as an extension.
+```
+```{eval-rst}
.. option:: -Wbind-to-temporary-copy
Warn about an unusable copy constructor when binding a reference to a
@@ -725,19 +792,20 @@ TODO: Generate this from tblgen. Define one anchor per warning group.
Note that if ``NonCopyable2::NonCopyable2()`` has a default argument
whose instantiation produces a compile error, that error will still
be a hard error in C++98 mode even if this warning is turned off.
+```
-Options to Control Clang Crash Diagnostics
-------------------------------------------
+### Options to Control Clang Crash Diagnostics
As unbelievable as it may sound, Clang does crash from time to time.
-Generally, this only occurs to those living on the `bleeding
-edge <https://llvm.org/releases/download.html#svn>`_. Clang goes to great
+Generally, this only occurs to those living on the [bleeding
+edge](https://llvm.org/releases/download.html#svn). Clang goes to great
lengths to assist you in filing a bug report. Specifically, Clang
generates preprocessed source file(s) and associated run script(s) upon
a crash. These files should be attached to a bug report to ease
reproducibility of the failure. Below are the command line options to
control the crash diagnostics.
+```{eval-rst}
.. option:: -fcrash-diagnostics=<val>
Valid values are:
@@ -745,46 +813,56 @@ control the crash diagnostics.
* ``off`` (Disable auto-generation of preprocessed source files during a clang crash.)
* ``compiler`` (Generate diagnostics for compiler crashes (default))
* ``all`` (Generate diagnostics for all tools which support it)
+```
+```{eval-rst}
.. option:: -fno-crash-diagnostics
Disable auto-generation of preprocessed source files during a clang crash.
The ``-fno-crash-diagnostics`` flag can be helpful for speeding the process
of generating a delta reduced test case.
+```
+```{eval-rst}
.. option:: -fcrash-diagnostics-dir=<dir>
Specify where to write the crash diagnostics files; defaults to the
usual location for temporary files.
+```
+```{eval-rst}
.. envvar:: CLANG_CRASH_DIAGNOSTICS_DIR=<dir>
Like ``-fcrash-diagnostics-dir=<dir>``, specifies where to write the
crash diagnostics files, but with lower precedence than the option.
+```
+```{eval-rst}
.. option:: -fcrash-diagnostics-tar=<path>
Specify where to write the crash diagnostics files as a tarball.
+```
Clang is also capable of generating preprocessed source file(s) and associated
run script(s) even without a crash. This is especially useful when trying to
generate a reproducer for warnings or errors while using modules.
+```{eval-rst}
.. option:: -gen-reproducer
Generates preprocessed source files, a reproducer script and if relevant, a
cache containing: built module pcm's and all headers needed to rebuild the
same modules.
+```
-.. _rpass:
+(rpass)=
-Options to Emit Optimization Reports
-------------------------------------
+### Options to Emit Optimization Reports
Optimization reports trace, at a high-level, all the major decisions
made by compiler transformations. For instance, when the inliner
-decides to inline function ``foo()`` into ``bar()``, or the loop unroller
+decides to inline function `foo()` into `bar()`, or the loop unroller
decides to unroll a loop N times, or the vectorizer decides to
vectorize a loop body.
@@ -792,9 +870,7 @@ Clang offers a family of flags which the optimizers can use to emit
a diagnostic in three cases:
1. When the pass makes a transformation (`-Rpass`).
-
2. When the pass fails to make a transformation (`-Rpass-missed`).
-
3. When the pass determines whether or not to make a transformation
(`-Rpass-analysis`).
@@ -806,12 +882,12 @@ take a regular expression that identifies the name of the pass which should
emit the associated diagnostic. For example, to get a report from the inliner,
compile the code with:
-.. code-block:: console
-
- $ clang -O2 -Rpass=inline code.cc -o code
- code.cc:4:25: remark: foo inlined into bar [-Rpass=inline]
- int bar(int j) { return foo(j, j - 2); }
- ^
+```console
+$ clang -O2 -Rpass=inline code.cc -o code
+code.cc:4:25: remark: foo inlined into bar [-Rpass=inline]
+int bar(int j) { return foo(j, j - 2); }
+ ^
+```
Note that remarks from the inliner are identified with `[-Rpass=inline]`.
To request a report from every optimization pass, you should use
@@ -824,16 +900,14 @@ feature.
Note that when using profile-guided optimization information, profile hotness
information can be included in the remarks (see
-:ref:`-fdiagnostics-show-hotness <opt_fdiagnostics-show-hotness>`).
+{ref}`-fdiagnostics-show-hotness <opt_fdiagnostics-show-hotness>`).
-Current limitations
-^^^^^^^^^^^^^^^^^^^
+#### Current limitations
1. Optimization remarks that refer to function names will display the
mangled name of the function. Since these remarks are emitted by the
back end of the compiler, it does not know anything about the input
language, nor its mangling rules.
-
2. Some source locations are not displayed correctly. The front end has
a more detailed source location tracking than the locations included
in the debug info (e.g., the front end can locate code inside macro
@@ -841,12 +915,12 @@ Current limitations
translated from debug annotations. That translation can be lossy,
which results in some remarks having no location information.
-Options to Emit Resource Consumption Reports
---------------------------------------------
+### Options to Emit Resource Consumption Reports
These are options that report execution time and consumed memory of different
compilations steps.
+```{eval-rst}
.. option:: -fproc-stat-report=
This option requests the driver to print used memory and execution time of each
@@ -904,18 +978,22 @@ compilations steps.
$ export CC_PRINT_PROC_STAT=1
$ export CC_PRINT_PROC_STAT_FILE=~/project-build-proc-stat.csv
$ make
+```
+
+### Other Options
-Other Options
--------------
Clang options that don't fit neatly into other categories.
+```{eval-rst}
.. option:: -fgnuc-version=
This flag controls the value of ``__GNUC__`` and related macros. This flag
does not enable or disable any GCC extensions implemented in Clang. Setting
the version to zero causes Clang to leave ``__GNUC__`` and other
GNU-namespaced macros, such as ``__GXX_WEAK__``, undefined.
+```
+```{eval-rst}
.. option:: -MV
When emitting a dependency file, use formatting conventions appropriate
@@ -930,7 +1008,9 @@ Clang options that don't fit neatly into other categories.
a special character, which is the convention used by GNU Make. The -MV
option tells Clang to put double-quotes around the entire filename, which
is the convention used by NMake and Jom.
+```
+```{eval-rst}
.. option:: -femit-dwarf-unwind=<value>
When to emit DWARF unwind (EH frame) info. This is a Mach-O-specific option.
@@ -949,48 +1029,50 @@ Clang options that don't fit neatly into other categories.
object files that are more quickly processed by the linker. This may cause
binary compatibility issues on older x86_64 targets, however, so use it with
caution.
+```
+```{eval-rst}
.. option:: -fdisable-block-signature-string
Instruct clang not to emit the signature string for blocks. Disabling the
string can potentially break existing code that relies on it. Users should
carefully consider this possibility when using the flag.
+```
-.. _configuration-files:
+(configuration-files)=
-Configuration files
--------------------
+### Configuration files
Configuration files group command-line options and allow all of them to be
specified just by referencing the configuration file. They may be used, for
example, to collect options required to tune compilation for a particular
-target, such as ``-L``, ``-I``, ``-l``, ``--sysroot``, codegen options, etc.
+target, such as `-L`, `-I`, `-l`, `--sysroot`, codegen options, etc.
Configuration files can be either specified on the command line or loaded
from default locations. If both variants are present, the default configuration
files are loaded first.
-The command line option ``--config=`` can be used to specify explicit
+The command line option `--config=` can be used to specify explicit
configuration files in a Clang invocation. If the option is used multiple times,
all specified files are loaded, in order. For example:
-::
-
- clang --config=/home/user/cfgs/testing.txt
- clang --config=debug.cfg --config=runtimes.cfg
+```
+clang --config=/home/user/cfgs/testing.txt
+clang --config=debug.cfg --config=runtimes.cfg
+```
If the provided argument contains a directory separator, it is considered as
a file path, and options are read from that file. Otherwise the argument is
treated as a file name and is searched for sequentially in the directories:
- - user directory,
- - system directory,
- - the directory where Clang executable resides.
+> - user directory,
+> - system directory,
+> - the directory where Clang executable resides.
Both user and system directories for configuration files can be specified
either during build or during runtime. At build time, use
-``CLANG_CONFIG_FILE_USER_DIR`` and ``CLANG_CONFIG_FILE_SYSTEM_DIR``. At run
-time use the ``--config-user-dir=`` and ``--config-system-dir=`` command line
+`CLANG_CONFIG_FILE_USER_DIR` and `CLANG_CONFIG_FILE_SYSTEM_DIR`. At run
+time use the `--config-user-dir=` and `--config-system-dir=` command line
options. Specifying config directories at runtime overrides the config
directories set at build time. The first file found is used. It is an error if
the required file cannot be found.
@@ -998,131 +1080,140 @@ the required file cannot be found.
The default configuration files are searched for in the same directories
following the rules described in the next paragraphs. Loading default
configuration files can be disabled entirely via passing
-the ``--no-default-config`` flag.
+the `--no-default-config` flag.
First, the algorithm searches for a configuration file named
-``<triple>-<driver>.cfg`` where `triple` is the triple for the target being
+`<triple>-<driver>.cfg` where `triple` is the triple for the target being
built, and `driver` is the name of the currently used driver. The algorithm
first attempts to use the canonical name for the driver used, then falls back
to the one found in the executable name.
The following canonical driver names are used:
-- ``clang`` for the ``gcc`` driver (used to compile C programs)
-- ``clang++`` for the ``gxx`` driver (used to compile C++ programs)
-- ``clang-cpp`` for the ``cpp`` driver (pure preprocessor)
-- ``clang-cl`` for the ``cl`` driver
-- ``flang`` for the ``flang`` driver
-- ``clang-dxc`` for the ``dxc`` driver
+- `clang` for the `gcc` driver (used to compile C programs)
+- `clang++` for the `gxx` driver (used to compile C++ programs)
+- `clang-cpp` for the `cpp` driver (pure preprocessor)
+- `clang-cl` for the `cl` driver
+- `flang` for the `flang` driver
+- `clang-dxc` for the `dxc` driver
-For example, when calling ``x86_64-pc-linux-gnu-clang-g++``,
-the driver will first attempt to use the configuration file named::
+For example, when calling `x86_64-pc-linux-gnu-clang-g++`,
+the driver will first attempt to use the configuration file named:
- x86_64-pc-linux-gnu-clang++.cfg
+```
+x86_64-pc-linux-gnu-clang++.cfg
+```
If this file is not found, it will attempt to use the name found
-in the executable instead::
+in the executable instead:
- x86_64-pc-linux-gnu-clang-g++.cfg
+```
+x86_64-pc-linux-gnu-clang-g++.cfg
+```
-Note that options such as ``--driver-mode=``, ``--target=``, ``-m32`` affect
+Note that options such as `--driver-mode=`, `--target=`, `-m32` affect
the search algorithm. For example, the aforementioned executable called with
-``-m32`` argument will instead search for::
+`-m32` argument will instead search for:
- i386-pc-linux-gnu-clang++.cfg
+```
+i386-pc-linux-gnu-clang++.cfg
+```
If none of the aforementioned files are found, the driver will instead search
for separate driver and target configuration files and attempt to load both.
-The former is named ``<driver>.cfg`` while the latter is named
-``<triple>.cfg``. Similarly to the previous variants, the canonical driver name
+The former is named `<driver>.cfg` while the latter is named
+`<triple>.cfg`. Similarly to the previous variants, the canonical driver name
will be preferred, and the compiler will fall back to the actual name.
-For example, ``x86_64-pc-linux-gnu-clang-g++`` will attempt to load two
-configuration files named respectively::
+For example, `x86_64-pc-linux-gnu-clang-g++` will attempt to load two
+configuration files named respectively:
- clang++.cfg
- x86_64-pc-linux-gnu.cfg
+```
+clang++.cfg
+x86_64-pc-linux-gnu.cfg
+```
-with fallback to trying::
+with fallback to trying:
- clang-g++.cfg
- x86_64-pc-linux-gnu.cfg
+```
+clang-g++.cfg
+x86_64-pc-linux-gnu.cfg
+```
It is not an error if either of these files is not found.
The configuration file consists of command-line options specified on one or
more lines. Lines composed of whitespace characters only are ignored as well as
-lines in which the first non-blank character is ``#``. Long options may be split
+lines in which the first non-blank character is `#`. Long options may be split
between several lines by a trailing backslash. Here is an example of a
configuration file:
-::
+```
+# Several options on line
+-c --target=x86_64-unknown-linux-gnu
- # Several options on line
- -c --target=x86_64-unknown-linux-gnu
+# Long option split between lines
+-I/usr/lib/gcc/x86_64-linux-gnu/5.4.0/../../../../\
+include/c++/5.4.0
- # Long option split between lines
- -I/usr/lib/gcc/x86_64-linux-gnu/5.4.0/../../../../\
- include/c++/5.4.0
+# other config files may be included
+ at linux.options
+```
- # other config files may be included
- @linux.options
-
-Files included by ``@file`` directives in configuration files are resolved
+Files included by `@file` directives in configuration files are resolved
relative to the including file. For example, if a configuration file
-``~/.llvm/target.cfg`` contains the directive ``@os/linux.opts``, the file
-``linux.opts`` is searched for in the directory ``~/.llvm/os``. Another way to
-include a file content is using the command line option ``--config=``. It works
+`~/.llvm/target.cfg` contains the directive `@os/linux.opts`, the file
+`linux.opts` is searched for in the directory `~/.llvm/os`. Another way to
+include a file content is using the command line option `--config=`. It works
similarly but the included file is searched for using the rules for configuration
files.
-To generate paths relative to the configuration file, the ``<CFGDIR>`` token may
+To generate paths relative to the configuration file, the `<CFGDIR>` token may
be used. This will expand to the absolute path of the directory containing the
configuration file.
In cases where a configuration file is deployed alongside SDK contents, the
-SDK directory can remain fully portable by using ``<CFGDIR>`` prefixed paths.
+SDK directory can remain fully portable by using `<CFGDIR>` prefixed paths.
In this way, the user may only need to specify a root configuration file with
-``--config=`` to establish every aspect of the SDK with the compiler:
-
-::
+`--config=` to establish every aspect of the SDK with the compiler:
- --target=foo
- -isystem <CFGDIR>/include
- -L <CFGDIR>/lib
- -T <CFGDIR>/ldscripts/link.ld
+```
+--target=foo
+-isystem <CFGDIR>/include
+-L <CFGDIR>/lib
+-T <CFGDIR>/ldscripts/link.ld
+```
Usually, config file options are placed before command-line options, regardless
of the actual operation to be performed. The exception is being made for the
-options prefixed with the ``$`` character. These will be used only when the linker
+options prefixed with the `$` character. These will be used only when the linker
is being invoked, and added after all of the command-line specified linker
-inputs. Here is an example of ``$``-prefixed options:
+inputs. Here is an example of `$`-prefixed options:
-::
+```
+$-Wl,-Bstatic $-lm
+$-Wl,-Bshared
+```
- $-Wl,-Bstatic $-lm
- $-Wl,-Bshared
+## Language and Target-Independent Features
-Language and Target-Independent Features
-========================================
+### Freestanding Builds
-Freestanding Builds
--------------------
-Passing the ``-ffreestanding`` flag causes Clang to build for a freestanding
+Passing the `-ffreestanding` flag causes Clang to build for a freestanding
(rather than a hosted) environment. The flag has the following effects:
-* the ``__STDC_HOSTED__`` predefined macro will expand to ``0``,
-* builtin functions are disabled by default (``-fno-builtins``),
-* unwind tables are disabled by default
- (``fno-asynchronous-unwind-tables -fno-unwind-tables``), and
-* does not treat the global ``main`` function as a special function.
+- the `__STDC_HOSTED__` predefined macro will expand to `0`,
+- builtin functions are disabled by default (`-fno-builtins`),
+- unwind tables are disabled by default
+ (`fno-asynchronous-unwind-tables -fno-unwind-tables`), and
+- does not treat the global `main` function as a special function.
An implementation of the following runtime library functions must always be
provided with the usual semantics, as Clang will generate calls to them:
-* ``memcpy``,
-* ``memmove``, and
-* ``memset``.
+- `memcpy`,
+- `memmove`, and
+- `memset`.
Clang does not, by itself, provide a full "conforming freestanding
implementation". If you wish to have a conforming freestanding implementation,
@@ -1130,68 +1221,64 @@ you must provide a freestanding C library. While Clang provides some of the
required header files, it does not provide all of them, nor any library
implementations.
-Conversely, when ``-ffreestanding`` is specified, Clang does not require you to
+Conversely, when `-ffreestanding` is specified, Clang does not require you to
provide a conforming freestanding implementation library. Clang will not make
any assumptions as to the availability or semantics of standard-library
functions other than those mentioned above.
-Controlling Errors and Warnings
--------------------------------
+### Controlling Errors and Warnings
Clang provides a number of ways to control which code constructs cause
it to emit errors and warning messages, and how they are displayed to
the console.
-Controlling How Clang Displays Diagnostics
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+#### Controlling How Clang Displays Diagnostics
When Clang emits a diagnostic, it includes rich information in the
output, and gives you fine-grain control over which information is
printed. Clang has the ability to print this information, and these are
the options that control it:
-#. A file/line/column indicator that shows exactly where the diagnostic
- occurs in your code [:ref:`-fshow-column <opt_fshow-column>`,
- :ref:`-fshow-source-location <opt_fshow-source-location>`].
-#. A categorization of the diagnostic as a note, warning, error, or
+1. A file/line/column indicator that shows exactly where the diagnostic
+ occurs in your code \[{ref}`-fshow-column <opt_fshow-column>`,
+ {ref}`-fshow-source-location <opt_fshow-source-location>`\].
+2. A categorization of the diagnostic as a note, warning, error, or
fatal error.
-#. A text string that describes what the problem is.
-#. An option that indicates how to control the diagnostic (for
+3. A text string that describes what the problem is.
+4. An option that indicates how to control the diagnostic (for
diagnostics that support it)
- [:ref:`-fdiagnostics-show-option <opt_fdiagnostics-show-option>`].
-#. A :ref:`high-level category <diagnostics_categories>` for the diagnostic
+ \[{ref}`-fdiagnostics-show-option <opt_fdiagnostics-show-option>`\].
+5. A {ref}`high-level category <diagnostics_categories>` for the diagnostic
for clients that want to group diagnostics by class (for diagnostics
that support it)
- [:option:`-fdiagnostics-show-category`].
-#. The line of source code that the issue occurs on, along with a caret
+ \[{option}`-fdiagnostics-show-category`\].
+6. The line of source code that the issue occurs on, along with a caret
and ranges that indicate the important locations
- [:ref:`-fcaret-diagnostics <opt_fcaret-diagnostics>`].
-#. "FixIt" information, which is a concise explanation of how to fix the
+ \[{ref}`-fcaret-diagnostics <opt_fcaret-diagnostics>`\].
+7. "FixIt" information, which is a concise explanation of how to fix the
problem (when Clang is certain it knows)
- [:ref:`-fdiagnostics-fixit-info <opt_fdiagnostics-fixit-info>`].
-#. A machine-parsable representation of the ranges involved (off by
+ \[{ref}`-fdiagnostics-fixit-info <opt_fdiagnostics-fixit-info>`\].
+8. A machine-parsable representation of the ranges involved (off by
default)
- [:ref:`-fdiagnostics-print-source-range-info <opt_fdiagnostics-print-source-range-info>`].
+ \[{ref}`-fdiagnostics-print-source-range-info <opt_fdiagnostics-print-source-range-info>`\].
-For more information please see :ref:`Formatting of
+For more information please see {ref}`Formatting of
Diagnostics <cl_diag_formatting>`.
-Diagnostic Mappings
-^^^^^^^^^^^^^^^^^^^
+#### Diagnostic Mappings
All diagnostics are mapped into one of these 6 classes:
-- Ignored
-- Note
-- Remark
-- Warning
-- Error
-- Fatal
+- Ignored
+- Note
+- Remark
+- Warning
+- Error
+- Fatal
-.. _diagnostics_categories:
+(diagnostics-categories)=
-Diagnostic Categories
-^^^^^^^^^^^^^^^^^^^^^
+#### Diagnostic Categories
Though not shown by default, diagnostics may each be associated with a
high-level category. This category is intended to make it possible to
@@ -1199,58 +1286,56 @@ triage builds that produce a large number of errors or warnings in a
grouped way.
Categories are not shown by default, but they can be turned on with the
-:option:`-fdiagnostics-show-category` option.
-When set to "``name``", the category is printed textually in the
-diagnostic output. When it is set to "``id``", a category number is
+{option}`-fdiagnostics-show-category` option.
+When set to "`name`", the category is printed textually in the
+diagnostic output. When it is set to "`id`", a category number is
printed. The mapping of category names to category id's can be obtained
-by running '``clang --print-diagnostic-categories``'.
+by running '`clang --print-diagnostic-categories`'.
-Controlling Diagnostics via Command Line Flags
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+#### Controlling Diagnostics via Command Line Flags
TODO: -W flags, -pedantic, etc
-.. _pragma_gcc_diagnostic:
+(pragma-gcc-diagnostic)=
-Controlling Diagnostics via Pragmas
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+#### Controlling Diagnostics via Pragmas
Clang can also control what diagnostics are enabled through the use of
pragmas in the source code. This is useful for turning off specific
warnings in a section of source code. Clang supports GCC's pragma for
-compatibility with existing source code, so ``#pragma GCC diagnostic``
-and ``#pragma clang diagnostic`` are synonyms for Clang. GCC will ignore
-``#pragma clang diagnostic``, though.
+compatibility with existing source code, so `#pragma GCC diagnostic`
+and `#pragma clang diagnostic` are synonyms for Clang. GCC will ignore
+`#pragma clang diagnostic`, though.
The pragma may control any warning that can be used from the command
line. Warnings may be set to ignored, warning, error, or fatal. The
-following example code will tell Clang or GCC to ignore the ``-Wall``
+following example code will tell Clang or GCC to ignore the `-Wall`
warnings:
-.. code-block:: c
-
- #pragma GCC diagnostic ignored "-Wall"
+```c
+#pragma GCC diagnostic ignored "-Wall"
+```
Clang also allows you to push and pop the current warning state. This is
particularly useful when writing a header file that will be compiled by
other people, because you don't know what warning flags they build with.
-In the example below, :option:`-Wextra-tokens` is ignored for only a single line
+In the example below, {option}`-Wextra-tokens` is ignored for only a single line
of code, after which the diagnostics return to whatever state had previously
existed.
-.. code-block:: c
-
- #if foo
- #endif foo // warning: extra tokens at end of #endif directive
+```c
+#if foo
+#endif foo // warning: extra tokens at end of #endif directive
- #pragma GCC diagnostic push
- #pragma GCC diagnostic ignored "-Wextra-tokens"
+#pragma GCC diagnostic push
+#pragma GCC diagnostic ignored "-Wextra-tokens"
- #if foo
- #endif foo // no warning
+#if foo
+#endif foo // no warning
- #pragma GCC diagnostic pop
+#pragma GCC diagnostic pop
+```
The push and pop pragmas will save and restore the full diagnostic state
of the compiler, regardless of how it was set. It should be noted that while Clang
@@ -1258,183 +1343,176 @@ supports the GCC pragma, Clang and GCC do not support the exact same set
of warnings, so even when using GCC-compatible #pragmas there is no
guarantee that they will have identical behaviour on both compilers.
-Clang also doesn't yet support GCC behavior for ``#pragma diagnostic pop``
-that doesn't have a corresponding ``#pragma diagnostic push``. In this case,
-GCC pretends that there is a ``#pragma diagnostic push`` at the very beginning
-of the source file, so "unpaired" ``#pragma diagnostic pop`` matches that
-implicit push. This makes a difference for ``#pragma GCC diagnostic ignored``
+Clang also doesn't yet support GCC behavior for `#pragma diagnostic pop`
+that doesn't have a corresponding `#pragma diagnostic push`. In this case,
+GCC pretends that there is a `#pragma diagnostic push` at the very beginning
+of the source file, so "unpaired" `#pragma diagnostic pop` matches that
+implicit push. This makes a difference for `#pragma GCC diagnostic ignored`
which are not guarded by push and pop. Refer to
-`GCC documentation <https://gcc.gnu.org/onlinedocs/gcc/Diagnostic-Pragmas.html>`_
+[GCC documentation](https://gcc.gnu.org/onlinedocs/gcc/Diagnostic-Pragmas.html)
for details.
-Like GCC, Clang accepts ``ignored``, ``warning``, ``error``, and ``fatal``
+Like GCC, Clang accepts `ignored`, `warning`, `error`, and `fatal`
severity levels. They can be used to change severity of a particular diagnostic
for a region of source file. A notable difference from GCC is that diagnostic
not enabled via command line arguments can't be enabled this way yet.
-Some diagnostics associated with a ``-W`` flag have the error severity by
+Some diagnostics associated with a `-W` flag have the error severity by
default. They can be ignored or downgraded to warnings:
-.. code-block:: cpp
-
- // C only
- #pragma GCC diagnostic warning "-Wimplicit-function-declaration"
- int main(void) { puts(""); }
+```cpp
+// C only
+#pragma GCC diagnostic warning "-Wimplicit-function-declaration"
+int main(void) { puts(""); }
+```
In addition to controlling warnings and errors generated by the compiler, it is
possible to generate custom warning and error messages through the following
pragmas:
-.. code-block:: c
+```c
+// The following will produce warning messages
+#pragma message "some diagnostic message"
+#pragma GCC warning "TODO: replace deprecated feature"
- // The following will produce warning messages
- #pragma message "some diagnostic message"
- #pragma GCC warning "TODO: replace deprecated feature"
+// The following will produce an error message
+#pragma GCC error "Not supported"
+```
- // The following will produce an error message
- #pragma GCC error "Not supported"
-
-These pragmas operate similarly to the ``#warning`` and ``#error`` preprocessor
+These pragmas operate similarly to the `#warning` and `#error` preprocessor
directives, except that they may also be embedded into preprocessor macros via
-the C99 ``_Pragma`` operator, for example:
-
-.. code-block:: c
+the C99 `_Pragma` operator, for example:
- #define STR(X) #X
- #define DEFER(M,...) M(__VA_ARGS__)
- #define CUSTOM_ERROR(X) _Pragma(STR(GCC error(X " at line " DEFER(STR,__LINE__))))
+```c
+#define STR(X) #X
+#define DEFER(M,...) M(__VA_ARGS__)
+#define CUSTOM_ERROR(X) _Pragma(STR(GCC error(X " at line " DEFER(STR,__LINE__))))
- CUSTOM_ERROR("Feature not available");
+CUSTOM_ERROR("Feature not available");
+```
-Controlling Diagnostics in System Headers
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+#### Controlling Diagnostics in System Headers
Warnings are suppressed when they occur in system headers. By default,
an included file is treated as a system header if it is found in an
-include path specified by ``-isystem``, but this can be overridden in
+include path specified by `-isystem`, but this can be overridden in
several ways.
-The ``system_header`` pragma can be used to mark the current file as
+The `system_header` pragma can be used to mark the current file as
being a system header. No warnings will be produced from the location of
the pragma onwards within the same file.
-.. code-block:: c
+```c
+#if foo
+#endif foo // warning: extra tokens at end of #endif directive
- #if foo
- #endif foo // warning: extra tokens at end of #endif directive
+#pragma clang system_header
- #pragma clang system_header
-
- #if foo
- #endif foo // no warning
+#if foo
+#endif foo // no warning
+```
The `--system-header-prefix=` and `--no-system-header-prefix=`
command-line arguments can be used to override whether subsets of an include
-path are treated as system headers. When the name in a ``#include`` directive
+path are treated as system headers. When the name in a `#include` directive
is found within a header search path and starts with a system prefix, the
header is treated as a system header. The last prefix on the
command-line which matches the specified header name takes precedence.
For instance:
-.. code-block:: console
-
- $ clang -Ifoo -isystem bar --system-header-prefix=x/ \
- --no-system-header-prefix=x/y/
+```console
+$ clang -Ifoo -isystem bar --system-header-prefix=x/ \
+ --no-system-header-prefix=x/y/
+```
-Here, ``#include "x/a.h"`` is treated as including a system header, even
-if the header is found in ``foo``, and ``#include "x/y/b.h"`` is treated
+Here, `#include "x/a.h"` is treated as including a system header, even
+if the header is found in `foo`, and `#include "x/y/b.h"` is treated
as not including a system header, even if the header is found in
-``bar``.
+`bar`.
-A ``#include`` directive which finds a file relative to the current
+A `#include` directive which finds a file relative to the current
directory is treated as including a system header if the including file
is treated as a system header.
-Controlling Deprecation Diagnostics in Clang-Provided C Runtime Headers
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+#### Controlling Deprecation Diagnostics in Clang-Provided C Runtime Headers
Clang is responsible for providing some of the C runtime headers that cannot be
provided by a platform CRT, such as implementation limits or when compiling in
-freestanding mode. Define the ``_CLANG_DISABLE_CRT_DEPRECATION_WARNINGS`` macro
+freestanding mode. Define the `_CLANG_DISABLE_CRT_DEPRECATION_WARNINGS` macro
prior to including such a C runtime header to disable the deprecation warnings.
Note that the C Standard Library headers are allowed to transitively include
other standard library headers (see 7.1.2p5), and so the most appropriate use
-of this macro is to set it within the build system using ``-D`` or before any
+of this macro is to set it within the build system using `-D` or before any
include directives in the translation unit.
-.. code-block:: c
+```c
+#define _CLANG_DISABLE_CRT_DEPRECATION_WARNINGS
+#include <stdint.h> // Clang CRT deprecation warnings are disabled.
+#include <stdatomic.h> // Clang CRT deprecation warnings are disabled.
+```
- #define _CLANG_DISABLE_CRT_DEPRECATION_WARNINGS
- #include <stdint.h> // Clang CRT deprecation warnings are disabled.
- #include <stdatomic.h> // Clang CRT deprecation warnings are disabled.
+(diagnostics-enable-everything)=
-.. _diagnostics_enable_everything:
+#### Enabling All Diagnostics
-Enabling All Diagnostics
-^^^^^^^^^^^^^^^^^^^^^^^^
-
-In addition to the traditional ``-W`` flags, one can enable **all** diagnostics
-by passing :option:`-Weverything`. This works as expected with
-:option:`-Werror`, and also includes the warnings from :option:`-pedantic`. Some
-diagnostics contradict each other, therefore, users of :option:`-Weverything`
+In addition to the traditional `-W` flags, one can enable **all** diagnostics
+by passing {option}`-Weverything`. This works as expected with
+{option}`-Werror`, and also includes the warnings from {option}`-pedantic`. Some
+diagnostics contradict each other, therefore, users of {option}`-Weverything`
often disable many diagnostics such as `-Wno-c++98-compat` and `-Wno-c++-compat`
because they contradict recent C++ standards.
-Since :option:`-Weverything` enables every diagnostic, we generally don't
+Since {option}`-Weverything` enables every diagnostic, we generally don't
recommend using it. `-Wall` `-Wextra` are a better choice for most projects.
-Using :option:`-Weverything` means that updating your compiler is more difficult
+Using {option}`-Weverything` means that updating your compiler is more difficult
because you're exposed to experimental diagnostics which might be of lower
-quality than the default ones. If you do use :option:`-Weverything` then we
+quality than the default ones. If you do use {option}`-Weverything` then we
advise that you address all new compiler diagnostics as they get added to Clang,
either by fixing everything they find or explicitly disabling that diagnostic
with its corresponding `Wno-` option.
-Note that when combined with :option:`-w` (which disables all warnings),
+Note that when combined with {option}`-w` (which disables all warnings),
disabling all warnings wins.
-.. _warning_suppression_mappings:
+(warning-suppression-mappings)=
-Controlling Diagnostics via Suppression Mappings
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+#### Controlling Diagnostics via Suppression Mappings
Warning suppression mappings enable users to suppress Clang's diagnostics at a
per-file granularity. This allows enforcing diagnostics in specific parts of the
project even if there are violations in some headers.
-.. code-block:: console
-
- $ cat mappings.txt
- [unused]
- src:foo/*
-
- $ clang --warning-suppression-mappings=mapping.txt -Wunused foo/bar.cc
- # This compilation won't emit any unused findings for sources under foo/
- # directory. But it'll still complain for all the other sources, e.g:
- $ cat foo/bar.cc
- #include "dir/include.h" // Clang flags unused declarations here.
- #include "foo/include.h" // but unused warnings under this source are omitted.
- #include "next_to_bar_cc.h" // as are unused warnings from this header file.
- // Further, unused warnings in the remainder of bar.cc are also omitted.
-
-
-See :doc:`WarningSuppressionMappings` for details about the file format and
+```console
+$ cat mappings.txt
+[unused]
+src:foo/*
+
+$ clang --warning-suppression-mappings=mapping.txt -Wunused foo/bar.cc
+# This compilation won't emit any unused findings for sources under foo/
+# directory. But it'll still complain for all the other sources, e.g:
+$ cat foo/bar.cc
+#include "dir/include.h" // Clang flags unused declarations here.
+#include "foo/include.h" // but unused warnings under this source are omitted.
+#include "next_to_bar_cc.h" // as are unused warnings from this header file.
+// Further, unused warnings in the remainder of bar.cc are also omitted.
+```
+
+See {doc}`WarningSuppressionMappings` for details about the file format and
functionality.
-Controlling Static Analyzer Diagnostics
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+#### Controlling Static Analyzer Diagnostics
While not strictly part of the compiler, the diagnostics from Clang's
-`static analyzer <https://clang-analyzer.llvm.org>`_ can also be
+[static analyzer](https://clang-analyzer.llvm.org) can also be
influenced by the user via changes to the source code. See the available
-`annotations <analyzer/user-docs/Annotations.html>`_ and the analyzer's
-`FAQ page <analyzer/user-docs/FAQ.html#exclude-code>`_ for more information.
+[annotations](analyzer/user-docs/Annotations.html) and the analyzer's
+[FAQ page](analyzer/user-docs/FAQ.html#exclude-code) for more information.
-.. _usersmanual-precompiled-headers:
+(usersmanual-precompiled-headers)=
-Precompiled Headers
--------------------
+### Precompiled Headers
-`Precompiled headers <https://en.wikipedia.org/wiki/Precompiled_header>`_
+[Precompiled headers](https://en.wikipedia.org/wiki/Precompiled_header)
are a general approach employed by many compilers to reduce compilation
time. The underlying motivation of the approach is that it is common for
the same (and often large) header files to be included by multiple
@@ -1448,64 +1526,60 @@ details of precompiled headers vary between compilers, precompiled
headers have been shown to be highly effective at speeding up program
compilation on systems with very large system headers (e.g., macOS).
-Generating a PCH File
-^^^^^^^^^^^^^^^^^^^^^
+#### Generating a PCH File
To generate a PCH file using Clang, one invokes Clang with the
`-x <language>-header` option. This mirrors the interface in GCC
for generating PCH files:
-.. code-block:: console
-
- $ gcc -x c-header test.h -o test.h.gch
- $ clang -x c-header test.h -o test.h.pch
-
-Using a PCH File
-^^^^^^^^^^^^^^^^
+```console
+$ gcc -x c-header test.h -o test.h.gch
+$ clang -x c-header test.h -o test.h.pch
+```
-A PCH file can then be used as a prefix header when a ``-include-pch``
-option is passed to ``clang``:
+#### Using a PCH File
-.. code-block:: console
+A PCH file can then be used as a prefix header when a `-include-pch`
+option is passed to `clang`:
- $ clang -include-pch test.h.pch test.c -o test
+```console
+$ clang -include-pch test.h.pch test.c -o test
+```
-The ``clang`` driver will check if the PCH file ``test.h.pch`` is
-available; if so, the contents of ``test.h`` (and the files it includes)
+The `clang` driver will check if the PCH file `test.h.pch` is
+available; if so, the contents of `test.h` (and the files it includes)
will be processed from the PCH file. Otherwise, Clang will report an error.
-.. note::
-
- Clang does *not* automatically use PCH files for headers that are directly
- included within a source file or indirectly via :option:`-include`.
- For example:
-
- .. code-block:: console
+:::{note}
+Clang does *not* automatically use PCH files for headers that are directly
+included within a source file or indirectly via {option}`-include`.
+For example:
- $ clang -x c-header test.h -o test.h.pch
- $ cat test.c
- #include "test.h"
- $ clang test.c -o test
+```console
+$ clang -x c-header test.h -o test.h.pch
+$ cat test.c
+#include "test.h"
+$ clang test.c -o test
+```
- In this example, ``clang`` will not automatically use the PCH file for
- ``test.h`` since ``test.h`` was included directly in the source file and not
- specified on the command line using ``-include-pch``.
+In this example, `clang` will not automatically use the PCH file for
+`test.h` since `test.h` was included directly in the source file and not
+specified on the command line using `-include-pch`.
+:::
-Ignoring a PCH File
-^^^^^^^^^^^^^^^^^^^
+#### Ignoring a PCH File
-To ignore PCH options, a `-ignore-pch` option is passed to ``clang``:
+To ignore PCH options, a `-ignore-pch` option is passed to `clang`:
-.. code-block:: console
-
- $ clang -x c-header test.h -Xclang -ignore-pch -o test.h.pch
- $ clang -include-pch test.h.pch -Xclang -ignore-pch test.c -o test
+```console
+$ clang -x c-header test.h -Xclang -ignore-pch -o test.h.pch
+$ clang -include-pch test.h.pch -Xclang -ignore-pch test.c -o test
+```
This option disables precompiled headers, overrides -emit-pch and -include-pch.
test.h.pch is not generated and not used as a prefix header.
-Relocatable PCH Files
-^^^^^^^^^^^^^^^^^^^^^
+#### Relocatable PCH Files
It is sometimes necessary to build a precompiled header from headers
that are not yet in their final, installed locations. For example, one
@@ -1517,45 +1591,45 @@ location.
To build a relocatable precompiled header, place your headers into a
subdirectory whose structure mimics the installed location. For example,
-if you want to build a precompiled header for the header ``mylib.h``
-that will be installed into ``/usr/include``, create a subdirectory
-``build/usr/include`` and place the header ``mylib.h`` into that
-subdirectory. If ``mylib.h`` depends on other headers, then they can be
-stored within ``build/usr/include`` in a way that mimics the installed
+if you want to build a precompiled header for the header `mylib.h`
+that will be installed into `/usr/include`, create a subdirectory
+`build/usr/include` and place the header `mylib.h` into that
+subdirectory. If `mylib.h` depends on other headers, then they can be
+stored within `build/usr/include` in a way that mimics the installed
location.
Building a relocatable precompiled header requires two additional
-arguments. First, pass the ``--relocatable-pch`` flag to indicate that
+arguments. First, pass the `--relocatable-pch` flag to indicate that
the resulting PCH file should be relocatable. Second, pass
-``-isysroot /path/to/build``, which makes all includes for your library
+`-isysroot /path/to/build`, which makes all includes for your library
relative to the build directory. For example:
-.. code-block:: console
-
- # clang -x c-header --relocatable-pch -isysroot /path/to/build /path/to/build/mylib.h mylib.h.pch
+```console
+# clang -x c-header --relocatable-pch -isysroot /path/to/build /path/to/build/mylib.h mylib.h.pch
+```
When loading the relocatable PCH file, the various headers used in the
-PCH file are found from the system header root. For example, ``mylib.h``
-can be found in ``/usr/include/mylib.h``. If the headers are installed
-in some other system root, the ``-isysroot`` option can be used provide
+PCH file are found from the system header root. For example, `mylib.h`
+can be found in `/usr/include/mylib.h`. If the headers are installed
+in some other system root, the `-isysroot` option can be used provide
a different system root from which the headers will be based. For
-example, ``-isysroot /Developer/SDKs/MacOSX10.4u.sdk`` will look for
-``mylib.h`` in ``/Developer/SDKs/MacOSX10.4u.sdk/usr/include/mylib.h``.
+example, `-isysroot /Developer/SDKs/MacOSX10.4u.sdk` will look for
+`mylib.h` in `/Developer/SDKs/MacOSX10.4u.sdk/usr/include/mylib.h`.
Relocatable precompiled headers are intended to be used in a limited
number of cases where the compilation environment is tightly controlled
and the precompiled header cannot be generated after headers have been
installed.
-.. _controlling-fp-behavior:
+(controlling-fp-behavior)=
-Controlling Floating Point Behavior
------------------------------------
+### Controlling Floating Point Behavior
Clang provides a number of ways to control floating point behavior, including
with command line options and source pragmas. This section
describes the various floating point semantic modes and the corresponding options.
+```{eval-rst}
.. csv-table:: Floating Point Semantic Modes
:header: "Mode", "Values"
:widths: 15, 30, 30
@@ -1574,11 +1648,12 @@ describes the various floating point semantic modes and the corresponding option
"fallow-approximate-fns", "{on, off}"
"fassociative-math", "{on, off}"
"fcomplex-arithmetic", "{basic, improved, full, promoted}"
+```
This table describes the option settings that correspond to the three
floating point semantic models: precise (the default), strict, and fast.
-
+```{eval-rst}
.. csv-table:: Floating Point Models
:header: "Mode", "Precise", "Strict", "Fast", "Aggressive"
:widths: 25, 25, 25, 25, 25
@@ -1595,15 +1670,17 @@ floating point semantic models: precise (the default), strict, and fast.
"allow_approximate_fns", "off", "off", "on", "on"
"allow_reassociation", "off", "off", "on", "on"
"complex_arithmetic", "full", "full", "promoted", "basic"
+```
-The ``-ffp-model`` option does not modify the ``fdenormal-fp-math``
-setting, but it does have an impact on whether ``crtfastmath.o`` is
-linked. Because linking ``crtfastmath.o`` has a global effect on the
+The `-ffp-model` option does not modify the `fdenormal-fp-math`
+setting, but it does have an impact on whether `crtfastmath.o` is
+linked. Because linking `crtfastmath.o` has a global effect on the
program, and because the global denormal handling can be changed in
-other ways, the state of ``fdenormal-fp-math`` handling cannot
-be assumed in any function based on fp-model. See :ref:`crtfastmath.o`
+other ways, the state of `fdenormal-fp-math` handling cannot
+be assumed in any function based on fp-model. See {ref}`crtfastmath.o`
for more details.
+```{eval-rst}
.. option:: -ffast-math
Enable fast-math mode. This option lets the
@@ -1651,7 +1728,9 @@ for more details.
Note: ``-ffast-math`` causes ``crtfastmath.o`` to be linked with code unless
``-shared`` or ``-mno-daz-ftz`` is present. See
:ref:`crtfastmath.o` for more details.
+```
+```{eval-rst}
.. option:: -fno-fast-math
Disable fast-math mode. This option disables unsafe floating-point
@@ -1703,7 +1782,9 @@ for more details.
Note: ``-fno-fast-math`` causes ``crtfastmath.o`` to not be linked with code
unless ``-mdaz-ftz`` is present.
+```
+```{eval-rst}
.. option:: -fdenormal-fp-math=<value>
Select which denormal numbers the code is permitted to require.
@@ -1716,7 +1797,9 @@ for more details.
The default value depends on the target. For most targets, it defaults to
``ieee``.
+```
+```{eval-rst}
.. option:: -f[no-]strict-float-cast-overflow
When a floating-point value is not representable in a destination integer
@@ -1725,7 +1808,9 @@ for more details.
With the 'no-strict' option, Clang will saturate towards the smallest and
largest representable integer values instead. NaNs will be converted to zero.
Defaults to ``-fstrict-float-cast-overflow``.
+```
+```{eval-rst}
.. option:: -f[no-]math-errno
Require math functions to indicate errors by setting errno.
@@ -1741,14 +1826,18 @@ for more details.
On some targets, math library functions never set ``errno``, and so
``-fno-math-errno`` is the default. This includes most BSD-derived
systems, including Darwin.
+```
+```{eval-rst}
.. option:: -f[no-]trapping-math
Control floating point exception behavior. ``-fno-trapping-math`` allows optimizations that assume that floating point operations cannot generate traps such as divide-by-zero, overflow and underflow.
- The option ``-ftrapping-math`` behaves identically to ``-ffp-exception-behavior=strict``.
- The option ``-fno-trapping-math`` behaves identically to ``-ffp-exception-behavior=ignore``. This is the default.
+```
+```{eval-rst}
.. option:: -ffp-contract=<value>
Specify when the compiler is permitted to form fused floating-point
@@ -1777,7 +1866,9 @@ for more details.
* ``off``: disable fusion
* ``fast-honor-pragmas``: fuse across statements unless dictated by pragmas
(default for HIP)
+```
+```{eval-rst}
.. option:: -f[no-]honor-infinities
Allow floating-point optimizations that assume arguments and results are
@@ -1786,7 +1877,9 @@ for more details.
If both ``-fno-honor-infinities`` and ``-fno-honor-nans`` are used,
has the same effect as specifying ``-ffinite-math-only``.
+```
+```{eval-rst}
.. option:: -f[no-]honor-nans
Allow floating-point optimizations that assume arguments and results are
@@ -1795,7 +1888,9 @@ for more details.
If both ``-fno-honor-infinities`` and ``-fno-honor-nans`` are used,
has the same effect as specifying ``-ffinite-math-only``.
+```
+```{eval-rst}
.. option:: -f[no-]approx-func
Allow certain math function calls (such as ``log``, ``sqrt``, ``pow``, etc)
@@ -1804,24 +1899,32 @@ for more details.
may be replaced with ``sqrt(sqrt(x))``, despite being an inexact result
in cases where ``x`` is ``-0.0`` or ``-inf``.
Defaults to ``-fno-approx-func``.
+```
+```{eval-rst}
.. option:: -f[no-]signed-zeros
Allow optimizations that ignore the sign of floating point zeros.
Defaults to ``-fsigned-zeros``.
+```
+```{eval-rst}
.. option:: -f[no-]associative-math
Allow floating point operations to be reassociated.
Defaults to ``-fno-associative-math``.
+```
+```{eval-rst}
.. option:: -f[no-]reciprocal-math
Allow division operations to be transformed into multiplication by a
reciprocal. This can be significantly faster than an ordinary division
but can also have significantly less precision. Defaults to
``-fno-reciprocal-math``.
+```
+```{eval-rst}
.. option:: -f[no-]unsafe-math-optimizations
Allow unsafe floating-point optimizations.
@@ -1848,7 +1951,9 @@ for more details.
to these options.
Defaults to ``-fno-unsafe-math-optimizations``.
+```
+```{eval-rst}
.. option:: -f[no-]finite-math-only
Allow floating-point optimizations that assume arguments and results are
@@ -1865,7 +1970,9 @@ for more details.
* ``-fhonor-nans``
Defaults to ``-fno-finite-math-only``.
+```
+```{eval-rst}
.. option:: -f[no-]rounding-math
Force floating-point operations to honor the dynamically-set rounding mode by default.
@@ -1876,7 +1983,9 @@ for more details.
- The option ``-fno-rounding-math`` allows the compiler to assume that the rounding mode is set to ``FE_TONEAREST``. This is the default.
- The option ``-frounding-math`` forces the compiler to honor the dynamically-set rounding mode. This prevents optimizations which might affect results if the rounding mode changes or is different from the default; for example, it prevents floating-point operations from being reordered across most calls and prevents constant-folding when the result is not exactly representable.
+```
+```{eval-rst}
.. option:: -ffp-model=<value>
Specify floating point behavior. ``-ffp-model`` is an umbrella
@@ -1907,7 +2016,9 @@ for more details.
option that has the effect of negating part of the ``ffp-model`` that
has been selected, then the compiler will issue a diagnostic warning
that the override has occurred.
+```
+```{eval-rst}
.. option:: -ffp-exception-behavior=<value>
Specify the floating-point exception behavior.
@@ -1918,7 +2029,9 @@ for more details.
* ``ignore`` The compiler assumes that the exception status flags will not be read and that floating point exceptions will be masked.
* ``maytrap`` The compiler avoids transformations that may raise exceptions that would not have been raised by the original code. Constant folding performed by the compiler is exempt from this option.
* ``strict`` The compiler ensures that all transformations strictly preserve the floating point exception semantics of the original code.
+```
+```{eval-rst}
.. option:: -ffp-eval-method=<value>
Specify the floating-point evaluation method for intermediate results within
@@ -1934,7 +2047,9 @@ for more details.
* ``source`` The compiler uses the floating-point type declared in the source program as the evaluation method.
* ``double`` The compiler uses ``double`` as the floating-point evaluation method for all float expressions of type that is narrower than ``double``.
* ``extended`` The compiler uses ``long double`` as the floating-point evaluation method for all float expressions of type that is narrower than ``long double``.
+```
+```{eval-rst}
.. option:: -f[no-]protect-parens
This option pertains to floating-point types, complex types with
@@ -1956,7 +2071,9 @@ for more details.
modes, such as `-ffp-model=precise` or `-ffp-model=strict`, this option
has no effect because the optimizer is prohibited from making unsafe
transformations.
+```
+```{eval-rst}
.. option:: -fexcess-precision:
The C and C++ standards allow floating-point expressions to be computed as if
@@ -1997,7 +2114,9 @@ for more details.
alias for ``standard``.
* ``16`` - Forces ``_Float16`` operations to be emitted without using excess
precision arithmetic.
+```
+```{eval-rst}
.. option:: -fcomplex-arithmetic=<value>:
This option specifies the implementation for complex multiplication and division.
@@ -2025,7 +2144,9 @@ for more details.
data type, the implementation for the complex operation using the Smith
algorithm will be used. Overflow may still occur in some cases. NaN and
infinite values are not handled.
+```
+```{eval-rst}
.. option:: -fcx-limited-range:
This option is aliased to ``-fcomplex-arithmetic=basic``. It enables the
@@ -2033,7 +2154,9 @@ for more details.
NaN checking of results. The default is ``-fno-cx-limited-range`` aliased to
``-fcomplex-arithmetic=full``. This option is enabled by the ``-ffast-math``
option.
+```
+```{eval-rst}
.. option:: -fcx-fortran-rules:
This option is aliased to ``-fcomplex-arithmetic=improved``. It enables the
@@ -2042,11 +2165,12 @@ for more details.
Complex division. Commun. ACM 5, 8 (1962).
The default is ``-fno-cx-fortran-rules`` aliased to
``-fcomplex-arithmetic=full``.
+```
+
+(floating-point-environment)=
-.. _floating-point-environment:
+#### Accessing the floating point environment
-Accessing the floating point environment
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Many targets allow floating point operations to be configured to control things
such as how inexact results should be rounded and how exceptional conditions
should be handled. This configuration is called the floating point environment.
@@ -2057,84 +2181,82 @@ on the environment (such as floating-point arithmetic and `FLT_ROUNDS`) may have
undefined behavior if the dynamic environment is not the default environment; for
example, `FLT_ROUNDS` may or may not simply return its default value for the target
instead of reading the dynamic environment, and floating-point operations may be
-optimized as if the dynamic environment were the default. Similarly, it is undefined
+optimized as if the dynamic environment were the default. Similarly, it is undefined
behavior to change the floating point environment in this default mode, for example
by calling the `fesetround` function.
C provides two pragmas to allow code to dynamically modify the floating point environment:
-- ``#pragma STDC FENV_ACCESS ON`` allows dynamic changes to the entire floating
+- `#pragma STDC FENV_ACCESS ON` allows dynamic changes to the entire floating
point environment.
-
-- ``#pragma STDC FENV_ROUND FE_DYNAMIC`` allows dynamic changes to just the floating
- point rounding mode. This may be more optimizable than ``FENV_ACCESS ON`` because
+- `#pragma STDC FENV_ROUND FE_DYNAMIC` allows dynamic changes to just the floating
+ point rounding mode. This may be more optimizable than `FENV_ACCESS ON` because
the compiler can still ignore the possibility of floating-point exceptions by default.
Both of these can be used either at the start of a block scope, in which case
they cover all code in that scope (unless they're turned off in a child scope),
or at the top level in a file, in which case they cover all subsequent function
-bodies until they're turned off. Note that it is undefined behavior to enter
+bodies until they're turned off. Note that it is undefined behavior to enter
code that is *not* covered by one of these pragmas from code that *is* covered
by one of these pragmas unless the floating point environment has been restored
-to its default state. See the C standard for more information about these pragmas.
+to its default state. See the C standard for more information about these pragmas.
-The command line option ``-frounding-math`` behaves as if the translation unit
-began with ``#pragma STDC FENV_ROUND FE_DYNAMIC``. The command line option
-``-ffp-model=strict`` behaves as if the translation unit began with ``#pragma STDC FENV_ACCESS ON``.
+The command line option `-frounding-math` behaves as if the translation unit
+began with `#pragma STDC FENV_ROUND FE_DYNAMIC`. The command line option
+`-ffp-model=strict` behaves as if the translation unit began with `#pragma STDC FENV_ACCESS ON`.
Code that just wants to use a specific rounding mode for specific floating point
operations can avoid most of the hazards of the dynamic floating point environment
-by using ``#pragma STDC FENV_ROUND`` with a value other than ``FE_DYNAMIC``.
+by using `#pragma STDC FENV_ROUND` with a value other than `FE_DYNAMIC`.
+
+(crtfastmath-o)=
-.. _crtfastmath.o:
+#### A note about `crtfastmath.o`
-A note about ``crtfastmath.o``
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-``-ffast-math`` and ``-funsafe-math-optimizations`` without the ``-shared``
-option cause ``crtfastmath.o`` to be
+`-ffast-math` and `-funsafe-math-optimizations` without the `-shared`
+option cause `crtfastmath.o` to be
automatically linked, which adds a static constructor that sets the FTZ/DAZ
bits in MXCSR, affecting not only the current compilation unit but all static
and shared libraries included in the program. This decision can be overridden
-by using either the flag ``-mdaz-ftz`` or ``-mno-daz-ftz`` to respectively
-link or not link ``crtfastmath.o``.
+by using either the flag `-mdaz-ftz` or `-mno-daz-ftz` to respectively
+link or not link `crtfastmath.o`.
+
+(flt-eval-method)=
-.. _FLT_EVAL_METHOD:
+#### A note about `__FLT_EVAL_METHOD__`
-A note about ``__FLT_EVAL_METHOD__``
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-The ``__FLT_EVAL_METHOD__`` is not defined as a traditional macro, and so it
+The `__FLT_EVAL_METHOD__` is not defined as a traditional macro, and so it
will not appear when dumping preprocessor macros. Instead, the value
-``__FLT_EVAL_METHOD__`` expands to is determined at the point of expansion
-either from the value set by the ``-ffp-eval-method`` command line option or
-from the target. This is because the ``__FLT_EVAL_METHOD__`` macro
-cannot expand to the correct evaluation method in the presence of a ``#pragma``
+`__FLT_EVAL_METHOD__` expands to is determined at the point of expansion
+either from the value set by the `-ffp-eval-method` command line option or
+from the target. This is because the `__FLT_EVAL_METHOD__` macro
+cannot expand to the correct evaluation method in the presence of a `#pragma`
which alters the evaluation method. An error is issued if
-``__FLT_EVAL_METHOD__`` is expanded inside a scope modified by
-``#pragma clang fp eval_method``.
+`__FLT_EVAL_METHOD__` is expanded inside a scope modified by
+`#pragma clang fp eval_method`.
-.. _fp-constant-eval:
+(fp-constant-eval)=
-A note about Floating Point Constant Evaluation
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+#### A note about Floating Point Constant Evaluation
In C, the only place floating point operations are guaranteed to be evaluated
during translation is in the initializers of variables of static storage
duration, which are all notionally initialized before the program begins
executing (and thus before a non-default floating point environment can be
-entered). But C++ has many more contexts where floating point constant
-evaluation occurs. Specifically: for static/thread-local variables,
+entered). But C++ has many more contexts where floating point constant
+evaluation occurs. Specifically: for static/thread-local variables,
first try evaluating the initializer in a constant context, including in the
constant floating point environment (just like in C), and then, if that fails,
fall back to emitting runtime code to perform the initialization (which might
in general be in a different floating point environment).
-Consider this example when compiled with ``-frounding-math``
+Consider this example when compiled with `-frounding-math`
- .. code-block:: console
-
- constexpr float func_01(float x, float y) {
- return x + y;
- }
- float V1 = func_01(1.0F, 0x0.000001p0F);
+> ```console
+> constexpr float func_01(float x, float y) {
+> return x + y;
+> }
+> float V1 = func_01(1.0F, 0x0.000001p0F);
+> ```
The C++ rule is that initializers for static storage duration variables are
first evaluated during translation (therefore, in the default rounding mode),
@@ -2150,15 +2272,14 @@ time.* C++ generalizes this by adding another phase of initialization
translation-time evaluation of the initializer of succeeds, it will be
treated as a constant initializer.
+(controlling-code-generation)=
-.. _controlling-code-generation:
-
-Controlling Code Generation
----------------------------
+### Controlling Code Generation
Clang provides a number of ways to control code generation. The options
are listed below.
+```{eval-rst}
.. option:: -f[no-]sanitize=check1,check2,...
Turn on runtime checks or mitigations for various forms of undefined or
@@ -2218,9 +2339,13 @@ are listed below.
It is not possible to combine more than one of the ``-fsanitize=address``,
``-fsanitize=thread``, and ``-fsanitize=memory`` checkers in the same
program.
+```
+```{eval-rst}
.. option:: -f[no-]sanitize-recover=check1,check2,...
+```
+```{eval-rst}
.. option:: -f[no-]sanitize-recover[=all]
Controls which checks enabled by ``-fsanitize=`` flag are non-fatal.
@@ -2244,9 +2369,13 @@ are listed below.
-fsanitize-trap=undefined``, the flag ``-fsanitize-recover=alignment``
will have no effect on its own; it will need to be accompanied by
``-fno-sanitize-trap=alignment``.
+```
+```{eval-rst}
.. option:: -f[no-]sanitize-trap=check1,check2,...
+```
+```{eval-rst}
.. option:: -f[no-]sanitize-trap[=all]
Controls which checks enabled by the ``-fsanitize=`` flag trap. This
@@ -2259,22 +2388,30 @@ are listed below.
checks other than ``vptr``.
This flag is enabled by default for sanitizers in the ``cfi`` group.
+```
+```{eval-rst}
.. option:: -fsanitize-ignorelist=/path/to/ignorelist/file
Disable or modify sanitizer checks for objects (source files, functions,
variables, types) listed in the file. See
:doc:`SanitizerSpecialCaseList` for file format description.
+```
+```{eval-rst}
.. option:: -fno-sanitize-ignorelist
Don't use ignorelist file, if it was specified earlier in the command line.
+```
+```{eval-rst}
.. option:: -f[no-]sanitize-coverage=[type,features,...]
Enable simple code coverage in addition to certain sanitizers.
See :doc:`SanitizerCoverage` for more details.
+```
+```{eval-rst}
.. option:: -f[no-]sanitize-address-outline-instrumentation
Controls how address sanitizer code is generated. If enabled will always use
@@ -2282,7 +2419,9 @@ are listed below.
reduce the binary size, but might result in a worse run-time performance.
See :doc: `AddressSanitizer` for more details.
+```
+```{eval-rst}
.. option:: -f[no-]sanitize-type-outline-instrumentation
Controls how type sanitizer code is generated. If enabled will always use
@@ -2291,28 +2430,38 @@ are listed below.
compilation overhead.
See :doc: `TypeSanitizer` for more details.
+```
+```{eval-rst}
.. option:: -f[no-]sanitize-stats
Enable simple statistics gathering for the enabled sanitizers.
See :doc:`SanitizerStats` for more details.
+```
+```{eval-rst}
.. option:: -fsanitize-undefined-trap-on-error
Deprecated alias for ``-fsanitize-trap=undefined``.
+```
+```{eval-rst}
.. option:: -fsanitize-cfi-cross-dso
Enable cross-DSO control flow integrity checks. This flag modifies
the behavior of sanitizers in the ``cfi`` group to allow checking
of cross-DSO virtual and indirect calls.
+```
+```{eval-rst}
.. option:: -fsanitize-cfi-icall-generalize-pointers
Generalize pointers in return and argument types in function type signatures
checked by Control Flow Integrity indirect call checking. See
:doc:`ControlFlowIntegrity` for more details.
+```
+```{eval-rst}
.. option:: -fsanitize-cfi-icall-experimental-normalize-integers
Normalize integers in return and argument types in function type signatures
@@ -2320,13 +2469,17 @@ are listed below.
:doc:`ControlFlowIntegrity` for more details.
This option is currently experimental.
+```
+```{eval-rst}
.. option:: -fsanitize-kcfi-arity
Extends kernel indirect call forward-edge control flow integrity with
additional function arity information (for supported targets). See
:doc:`ControlFlowIntegrity` for more details.
+```
+```{eval-rst}
.. option:: -fsanitize-trap-loop
When a UBSan or CFI check fails in trapping mode, spin in an infinite
@@ -2351,7 +2504,9 @@ are listed below.
- There are currently no guarantees about instructions used by other
targets.
+```
+```{eval-rst}
.. option:: -fstrict-bool
``bool`` values are stored to memory as 8-bit values on most targets. C and
@@ -2361,7 +2516,9 @@ are listed below.
assumption is violated, for instance if invalid data is ``memcpy``ed over a
``bool``, the optimized code can lead to memory corruption.
``-fstrict-bool`` is enabled by default.
+```
+```{eval-rst}
.. option:: -fno-strict-bool[={truncate|nonzero}]
Disable optimizations based on the assumption that all ``bool`` values,
@@ -2381,20 +2538,26 @@ are listed below.
that were compiled without ``-fno-strict-bool`` (or by different
compilers that have no equivalent option) will continue to behave
erratically.
+```
+```{eval-rst}
.. option:: -fstrict-vtable-pointers
Enable optimizations based on the strict rules for overwriting polymorphic
C++ objects, i.e. the vptr is invariant during an object's lifetime.
This enables better devirtualization. Turned off by default, because it is
still experimental.
+```
+```{eval-rst}
.. option:: -fwhole-program-vtables
Enable whole-program vtable optimizations, such as single-implementation
devirtualization and virtual constant propagation, for classes with
:doc:`hidden LTO visibility <LTOVisibility>`. Requires ``-flto``.
+```
+```{eval-rst}
.. option:: -f[no-]split-lto-unit
Controls splitting the :doc:`LTO unit <LTOVisibility>` into regular LTO and
@@ -2412,7 +2575,9 @@ are listed below.
However, this can increase the LTO link time and memory requirements over
pure ThinLTO, as all split regular LTO modules are merged and LTO linked
with regular LTO.
+```
+```{eval-rst}
.. option:: -fdevirtualize-speculatively
Enable speculative devirtualization optimization where a virtual call
@@ -2462,7 +2627,9 @@ are listed below.
This feature is temporarily ignored at the LLVM side when LTO is enabled.
TODO: Update the comment when the LLVM side supports this feature for LTO.
This feature is turned off by default.
+```
+```{eval-rst}
.. option:: -f[no-]unique-source-file-names
When enabled, allows the compiler to assume that each object file
@@ -2483,7 +2650,7 @@ are listed below.
$ clang -funique-source-file-names -c foo.c
$ cd ..
$ clang foo/foo.o bar/foo.o
-
+
but this is not:
.. code-block:: console
@@ -2494,18 +2661,24 @@ are listed below.
A misuse of this flag may result in a duplicate symbol error at
link time.
+```
+```{eval-rst}
.. option:: -funique-source-file-identifier=IDENTIFIER
Used with `-funique-source-file-names` to specify a source file
identifier.
+```
+```{eval-rst}
.. option:: -fforce-emit-vtables
In order to improve devirtualization, forces emitting of vtables even in
modules where it isn't necessary. It causes more inline virtual functions
to be emitted.
+```
+```{eval-rst}
.. option:: -fno-assume-sane-operator-new
Don't assume that the C++'s new operator is sane.
@@ -2513,7 +2686,9 @@ are listed below.
This option tells the compiler to do not assume that C++'s global
new operator will always return a pointer that does not alias any
other pointer when the function returns.
+```
+```{eval-rst}
.. option:: -fassume-nothrow-exception-dtor
Assume that an exception object' destructor will not throw, and generate
@@ -2525,7 +2700,9 @@ are listed below.
destroy local variables and call ``_Unwind_Resume`` for the code
``catch (...) { ... }``. This option tells Clang that an exception object's
destructor will not throw and code simplification is possible.
+```
+```{eval-rst}
.. option:: -ftrap-function=[name]
Instruct code generator to emit a function call to the specified
@@ -2539,7 +2716,9 @@ are listed below.
trap instruction. This option is useful for environments (e.g.
deeply embedded) where a trap cannot be properly handled, or when
some custom behavior is desired.
+```
+```{eval-rst}
.. option:: -ftls-model=[model]
Select which TLS model to use.
@@ -2550,14 +2729,18 @@ are listed below.
selected model is not supported by the target, or if a more
efficient model can be used. The TLS model can be overridden per
variable using the ``tls_model`` attribute.
+```
+```{eval-rst}
.. option:: -femulated-tls
Select emulated TLS model, which overrides all -ftls-model choices.
In emulated TLS mode, all access to TLS variables are converted to
calls to __emutls_get_address in the runtime library.
+```
+```{eval-rst}
.. option:: -mhwdiv=[values]
Select the ARM modes (arm or thumb) that support hardware division
@@ -2567,7 +2750,9 @@ are listed below.
This option is used to indicate which mode (arm or thumb) supports
hardware division instructions. This only applies to the ARM
architecture.
+```
+```{eval-rst}
.. option:: -m[no-]crc
Enable or disable CRC instructions.
@@ -2576,14 +2761,18 @@ are listed below.
be generated. This only applies to the ARM architecture.
CRC instructions are enabled by default on ARMv8.
+```
+```{eval-rst}
.. option:: -mgeneral-regs-only
Generate code which only uses the general purpose registers.
This option restricts the generated code to use general registers
only. This only applies to the AArch64 architecture.
+```
+```{eval-rst}
.. option:: -mcompact-branches=[values]
Control the usage of compact branches for MIPSR6.
@@ -2593,7 +2782,9 @@ are listed below.
when a delay slot cannot be filled. ``never`` disables the usage of
compact branches and ``always`` generates compact branches whenever
possible.
+```
+```{eval-rst}
.. option:: -f[no-]max-type-align=[number]
Instruct the code generator to not enforce a higher alignment than the given
@@ -2625,7 +2816,9 @@ are listed below.
// The compiler may assume that ‘v’ is 64-byte aligned, regardless of the
// value of -fmax-type-align.
}
+```
+```{eval-rst}
.. option:: -faddrsig, -fno-addrsig
Controls whether Clang emits an address-significance table into the object
@@ -2635,9 +2828,11 @@ are listed below.
relocation scanning. Address-significance tables are enabled by default
on ELF targets when using the integrated assembler. This flag currently
only has an effect on ELF targets.
+```
-.. _funique_internal_linkage_names:
+(funique-internal-linkage-names)=
+```{eval-rst}
.. option:: -f[no-]unique-internal-linkage-names
Controls whether Clang emits a unique (best-effort) symbol name for internal
@@ -2658,12 +2853,16 @@ are listed below.
$ cd $P/foo && clang -c -funique-internal-linkage-names name_conflict.c
$ cd $P/bar && clang -c -funique-internal-linkage-names name_conflict.c
$ cd $P && clang foo/name_conflict.o && bar/name_conflict.o
+```
+```{eval-rst}
.. option:: -f[no-]basic-block-address-map:
Emits a ``SHT_LLVM_BB_ADDR_MAP`` section which includes address offsets for each
basic block in the program, relative to the parent function address.
+```
+```{eval-rst}
.. option:: -fbasic-block-sections=[all, list=<arg>, none]
Controls how Clang emits text sections for basic blocks. With values ``all``
@@ -2701,7 +2900,9 @@ are listed below.
Basic block sections allow the linker to reorder basic blocks and enables
link-time optimizations like whole program inter-procedural basic block
reordering.
+```
+```{eval-rst}
.. option:: -fcodegen-data-generate[=<path>]
Emit the raw codegen (CG) data into custom sections in the object file.
@@ -2722,7 +2923,9 @@ are listed below.
$ clang -c -fuse-ld=lld -Oz -fcodegen-data-generate code.cc
$ llvm-cgdata --merge -o default.cgdata code.o
+```
+```{eval-rst}
.. option:: -fcodegen-data-use[=<path>]
Read the codegen data from the specified path to more effectively outline
@@ -2734,7 +2937,9 @@ are listed below.
.. code-block:: console
$ clang -fuse-ld=lld -Oz -Wl,--icf=safe -fcodegen-data-use code.cc
+```
+```{eval-rst}
.. option:: -falign-functions=<value>
Use at least the specified value as the alignment for emitted
@@ -2745,7 +2950,9 @@ are listed below.
This option is overridden by the ``aligned`` function attribute. If
this option is specified, ``-fpreferred-function-alignment``
is ignored.
+```
+```{eval-rst}
.. option:: -fpreferred-function-alignment=<value>
Use the specified value as the preferred alignment for emitted
@@ -2760,11 +2967,11 @@ are listed below.
If ``-falign-functions`` is specified, or if the function has an
``aligned`` attribute, this option is ignored.
+```
-.. _strict_aliasing:
+(strict-aliasing)=
-Strict Aliasing
----------------
+### Strict Aliasing
The C and C++ standards require accesses to objects in memory to use l-values of
an appropriate type for the object. This is called *strict aliasing* or
@@ -2773,59 +2980,59 @@ memory optimizations, including reordering, combining, and eliminating memory
accesses. These optimizations can lead to unexpected behavior in code that
violates the strict aliasing rules. For example:
-.. code-block:: c++
-
- void advance(size_t *index, double *data) {
- double value = data[*index];
- /* Clang may assume that this store does not change the contents of `data`. */
- *index += 1;
- /* Clang may assume that this store does not change the contents of `index`. */
- data[*index] = value;
- /* Either of these facts may create significant optimization opportunities
- if Clang is able to inline this function. */
- }
-
+```c++
+ void advance(size_t *index, double *data) {
+ double value = data[*index];
+ /* Clang may assume that this store does not change the contents of `data`. */
+ *index += 1;
+ /* Clang may assume that this store does not change the contents of `index`. */
+ data[*index] = value;
+ /* Either of these facts may create significant optimization opportunities
+ if Clang is able to inline this function. */
+}
+```
+
+```{eval-rst}
.. option:: -fstrict-aliasing, -fno-strict-aliasing
+```
-Strict aliasing can be explicitly enabled with :option:`-fstrict-aliasing` and
-disabled with :option:`-fno-strict-aliasing`. Windows MSVC platforms and UEFI
-platforms default to :option:`-fno-strict-aliasing`. Otherwise, Clang defaults
-to :option:`-fstrict-aliasing`. These options may also be affected by
-:option:`-Ofast`.
+Strict aliasing can be explicitly enabled with {option}`-fstrict-aliasing` and
+disabled with {option}`-fno-strict-aliasing`. Windows MSVC platforms and UEFI
+platforms default to {option}`-fno-strict-aliasing`. Otherwise, Clang defaults
+to {option}`-fstrict-aliasing`. These options may also be affected by
+{option}`-Ofast`.
C and C++ specify slightly different rules for strict aliasing. To improve
language interoperability, Clang allows two types to alias if either language
would permit it. This includes applying the C++ similar types rule to C,
-allowing ``int **`` to alias ``int const * const *``. Clang also relaxes the
+allowing `int **` to alias `int const * const *`. Clang also relaxes the
standard aliasing rules in the following ways:
-* All integer types of the same size are permitted to alias each other,
+- All integer types of the same size are permitted to alias each other,
including signed and unsigned types.
-* ``void*`` is permitted to alias any pointer type, ``void**`` is permitted to
+- `void*` is permitted to alias any pointer type, `void**` is permitted to
alias any pointer to pointer type, and so on.
Code which violates strict aliasing has undefined behavior. A program that
works in one version of Clang may not work in another because of changes to the
-optimizer. Clang provides a :doc:`TypeSanitizer` to help detect
+optimizer. Clang provides a {doc}`TypeSanitizer` to help detect
violations of the strict aliasing rules, but it is currently still experimental.
Code that is known to violate strict aliasing should generally be built with
-:option:`-fno-strict-aliasing` if the violation cannot be fixed.
+{option}`-fno-strict-aliasing` if the violation cannot be fixed.
Clang supports several ways to fix a violation of strict aliasing:
-* L-values of the character types ``char`` and ``unsigned char`` (as well as
+- L-values of the character types `char` and `unsigned char` (as well as
other types, depending on the standard) are permitted to access objects of
any type.
-
-* Library functions such as ``memcpy`` and ``memset`` are specified as treating
+- Library functions such as `memcpy` and `memset` are specified as treating
memory as characters and therefore are not limited by strict aliasing. If a
value of one type must be reinterpreted as another (e.g. to read the bits of a
- floating-point number), use ``memcpy`` to copy the representation to an object
+ floating-point number), use `memcpy` to copy the representation to an object
of the destination type. This has no overhead over a direct l-value access
because Clang should reliably optimize calls to these functions to use simple
loads and stores when they are used with small constant sizes.
-
-* The attribute ``may_alias`` can be added to a ``typedef`` to give l-values of
+- The attribute `may_alias` can be added to a `typedef` to give l-values of
that type the same aliasing power as the character types.
Clang makes a best effort to avoid obvious miscompilations from strict aliasing
@@ -2838,17 +3045,16 @@ In Clang 20, Clang strengthened its implementation of strict aliasing for
accesses of pointer type. Previously, all accesses of pointer type were
permitted to alias each other, but Clang now distinguishes different pointers
by their pointee type, except as limited by the relaxations around qualifiers
-and ``void*`` described above. The previous behavior of treating all pointers as
-aliasing can be restored using ``-fno-pointer-tbaa``.
+and `void*` described above. The previous behavior of treating all pointers as
+aliasing can be restored using `-fno-pointer-tbaa`.
-Profile Guided Optimization
----------------------------
+### Profile Guided Optimization
Profile information enables better optimization. For example, knowing that a
branch is taken very frequently helps the compiler make better decisions when
-ordering basic blocks. Knowing that a function ``foo`` is called more
-frequently than another function ``bar`` helps the inliner. Optimization
-levels ``-O2`` and above are recommended for use of profile guided optimization.
+ordering basic blocks. Knowing that a function `foo` is called more
+frequently than another function `bar` helps the inliner. Optimization
+levels `-O2` and above are recommended for use of profile guided optimization.
Clang supports profile guided optimization with two different kinds of
profiling. A sampling profiler can generate a profile with very low runtime
@@ -2863,35 +3069,29 @@ behavior. Code that is not exercised in the profile will be optimized as if it
is unimportant, and the compiler may make poor optimization choices for code
that is disproportionately used while profiling.
-Differences Between Sampling and Instrumentation
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+#### Differences Between Sampling and Instrumentation
Although both techniques are used for similar purposes, there are important
differences between the two:
1. Profile data generated with one cannot be used by the other, and there is no
conversion tool that can convert one to the other. So, a profile generated
- via ``-fprofile-generate`` or ``-fprofile-instr-generate`` must be used with
- ``-fprofile-use`` or ``-fprofile-instr-use``. Similarly, sampling profiles
- generated by external profilers must be converted and used with ``-fprofile-sample-use``
- or ``-fauto-profile``.
-
+ via `-fprofile-generate` or `-fprofile-instr-generate` must be used with
+ `-fprofile-use` or `-fprofile-instr-use`. Similarly, sampling profiles
+ generated by external profilers must be converted and used with `-fprofile-sample-use`
+ or `-fauto-profile`.
2. Instrumentation profile data can be used for code coverage analysis and
optimization.
-
3. Sampling profiles can only be used for optimization. They cannot be used for
code coverage analysis. Although it would be technically possible to use
sampling profiles for code coverage, sample-based profiles are too
coarse-grained for code coverage purposes; it would yield poor results.
-
4. Sampling profiles must be generated by an external tool. The profile
generated by that tool must then be converted into a format that can be read
by LLVM. The section on sampling profilers describes one of the supported
sampling profile formats.
-
-Using Sampling Profilers
-^^^^^^^^^^^^^^^^^^^^^^^^
+#### Using Sampling Profilers
Sampling profilers are used to collect runtime information, such as
hardware counters, while your application executes. They are typically
@@ -2909,187 +3109,184 @@ usual build cycle when using sample profilers for optimization:
requirement is that DWARF debug info including source line information is
generated. This DWARF information is important for the profiler to be able
to map instructions back to source line locations. The usefulness of this
- DWARF information can be improved with the ``-fdebug-info-for-profiling``
- and ``-funique-internal-linkage-names`` options.
+ DWARF information can be improved with the `-fdebug-info-for-profiling`
+ and `-funique-internal-linkage-names` options.
On Linux:
- .. code-block:: console
-
- $ clang++ -O2 -gline-tables-only \
- -fdebug-info-for-profiling -funique-internal-linkage-names \
- code.cc -o code
+ ```console
+ $ clang++ -O2 -gline-tables-only \
+ -fdebug-info-for-profiling -funique-internal-linkage-names \
+ code.cc -o code
+ ```
While MSVC-style targets default to CodeView debug information, DWARF debug
information is required to generate source-level LLVM profiles. Use
- ``-gdwarf`` to include DWARF debug information:
-
- .. code-block:: winbatch
+ `-gdwarf` to include DWARF debug information:
- > clang-cl /O2 -gdwarf -gline-tables-only ^
- /clang:-fdebug-info-for-profiling /clang:-funique-internal-linkage-names ^
- code.cc /Fe:code -fuse-ld=lld /link /debug:dwarf
+ ```winbatch
+ > clang-cl /O2 -gdwarf -gline-tables-only ^
+ /clang:-fdebug-info-for-profiling /clang:-funique-internal-linkage-names ^
+ code.cc /Fe:code -fuse-ld=lld /link /debug:dwarf
+ ```
[OPTIONAL] Pseudo instrumentation can be used as the anchor for accurate
- profile mapping with the ``-fpseudo-probe-for-profiling`` option.
+ profile mapping with the `-fpseudo-probe-for-profiling` option.
On Linux:
- .. code-block:: console
-
- $ clang++ -O2 -gline-tables-only \
- -fpseudo-probe-for-profiling -funique-internal-linkage-names \
- code.cc -o code
+ ```console
+ $ clang++ -O2 -gline-tables-only \
+ -fpseudo-probe-for-profiling -funique-internal-linkage-names \
+ code.cc -o code
+ ```
On Windows:
- .. code-block:: winbatch
+ ```winbatch
+ > clang-cl /O2 -gdwarf -gline-tables-only ^
+ -fpseudo-probe-for-profiling /clang:-funique-internal-linkage-names ^
+ code.cc /Fe:code -fuse-ld=lld /link /debug:dwarf
+ ```
- > clang-cl /O2 -gdwarf -gline-tables-only ^
- -fpseudo-probe-for-profiling /clang:-funique-internal-linkage-names ^
- code.cc /Fe:code -fuse-ld=lld /link /debug:dwarf
-
-.. note::
-
- :ref:`-funique-internal-linkage-names <funique_internal_linkage_names>`
- generates unique names based on given command-line source file paths. If
- your build system uses absolute source paths and these paths may change
- between steps 1 and 4, then the uniqued function names may change and result
- in unused profile data. Consider omitting this option in such cases.
+:::{note}
+{ref}`-funique-internal-linkage-names <funique_internal_linkage_names>`
+generates unique names based on given command-line source file paths. If
+your build system uses absolute source paths and these paths may change
+between steps 1 and 4, then the uniqued function names may change and result
+in unused profile data. Consider omitting this option in such cases.
+:::
2. Run the executable under a sampling profiler. The specific profiler
you use does not really matter, as long as its output can be converted
into the format that the LLVM optimizer understands.
Two such profilers are the Linux Perf profiler
- (https://perf.wiki.kernel.org/) and Intel's Sampling Enabling Product (SEP),
- available as part of `Intel VTune
- <https://software.intel.com/content/www/us/en/develop/tools/oneapi/components/vtune-profiler.html>`_.
+ (<https://perf.wiki.kernel.org/>) and Intel's Sampling Enabling Product (SEP),
+ available as part of [Intel VTune](https://software.intel.com/content/www/us/en/develop/tools/oneapi/components/vtune-profiler.html).
While Perf is Linux-specific, SEP can be used on Linux, Windows, and FreeBSD.
- The LLVM tool ``llvm-profgen`` can convert output of either Perf or SEP. An
- external project, `AutoFDO <https://github.com/google/autofdo>`_, also
- provides a ``create_llvm_prof`` tool which supports Linux Perf output.
+ The LLVM tool `llvm-profgen` can convert output of either Perf or SEP. An
+ external project, [AutoFDO](https://github.com/google/autofdo), also
+ provides a `create_llvm_prof` tool which supports Linux Perf output.
When using Perf:
- .. code-block:: console
-
- $ perf record -b -e BR_INST_RETIRED.NEAR_TAKEN:uppp ./code
+ ```console
+ $ perf record -b -e BR_INST_RETIRED.NEAR_TAKEN:uppp ./code
+ ```
- If the event above is unavailable, ``branches:u`` is probably next-best.
+ If the event above is unavailable, `branches:u` is probably next-best.
- Note the use of the ``-b`` flag. This tells Perf to use the Last Branch
+ Note the use of the `-b` flag. This tells Perf to use the Last Branch
Record (LBR) to record call chains. While this is not strictly required,
it provides better call information, which improves the accuracy of
the profile data.
When using SEP:
- .. code-block:: console
-
- $ sep -start -out code.tb7 -ec BR_INST_RETIRED.NEAR_TAKEN:precise=yes:pdir -lbr no_filter:usr -perf-script brstack -app ./code
+ ```console
+ $ sep -start -out code.tb7 -ec BR_INST_RETIRED.NEAR_TAKEN:precise=yes:pdir -lbr no_filter:usr -perf-script brstack -app ./code
+ ```
- This produces a ``code.perf.data.script`` output which can be used with
- ``llvm-profgen``'s ``--perfscript`` input option.
+ This produces a `code.perf.data.script` output which can be used with
+ `llvm-profgen`'s `--perfscript` input option.
3. Convert the collected profile data to LLVM's sample profile format. This is
- currently supported via the `AutoFDO <https://github.com/google/autofdo>`_
- converter ``create_llvm_prof``. Once built and installed, you can convert
- the ``perf.data`` file to LLVM using the command:
-
- .. code-block:: console
+ currently supported via the [AutoFDO](https://github.com/google/autofdo)
+ converter `create_llvm_prof`. Once built and installed, you can convert
+ the `perf.data` file to LLVM using the command:
- $ create_llvm_prof --binary=./code --out=code.prof
+ ```console
+ $ create_llvm_prof --binary=./code --out=code.prof
+ ```
- This will read ``perf.data`` and the binary file ``./code`` and emit
- the profile data in ``code.prof``. Note that if you ran ``perf``
- without the ``-b`` flag, you need to use ``--use_lbr=false`` when
- calling ``create_llvm_prof``.
+ This will read `perf.data` and the binary file `./code` and emit
+ the profile data in `code.prof`. Note that if you ran `perf`
+ without the `-b` flag, you need to use `--use_lbr=false` when
+ calling `create_llvm_prof`.
- Alternatively, the LLVM tool ``llvm-profgen`` can also be used to generate
+ Alternatively, the LLVM tool `llvm-profgen` can also be used to generate
the LLVM sample profile:
- .. code-block:: console
-
- $ llvm-profgen --binary=./code --output=code.prof --perfdata=perf.data
+ ```console
+ $ llvm-profgen --binary=./code --output=code.prof --perfdata=perf.data
+ ```
- Please note, ``perf.data`` must be collected with ``-b`` flag to Linux ``perf``
+ Please note, `perf.data` must be collected with `-b` flag to Linux `perf`
for the above step to work.
When using SEP the output is in the textual format corresponding to
- ``llvm-profgen --perfscript``. For example:
-
- .. code-block:: console
-
- $ llvm-profgen --binary=./code --output=code.prof --perfscript=code.perf.data.script
+ `llvm-profgen --perfscript`. For example:
+ ```console
+ $ llvm-profgen --binary=./code --output=code.prof --perfscript=code.perf.data.script
+ ```
4. Build the code again using the collected profile. This step feeds
the profile back to the optimizers. This should result in a binary
that executes faster than the original one. Note that you are not
required to build the code with the exact same arguments that you
used in the first step. The only requirement is that you build the code
- with the same debug info options and ``-fprofile-sample-use``. ``-gdwarf``
- and ``-gline-tables-only`` can be omitted if you do not need debug info
+ with the same debug info options and `-fprofile-sample-use`. `-gdwarf`
+ and `-gline-tables-only` can be omitted if you do not need debug info
in the final binary.
On Linux:
- .. code-block:: console
-
- $ clang++ -O2 \
- -fdebug-info-for-profiling -funique-internal-linkage-names \
- -fprofile-sample-use=code.prof code.cc -o code
+ ```console
+ $ clang++ -O2 \
+ -fdebug-info-for-profiling -funique-internal-linkage-names \
+ -fprofile-sample-use=code.prof code.cc -o code
+ ```
On Windows:
- .. code-block:: winbatch
-
- > clang-cl /O2 ^
- /clang:-fdebug-info-for-profiling /clang:-funique-internal-linkage-names ^
- -fprofile-sample-use=code.prof code.cc /Fe:code
+ ```winbatch
+ > clang-cl /O2 ^
+ /clang:-fdebug-info-for-profiling /clang:-funique-internal-linkage-names ^
+ -fprofile-sample-use=code.prof code.cc /Fe:code
+ ```
[OPTIONAL] Pseudo instrumentation can be used as the anchor for accurate
- profile mapping with the ``-fpseudo-probe-for-profiling`` option.
+ profile mapping with the `-fpseudo-probe-for-profiling` option.
On Linux:
- .. code-block:: console
-
- $ clang++ -O2 \
- -fpseudo-probe-for-profiling -funique-internal-linkage-names \
- -fprofile-sample-use=code.prof code.cc -o code
+ ```console
+ $ clang++ -O2 \
+ -fpseudo-probe-for-profiling -funique-internal-linkage-names \
+ -fprofile-sample-use=code.prof code.cc -o code
+ ```
On Windows:
- .. code-block:: winbatch
-
- > clang-cl /O2 ^
- -fpseudo-probe-for-profiling /clang:-funique-internal-linkage-names ^
- -fprofile-sample-use=code.prof code.cc /Fe:code
+ ```winbatch
+ > clang-cl /O2 ^
+ -fpseudo-probe-for-profiling /clang:-funique-internal-linkage-names ^
+ -fprofile-sample-use=code.prof code.cc /Fe:code
+ ```
[OPTIONAL] Sampling-based profiles can have inaccuracies or missing block/
edge counters. The profile inference algorithm (profi) can be used to infer
missing blocks and edge counts, and improve the quality of profile data.
- Enable it with ``-fsample-profile-use-profi``. For example, on Linux:
-
- .. code-block:: console
+ Enable it with `-fsample-profile-use-profi`. For example, on Linux:
- $ clang++ -fsample-profile-use-profi -O2 \
- -fdebug-info-for-profiling -funique-internal-linkage-names \
- -fprofile-sample-use=code.prof code.cc -o code
+ ```console
+ $ clang++ -fsample-profile-use-profi -O2 \
+ -fdebug-info-for-profiling -funique-internal-linkage-names \
+ -fprofile-sample-use=code.prof code.cc -o code
+ ```
On Windows:
- .. code-block:: winbatch
-
- > clang-cl /clang:-fsample-profile-use-profi /O2 ^
- /clang:-fdebug-info-for-profiling /clang:-funique-internal-linkage-names ^
- -fprofile-sample-use=code.prof code.cc /Fe:code
+ ```winbatch
+ > clang-cl /clang:-fsample-profile-use-profi /O2 ^
+ /clang:-fdebug-info-for-profiling /clang:-funique-internal-linkage-names ^
+ -fprofile-sample-use=code.prof code.cc /Fe:code
+ ```
-Sample Profile Formats
-""""""""""""""""""""""
+##### Sample Profile Formats
Since external profilers generate profile data in a variety of custom formats,
the data generated by the profiler must be converted into a format that can be
@@ -3098,44 +3295,40 @@ read by the backend. LLVM supports three different sample profile formats:
1. ASCII text. This is the easiest one to generate. The file is divided into
sections, which correspond to each of the functions with profile
information. The format is described below. It can also be generated from
- the binary or gcov formats using the ``llvm-profdata`` tool.
-
+ the binary or gcov formats using the `llvm-profdata` tool.
2. Binary encoding. This uses a more efficient encoding that yields smaller
- profile files. This is the format generated by the ``create_llvm_prof`` tool
- in https://github.com/google/autofdo.
-
+ profile files. This is the format generated by the `create_llvm_prof` tool
+ in <https://github.com/google/autofdo>.
3. GCC encoding. This is based on the gcov format, which is accepted by GCC. It
is only interesting in environments where GCC and Clang co-exist. This
- encoding is only generated by the ``create_gcov`` tool in
- https://github.com/google/autofdo. It can be read by LLVM and
- ``llvm-profdata``, but it cannot be generated by either.
+ encoding is only generated by the `create_gcov` tool in
+ <https://github.com/google/autofdo>. It can be read by LLVM and
+ `llvm-profdata`, but it cannot be generated by either.
If you are using Linux Perf to generate sampling profiles, you can use the
-conversion tool ``create_llvm_prof`` described in the previous section.
+conversion tool `create_llvm_prof` described in the previous section.
Otherwise, you will need to write a conversion tool that converts your
profiler's native format into one of these three.
-
-Sample Profile Text Format
-""""""""""""""""""""""""""
+##### Sample Profile Text Format
This section describes the ASCII text format for sampling profiles. It is,
arguably, the easiest one to generate. If you are interested in generating any
-of the other two, consult the ``ProfileData`` library in LLVM's source tree
-(specifically, ``include/llvm/ProfileData/SampleProfReader.h``).
-
-.. code-block:: console
-
- function1:total_samples:total_head_samples
- offset1[.discriminator]: number_of_samples [fn1:num fn2:num ... ]
- offset2[.discriminator]: number_of_samples [fn3:num fn4:num ... ]
- ...
- offsetN[.discriminator]: number_of_samples [fn5:num fn6:num ... ]
- offsetA[.discriminator]: fnA:num_of_total_samples
- offsetA1[.discriminator]: number_of_samples [fn7:num fn8:num ... ]
- offsetA1[.discriminator]: number_of_samples [fn9:num fn10:num ... ]
- offsetB[.discriminator]: fnB:num_of_total_samples
- offsetB1[.discriminator]: number_of_samples [fn11:num fn12:num ... ]
+of the other two, consult the `ProfileData` library in LLVM's source tree
+(specifically, `include/llvm/ProfileData/SampleProfReader.h`).
+
+```console
+function1:total_samples:total_head_samples
+ offset1[.discriminator]: number_of_samples [fn1:num fn2:num ... ]
+ offset2[.discriminator]: number_of_samples [fn3:num fn4:num ... ]
+ ...
+ offsetN[.discriminator]: number_of_samples [fn5:num fn6:num ... ]
+ offsetA[.discriminator]: fnA:num_of_total_samples
+ offsetA1[.discriminator]: number_of_samples [fn7:num fn8:num ... ]
+ offsetA1[.discriminator]: number_of_samples [fn9:num fn10:num ... ]
+ offsetB[.discriminator]: fnB:num_of_total_samples
+ offsetB1[.discriminator]: number_of_samples [fn11:num fn12:num ... ]
+```
This is a nested tree in which the indentation represents the nesting level
of the inline stack. There are no blank lines in the file. And the spacing
@@ -3158,16 +3351,15 @@ count provides an indicator of how frequently the function is invoked.
There are two types of lines in the function body.
-- Sampled line represents the profile information of a source location.
- ``offsetN[.discriminator]: number_of_samples [fn5:num fn6:num ... ]``
-
-- Callsite line represents the profile information of an inlined callsite.
- ``offsetA[.discriminator]: fnA:num_of_total_samples``
+- Sampled line represents the profile information of a source location.
+ `offsetN[.discriminator]: number_of_samples [fn5:num fn6:num ... ]`
+- Callsite line represents the profile information of an inlined callsite.
+ `offsetA[.discriminator]: fnA:num_of_total_samples`
Each sampled line may contain several items. Some are optional (marked
below):
-a. Source line offset. This number represents the line number
+1. Source line offset. This number represents the line number
in the function where the sample was collected. The line number is
always relative to the line where symbol of the function is
defined. So, if the function has its header at line 280, the offset
@@ -3181,65 +3373,64 @@ a. Source line offset. This number represents the line number
will not be able to associate a meaningful weight to the instructions
in the macro).
-b. [OPTIONAL] Discriminator. This is used if the sampled program
+2. [OPTIONAL] Discriminator. This is used if the sampled program
was compiled with DWARF discriminator support
- (http://wiki.dwarfstd.org/index.php?title=Path_Discriminators).
+ (<http://wiki.dwarfstd.org/index.php?title=Path_Discriminators>).
DWARF discriminators are unsigned integer values that allow the
compiler to distinguish between multiple execution paths on the
same source line location.
- For example, consider the line of code ``if (cond) foo(); else bar();``.
- If the predicate ``cond`` is true 80% of the time, then the edge
- into function ``foo`` should be considered to be taken most of the
- time. But both calls to ``foo`` and ``bar`` are at the same source
+ For example, consider the line of code `if (cond) foo(); else bar();`.
+ If the predicate `cond` is true 80% of the time, then the edge
+ into function `foo` should be considered to be taken most of the
+ time. But both calls to `foo` and `bar` are at the same source
line, so a sample count at that line is not sufficient. The
compiler needs to know which part of that line is taken more
frequently.
This is what discriminators provide. In this case, the calls to
- ``foo`` and ``bar`` will be at the same line, but will have
+ `foo` and `bar` will be at the same line, but will have
different discriminator values. This allows the compiler to correctly
- set edge weights into ``foo`` and ``bar``.
+ set edge weights into `foo` and `bar`.
-c. Number of samples. This is an integer quantity representing the
+3. Number of samples. This is an integer quantity representing the
number of samples collected by the profiler at this source
location.
-d. [OPTIONAL] Potential call targets and samples. If present, this
+4. [OPTIONAL] Potential call targets and samples. If present, this
line contains a call instruction. This models both direct and
number of samples. For example,
- .. code-block:: console
-
- 130: 7 foo:3 bar:2 baz:7
+ ```console
+ 130: 7 foo:3 bar:2 baz:7
+ ```
The above means that at relative line offset 130 there is a call
- instruction that calls one of ``foo()``, ``bar()`` and ``baz()``,
- with ``baz()`` being the relatively more frequently called target.
+ instruction that calls one of `foo()`, `bar()` and `baz()`,
+ with `baz()` being the relatively more frequently called target.
-As an example, consider a program with the call chain ``main -> foo -> bar``.
+As an example, consider a program with the call chain `main -> foo -> bar`.
When built with optimizations enabled, the compiler may inline the
-calls to ``bar`` and ``foo`` inside ``main``. The generated profile
+calls to `bar` and `foo` inside `main`. The generated profile
could then be something like this:
-.. code-block:: console
-
- main:35504:0
- 1: _Z3foov:35504
- 2: _Z32bari:31977
- 1.1: 31977
- 2: 0
+```console
+main:35504:0
+1: _Z3foov:35504
+ 2: _Z32bari:31977
+ 1.1: 31977
+2: 0
+```
This profile indicates that there were a total of 35,504 samples
-collected in main. All of those were at line 1 (the call to ``foo``).
-Of those, 31,977 were spent inside the body of ``bar``. The last line
-of the profile (``2: 0``) corresponds to line 2 inside ``main``. No
+collected in main. All of those were at line 1 (the call to `foo`).
+Of those, 31,977 were spent inside the body of `bar`. The last line
+of the profile (`2: 0`) corresponds to line 2 inside `main`. No
samples were collected there.
-.. _prof_instr:
+(prof-instr)=
-Profiling with Instrumentation
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+#### Profiling with Instrumentation
Clang also supports profiling via instrumentation. This requires building a
special instrumented version of the code and has some runtime
@@ -3248,109 +3439,109 @@ sampling profiler. It also provides reproducible results, at least to the
extent that the code behaves consistently across runs.
Clang supports two types of instrumentation: frontend-based and IR-based.
-Frontend-based instrumentation can be enabled with the option ``-fprofile-instr-generate``,
-and IR-based instrumentation can be enabled with the option ``-fprofile-generate``.
+Frontend-based instrumentation can be enabled with the option `-fprofile-instr-generate`,
+and IR-based instrumentation can be enabled with the option `-fprofile-generate`.
For best performance with PGO, IR-based instrumentation should be used. It has
the benefits of lower instrumentation overhead, smaller raw profile size, and
better runtime performance. Frontend-based instrumentation, on the other hand,
has better source correlation, so it should be used with source line-based
coverage testing.
-The flag ``-fcs-profile-generate`` also instruments programs using the same
-instrumentation method as ``-fprofile-generate``. However, it performs a
+The flag `-fcs-profile-generate` also instruments programs using the same
+instrumentation method as `-fprofile-generate`. However, it performs a
post-inline late instrumentation and can produce context-sensitive profiles.
-
Here are the steps for using profile guided optimization with
instrumentation:
1. Build an instrumented version of the code by compiling and linking with the
- ``-fprofile-generate`` or ``-fprofile-instr-generate`` option.
-
- .. code-block:: console
+ `-fprofile-generate` or `-fprofile-instr-generate` option.
- $ clang++ -O2 -fprofile-instr-generate code.cc -o code
+ ```console
+ $ clang++ -O2 -fprofile-instr-generate code.cc -o code
+ ```
2. Run the instrumented executable with inputs that reflect the typical usage.
- By default, the profile data will be written to a ``default.profraw`` file
+ By default, the profile data will be written to a `default.profraw` file
in the current directory. You can override that default by using option
- ``-fprofile-instr-generate=`` or by setting the ``LLVM_PROFILE_FILE``
+ `-fprofile-instr-generate=` or by setting the `LLVM_PROFILE_FILE`
environment variable to specify an alternate file. If non-default file name
is specified by both the environment variable and the command line option,
the environment variable takes precedence. The file name pattern specified
- can include different modifiers: ``%p``, ``%h``, ``%m``, ``%b``, ``%t``, and
- ``%c``.
+ can include different modifiers: `%p`, `%h`, `%m`, `%b`, `%t`, and
+ `%c`.
- Any instance of ``%p`` in that file name will be replaced by the process
+ Any instance of `%p` in that file name will be replaced by the process
ID, so that you can easily distinguish the profile output from multiple
runs.
- .. code-block:: console
-
- $ LLVM_PROFILE_FILE="code-%p.profraw" ./code
+ ```console
+ $ LLVM_PROFILE_FILE="code-%p.profraw" ./code
+ ```
- The modifier ``%h`` can be used in scenarios where the same instrumented
+ The modifier `%h` can be used in scenarios where the same instrumented
binary is run in multiple different host machines dumping profile data
- to a shared network based storage. The ``%h`` specifier will be substituted
+ to a shared network based storage. The `%h` specifier will be substituted
with the hostname so that profiles collected from different hosts do not
clobber each other.
- While the use of ``%p`` specifier can reduce the likelihood for the profiles
+ While the use of `%p` specifier can reduce the likelihood for the profiles
dumped from different processes to clobber each other, such clobbering can still
- happen because of the ``pid`` re-use by the OS. Another side-effect of using
- ``%p`` is that the storage requirement for raw profile data files is greatly
- increased. To avoid issues like this, the ``%m`` specifier can used in the profile
- name. When this specifier is used, the profiler runtime will substitute ``%m``
+ happen because of the `pid` re-use by the OS. Another side-effect of using
+ `%p` is that the storage requirement for raw profile data files is greatly
+ increased. To avoid issues like this, the `%m` specifier can used in the profile
+ name. When this specifier is used, the profiler runtime will substitute `%m`
with an integer identifier associated with the instrumented binary. Additionally,
multiple raw profiles dumped from different processes that share a file system (can be
on different hosts) will be automatically merged by the profiler runtime during the
dumping. If the program links in multiple instrumented shared libraries, each library
will dump the profile data into its own profile data file (with its integer
- id embedded in the profile name). Note that the merging enabled by ``%m`` is for raw
+ id embedded in the profile name). Note that the merging enabled by `%m` is for raw
profile data generated by profiler runtime. The resulting merged "raw" profile data
file still needs to be converted to a different format expected by the compiler (
see step 3 below).
- .. code-block:: console
-
- $ LLVM_PROFILE_FILE="code-%m.profraw" ./code
+ ```console
+ $ LLVM_PROFILE_FILE="code-%m.profraw" ./code
+ ```
- Although rare, binary signatures used by the ``%m`` specifier can have
- collisions. In this case, the ``%b`` specifier, which expands to the binary
+ Although rare, binary signatures used by the `%m` specifier can have
+ collisions. In this case, the `%b` specifier, which expands to the binary
ID (build ID in ELF and COFF), can be added. To use it, the program should be
- compiled with the build ID linker option (``--build-id`` for GNU ld or LLD,
- ``/build-id`` for lld-link on Windows). Linux, Windows and AIX are supported.
+ compiled with the build ID linker option (`--build-id` for GNU ld or LLD,
+ `/build-id` for lld-link on Windows). Linux, Windows and AIX are supported.
- See `this <SourceBasedCodeCoverage.html#running-the-instrumented-program>`_ section
- about the ``%t``, and ``%c`` modifiers.
+ See [this](SourceBasedCodeCoverage.html#running-the-instrumented-program) section
+ about the `%t`, and `%c` modifiers.
3. Combine profiles from multiple runs and convert the "raw" profile format to
- the input expected by clang. Use the ``merge`` command of the
- ``llvm-profdata`` tool to do this.
+ the input expected by clang. Use the `merge` command of the
+ `llvm-profdata` tool to do this.
- .. code-block:: console
-
- $ llvm-profdata merge -output=code.profdata code-*.profraw
+ ```console
+ $ llvm-profdata merge -output=code.profdata code-*.profraw
+ ```
Note that this step is necessary even when there is only one "raw" profile,
since the merge operation also changes the file format.
-4. Build the code again using the ``-fprofile-use`` or ``-fprofile-instr-use``
+4. Build the code again using the `-fprofile-use` or `-fprofile-instr-use`
option to specify the collected profile data.
- .. code-block:: console
-
- $ clang++ -O2 -fprofile-instr-use=code.profdata code.cc -o code
+ ```console
+ $ clang++ -O2 -fprofile-instr-use=code.profdata code.cc -o code
+ ```
You can repeat step 4 as often as you like without regenerating the
profile. As you make changes to your code, clang may no longer be able to
use the profile data. It will warn you when this happens.
-Note that ``-fprofile-use`` option is semantically equivalent to
+Note that `-fprofile-use` option is semantically equivalent to
its GCC counterpart, it *does not* handle profile formats produced by GCC.
-Both ``-fprofile-use`` and ``-fprofile-instr-use`` accept profiles in the
+Both `-fprofile-use` and `-fprofile-instr-use` accept profiles in the
indexed format, regardeless whether it is produced by frontend or the IR pass.
+```{eval-rst}
.. option:: -fprofile-generate[=<dirname>]
The ``-fprofile-generate`` and ``-fprofile-generate=`` flags will use
@@ -3383,7 +3574,9 @@ indexed format, regardeless whether it is produced by frontend or the IR pass.
the directory and filename for the profile file at runtime.
To override the path and filename at compile time, use
``-Xclang -fprofile-instrument-path=/path/to/file_pattern.profraw``.
+```
+```{eval-rst}
.. option:: -fcs-profile-generate[=<dirname>]
The ``-fcs-profile-generate`` and ``-fcs-profile-generate=`` flags will use
@@ -3422,14 +3615,18 @@ indexed format, regardeless whether it is produced by frontend or the IR pass.
The above command will read both profiles to the compiler at the identical
point of instrumentations.
+```
+```{eval-rst}
.. option:: -fprofile-use[=<pathname>]
Without any other arguments, ``-fprofile-use`` behaves identically to
``-fprofile-instr-use``. Otherwise, if ``pathname`` is the full path to a
profile file, it reads from that file. If ``pathname`` is a directory name,
it reads from ``pathname/default.profdata``.
+```
+```{eval-rst}
.. option:: -fprofile-update[=<method>]
Unless ``-fsanitize=thread`` is specified, the default is ``single``, which
@@ -3437,7 +3634,9 @@ indexed format, regardeless whether it is produced by frontend or the IR pass.
contention. ``atomic`` uses atomic increments which is accurate but has
overhead. ``prefer-atomic`` will be transformed to ``atomic`` when supported
by the target, or ``single`` otherwise.
+```
+```{eval-rst}
.. option:: -fprofile-continuous
Enables the continuous instrumentation profiling where profile counter updates
@@ -3455,7 +3654,9 @@ indexed format, regardeless whether it is produced by frontend or the IR pass.
does not call ``exit()``, in continuous mode the profile collected up to the
point of termination will be available in ``default_xxxx.profraw`` while in
the non-continuous mode, no profile file is generated.
+```
+```{eval-rst}
.. option:: -ftemporal-profile
Enables the temporal profiling extension for IRPGO to improve startup time by
@@ -3487,142 +3688,141 @@ indexed format, regardeless whether it is produced by frontend or the IR pass.
For more information, please read the RFC:
https://discourse.llvm.org/t/rfc-temporal-profiling-extension-for-irpgo/68068
+```
-Fine Tuning Profile Collection
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+#### Fine Tuning Profile Collection
The PGO infrastructure provides user program knobs to fine tune profile
collection. Specifically, the PGO runtime provides the following functions
that can be used to control the regions in the program where profiles should
be collected.
- * ``void __llvm_profile_set_filename(const char *Name)``: changes the name of
- the profile file to ``Name``.
- * ``void __llvm_profile_reset_counters(void)``: resets all counters to zero.
- * ``int __llvm_profile_dump(void)``: write the profile data to disk.
+> - `void __llvm_profile_set_filename(const char *Name)`: changes the name of
+> the profile file to `Name`.
+> - `void __llvm_profile_reset_counters(void)`: resets all counters to zero.
+> - `int __llvm_profile_dump(void)`: write the profile data to disk.
For example, the following pattern can be used to skip profiling program
initialization, profile two specific hot regions, and skip profiling program
cleanup:
-.. code-block:: c
-
- int main() {
- initialize();
-
- // Reset all profile counters to 0 to omit profile collected during
- // initialize()'s execution.
- __llvm_profile_reset_counters();
- ... hot region 1
- // Dump the profile for hot region 1.
- __llvm_profile_set_filename("region1.profraw");
- __llvm_profile_dump();
-
- // Reset counters before proceeding to hot region 2.
- __llvm_profile_reset_counters();
- ... hot region 2
- // Dump the profile for hot region 2.
- __llvm_profile_set_filename("region2.profraw");
- __llvm_profile_dump();
-
- // Since the profile has been dumped, no further profile data
- // will be collected beyond the above __llvm_profile_dump().
- cleanup();
- return 0;
- }
+```c
+int main() {
+ initialize();
+
+ // Reset all profile counters to 0 to omit profile collected during
+ // initialize()'s execution.
+ __llvm_profile_reset_counters();
+ ... hot region 1
+ // Dump the profile for hot region 1.
+ __llvm_profile_set_filename("region1.profraw");
+ __llvm_profile_dump();
+
+ // Reset counters before proceeding to hot region 2.
+ __llvm_profile_reset_counters();
+ ... hot region 2
+ // Dump the profile for hot region 2.
+ __llvm_profile_set_filename("region2.profraw");
+ __llvm_profile_dump();
+
+ // Since the profile has been dumped, no further profile data
+ // will be collected beyond the above __llvm_profile_dump().
+ cleanup();
+ return 0;
+}
+```
These APIs' names can be introduced to user programs in two ways.
They can be declared as weak symbols on platforms which support
-treating weak symbols as ``null`` during linking. For example, the user can
+treating weak symbols as `null` during linking. For example, the user can
have
-.. code-block:: c
-
- __attribute__((weak)) int __llvm_profile_dump(void);
+```c
+__attribute__((weak)) int __llvm_profile_dump(void);
- // Then later in the same source file
- if (__llvm_profile_dump)
- if (__llvm_profile_dump() != 0) { ... }
- // The first if condition tests if the symbol is actually defined.
- // Profile dumping only happens if the symbol is defined. Hence,
- // the user program works correctly during normal (not profile-generate)
- // executions.
+// Then later in the same source file
+if (__llvm_profile_dump)
+ if (__llvm_profile_dump() != 0) { ... }
+// The first if condition tests if the symbol is actually defined.
+// Profile dumping only happens if the symbol is defined. Hence,
+// the user program works correctly during normal (not profile-generate)
+// executions.
+```
Alternatively, the user program can include the header
-``profile/instr_prof_interface.h``, which contains the API names. For example,
-
-.. code-block:: c
+`profile/instr_prof_interface.h`, which contains the API names. For example,
- #include "profile/instr_prof_interface.h"
+```c
+#include "profile/instr_prof_interface.h"
- // Then later in the same source file
- if (__llvm_profile_dump() != 0) { ... }
+// Then later in the same source file
+if (__llvm_profile_dump() != 0) { ... }
+```
The user code does not need to check if the API names are defined, because
-these names are automatically replaced by ``(0)`` or the equivalence of noop
-if the ``clang`` is not compiling for profile generation.
+these names are automatically replaced by `(0)` or the equivalence of noop
+if the `clang` is not compiling for profile generation.
-Such replacement can happen because ``clang`` adds one of two macros depending
-on the ``-fprofile-generate`` and the ``-fprofile-use`` flags.
+Such replacement can happen because `clang` adds one of two macros depending
+on the `-fprofile-generate` and the `-fprofile-use` flags.
- * ``__LLVM_INSTR_PROFILE_GENERATE``: defined when one of
- ``-fprofile[-instr]-generate``/``-fcs-profile-generate`` is in effect.
- * ``__LLVM_INSTR_PROFILE_USE``: defined when one of
- ``-fprofile-use``/``-fprofile-instr-use`` is in effect.
+> - `__LLVM_INSTR_PROFILE_GENERATE`: defined when one of
+> `-fprofile[-instr]-generate`/`-fcs-profile-generate` is in effect.
+> - `__LLVM_INSTR_PROFILE_USE`: defined when one of
+> `-fprofile-use`/`-fprofile-instr-use` is in effect.
The two macros can be used to provide more flexibility so a user program
can execute code specifically intended for profile generate or profile use.
For example, a user program can have special logging during profile generate:
-.. code-block:: c
-
- #if __LLVM_INSTR_PROFILE_GENERATE
- expensive_logging_of_full_program_state();
- #endif
+```c
+#if __LLVM_INSTR_PROFILE_GENERATE
+expensive_logging_of_full_program_state();
+#endif
+```
The logging is automatically excluded during a normal build of the program,
hence it does not impact performance during a normal execution.
It is advised to use such fine tuning only in a program's cold regions. The weak
-symbols can introduce extra control flow (the ``if`` checks), while the macros
-(hence declarations they guard in ``profile/instr_prof_interface.h``)
+symbols can introduce extra control flow (the `if` checks), while the macros
+(hence declarations they guard in `profile/instr_prof_interface.h`)
can change the control flow of the functions that use them between profile
generation and profile use (which can lead to discarded counters in such
functions). Using these APIs in the program's cold regions introduces less
overhead and leads to more optimized code.
-Disabling Instrumentation
-^^^^^^^^^^^^^^^^^^^^^^^^^
+#### Disabling Instrumentation
In certain situations, it may be useful to disable profile generation or use
for specific files in a build, without affecting the main compilation flags
used for the other files in the project.
-In these cases, you can use the flag ``-fno-profile-instr-generate`` (or
-``-fno-profile-generate``) to disable profile generation, and
-``-fno-profile-instr-use`` (or ``-fno-profile-use``) to disable profile use.
+In these cases, you can use the flag `-fno-profile-instr-generate` (or
+`-fno-profile-generate`) to disable profile generation, and
+`-fno-profile-instr-use` (or `-fno-profile-use`) to disable profile use.
Note that these flags should appear after the corresponding profile
flags to have an effect.
-.. note::
-
- When none of the translation units inside a binary is instrumented, in the
- case of Fuchsia the profile runtime will not be linked into the binary and
- no profile will be produced, while on other platforms the profile runtime
- will be linked and profile will be produced but there will not be any
- counters.
+:::{note}
+When none of the translation units inside a binary is instrumented, in the
+case of Fuchsia the profile runtime will not be linked into the binary and
+no profile will be produced, while on other platforms the profile runtime
+will be linked and profile will be produced but there will not be any
+counters.
+:::
-Instrumenting only selected files or functions
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+#### Instrumenting only selected files or functions
-Sometimes it's useful to only instrument certain files or functions. For
+Sometimes it's useful to only instrument certain files or functions. For
example in automated testing infrastructure, it may be desirable to only
instrument files or functions that were modified by a patch to reduce the
overhead of instrumenting a full system.
-This can be done using the ``-fprofile-list`` option.
+This can be done using the `-fprofile-list` option.
+```{eval-rst}
.. option:: -fprofile-list=<pathname>
This option can be used to apply profile instrumentation only to selected
@@ -3639,68 +3839,69 @@ This can be done using the ``-fprofile-list`` option.
.. code-block:: console
$ clang++ -O2 -fprofile-instr-generate -fcoverage-mapping -fprofile-list=fun.list -fprofile-list=code.list code.cc -o code
-
-Supported sections are ``[clang]``, ``[llvm]``, ``[csllvm]``, and ``[sample-coldcov]`` representing
-clang PGO, IRPGO, CSIRPGO and sample PGO based cold function coverage, respectively. Supported prefixes
-are ``function`` and ``source``. Supported categories are ``allow``, ``skip``, and ``forbid``.
-``skip`` adds the ``skipprofile`` attribute while ``forbid`` adds the
-``noprofile`` attribute to the appropriate function. Use
-``default:<allow|skip|forbid>`` to specify the default category.
-
- .. code-block:: console
-
- $ cat fun.list
- # The following cases are for clang instrumentation.
- [clang]
-
- # We might not want to profile functions that are inlined in many places.
- function:inlinedLots=skip
-
- # We want to forbid profiling where it might be dangerous.
- source:lib/unsafe/*.cc=forbid
-
- # Otherwise we allow profiling.
- default:allow
-
-Older Prefixes
-""""""""""""""
- An older format is also supported, but it is only able to add the
- ``noprofile`` attribute.
- To filter individual functions or entire source files use ``fun:<name>`` or
- ``src:<file>`` respectively. To exclude a function or a source file, use
- ``!fun:<name>`` or ``!src:<file>`` respectively. The format also supports
- wildcard expansion. The compiler generated functions are assumed to be located
- in the main source file. It is also possible to restrict the filter to a
- particular instrumentation type by using a named section.
-
- .. code-block:: none
-
- # all functions whose name starts with foo will be instrumented.
- fun:foo*
-
- # except for foo1 which will be excluded from instrumentation.
- !fun:foo1
-
- # every function in path/to/foo.cc will be instrumented.
- src:path/to/foo.cc
-
- # bar will be instrumented only when using backend instrumentation.
- # Recognized section names are clang, llvm and csllvm.
- [llvm]
- fun:bar
-
- When the file contains only excludes, all files and functions except for the
- excluded ones will be instrumented. Otherwise, only the files and functions
- specified will be instrumented.
-
-Instrument function groups
-^^^^^^^^^^^^^^^^^^^^^^^^^^
+```
+
+Supported sections are `[clang]`, `[llvm]`, `[csllvm]`, and `[sample-coldcov]` representing
+clang PGO, IRPGO, CSIRPGO and sample PGO based cold function coverage, respectively. Supported prefixes
+are `function` and `source`. Supported categories are `allow`, `skip`, and `forbid`.
+`skip` adds the `skipprofile` attribute while `forbid` adds the
+`noprofile` attribute to the appropriate function. Use
+`default:<allow|skip|forbid>` to specify the default category.
+
+> ```console
+> $ cat fun.list
+> # The following cases are for clang instrumentation.
+> [clang]
+>
+> # We might not want to profile functions that are inlined in many places.
+> function:inlinedLots=skip
+>
+> # We want to forbid profiling where it might be dangerous.
+> source:lib/unsafe/*.cc=forbid
+>
+> # Otherwise we allow profiling.
+> default:allow
+> ```
+
+##### Older Prefixes
+
+> An older format is also supported, but it is only able to add the
+> `noprofile` attribute.
+> To filter individual functions or entire source files use `fun:<name>` or
+> `src:<file>` respectively. To exclude a function or a source file, use
+> `!fun:<name>` or `!src:<file>` respectively. The format also supports
+> wildcard expansion. The compiler generated functions are assumed to be located
+> in the main source file. It is also possible to restrict the filter to a
+> particular instrumentation type by using a named section.
+>
+> ```none
+> # all functions whose name starts with foo will be instrumented.
+> fun:foo*
+>
+> # except for foo1 which will be excluded from instrumentation.
+> !fun:foo1
+>
+> # every function in path/to/foo.cc will be instrumented.
+> src:path/to/foo.cc
+>
+> # bar will be instrumented only when using backend instrumentation.
+> # Recognized section names are clang, llvm and csllvm.
+> [llvm]
+> fun:bar
+> ```
+>
+> When the file contains only excludes, all files and functions except for the
+> excluded ones will be instrumented. Otherwise, only the files and functions
+> specified will be instrumented.
+
+#### Instrument function groups
Sometimes it is desirable to minimize the size overhead of instrumented
binaries. One way to do this is to partition functions into groups and only
instrument functions in a specified group. This can be done using the
`-fprofile-function-groups` and `-fprofile-selected-function-group` options.
+```{eval-rst}
.. option:: -fprofile-function-groups=<N>, -fprofile-selected-function-group=<i>
The following uses 3 groups
@@ -3718,87 +3919,89 @@ instrument functions in a specified group. This can be done using the
$ llvm-profdata merge -output=code.profdata group_*/*.profraw
+```
-Profile remapping
-^^^^^^^^^^^^^^^^^
+#### Profile remapping
When the program is compiled after a change that affects many symbol names,
pre-existing profile data may no longer match the program. For example:
- * switching from libstdc++ to libc++ will result in the mangled names of all
- functions taking standard library types to change
- * renaming a widely-used type in C++ will result in the mangled names of all
- functions that have parameters involving that type to change
- * moving from a 32-bit compilation to a 64-bit compilation may change the
- underlying type of ``size_t`` and similar types, resulting in changes to
- manglings
+> - switching from libstdc++ to libc++ will result in the mangled names of all
+> functions taking standard library types to change
+> - renaming a widely-used type in C++ will result in the mangled names of all
+> functions that have parameters involving that type to change
+> - moving from a 32-bit compilation to a 64-bit compilation may change the
+> underlying type of `size_t` and similar types, resulting in changes to
+> manglings
Clang allows use of a profile remapping file to specify that such differences
in mangled names should be ignored when matching the profile data against the
program.
+```{eval-rst}
.. option:: -fprofile-remapping-file=<file>
Specifies a file containing profile remapping information, that will be
used to match mangled names in the profile data to mangled names in the
program.
+```
The profile remapping file is a text file containing lines of the form
-.. code-block:: text
-
- fragmentkind fragment1 fragment2
+```text
+fragmentkind fragment1 fragment2
+```
-where ``fragmentkind`` is one of ``name``, ``type``, or ``encoding``,
+where `fragmentkind` is one of `name`, `type`, or `encoding`,
indicating whether the following mangled name fragments are
-<`name <https://itanium-cxx-abi.github.io/cxx-abi/abi.html#mangle.name>`_>s,
-<`type <https://itanium-cxx-abi.github.io/cxx-abi/abi.html#mangle.type>`_>s, or
-<`encoding <https://itanium-cxx-abi.github.io/cxx-abi/abi.html#mangle.encoding>`_>s,
+\<[name](https://itanium-cxx-abi.github.io/cxx-abi/abi.html#mangle.name)>s,
+\<[type](https://itanium-cxx-abi.github.io/cxx-abi/abi.html#mangle.type)>s, or
+\<[encoding](https://itanium-cxx-abi.github.io/cxx-abi/abi.html#mangle.encoding)>s,
respectively.
-Blank lines and lines starting with ``#`` are ignored.
+Blank lines and lines starting with `#` are ignored.
-For convenience, built-in <substitution>s such as ``St`` and ``Ss``
-are accepted as <name>s (even though they technically are not <name>s).
+For convenience, built-in \<substitution>s such as `St` and `Ss`
+are accepted as \<name>s (even though they technically are not \<name>s).
-For example, to specify that ``absl::string_view`` and ``std::string_view``
+For example, to specify that `absl::string_view` and `std::string_view`
should be treated as equivalent when matching profile data, the following
remapping file could be used:
-.. code-block:: text
+```text
+# absl::string_view is considered equivalent to std::string_view
+type N4absl11string_viewE St17basic_string_viewIcSt11char_traitsIcEE
- # absl::string_view is considered equivalent to std::string_view
- type N4absl11string_viewE St17basic_string_viewIcSt11char_traitsIcEE
-
- # std:: might be std::__1:: in libc++ or std::__cxx11:: in libstdc++
- name 3std St3__1
- name 3std St7__cxx11
+# std:: might be std::__1:: in libc++ or std::__cxx11:: in libstdc++
+name 3std St3__1
+name 3std St7__cxx11
+```
Matching profile data using a profile remapping file is supported on a
best-effort basis. For example, information regarding indirect call targets is
currently not remapped. For best results, you are encouraged to generate new
profile data matching the updated program, or to remap the profile data
-using the ``llvm-cxxmap`` and ``llvm-profdata merge`` tools.
-
-.. note::
+using the `llvm-cxxmap` and `llvm-profdata merge` tools.
- Profile data remapping is currently only supported for C++ mangled names
- following the Itanium C++ ABI mangling scheme. This covers all C++ targets
- supported by Clang other than Windows.
+:::{note}
+Profile data remapping is currently only supported for C++ mangled names
+following the Itanium C++ ABI mangling scheme. This covers all C++ targets
+supported by Clang other than Windows.
+:::
-GCOV-based Profiling
---------------------
+### GCOV-based Profiling
GCOV is a test coverage program, it helps to know how often a line of code
-is executed. When instrumenting the code with ``--coverage`` option, some
+is executed. When instrumenting the code with `--coverage` option, some
counters are added for each edge linking basic blocks.
At compile time, gcno files are generated containing information about
blocks and edges between them. At runtime the counters are incremented and at
exit the counters are dumped in gcda files.
-The tool ``llvm-cov gcov`` will parse gcno, gcda and source files to generate
-a report ``.c.gcov``.
+The tool `llvm-cov gcov` will parse gcno, gcda and source files to generate
+a report `.c.gcov`.
+```{eval-rst}
.. option:: -fprofile-filter-files=[regexes]
Define a list of regexes separated by a semi-colon.
@@ -3809,7 +4012,9 @@ a report ``.c.gcov``.
$ clang --coverage -fprofile-filter-files=".*\.c$" foo.c
For example, this will only instrument files finishing with ``.c``, skipping ``.h`` files.
+```
+```{eval-rst}
.. option:: -fprofile-exclude-files=[regexes]
Define a list of regexes separated by a semi-colon.
@@ -3820,33 +4025,35 @@ a report ``.c.gcov``.
$ clang --coverage -fprofile-exclude-files="^/usr/include/.*$" foo.c
For example, this will instrument all the files except the ones in ``/usr/include``.
+```
If both options are used then a file is instrumented if its name matches any
-of the regexes from ``-fprofile-filter-list`` and doesn't match all the regexes
-from ``-fprofile-exclude-list``.
+of the regexes from `-fprofile-filter-list` and doesn't match all the regexes
+from `-fprofile-exclude-list`.
-.. code-block:: console
+```console
+$ clang --coverage -fprofile-exclude-files="^/usr/include/.*$" \
+ -fprofile-filter-files="^/usr/.*$"
+```
- $ clang --coverage -fprofile-exclude-files="^/usr/include/.*$" \
- -fprofile-filter-files="^/usr/.*$"
-
-In that case ``/usr/foo/oof.h`` is instrumented since it matches the filter regex and
-doesn't match the exclude regex, but ``/usr/include/foo.h`` doesn't since it matches
+In that case `/usr/foo/oof.h` is instrumented since it matches the filter regex and
+doesn't match the exclude regex, but `/usr/include/foo.h` doesn't since it matches
the exclude regex.
-Controlling Debug Information
------------------------------
+### Controlling Debug Information
-Controlling Size of Debug Information
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+#### Controlling Size of Debug Information
Debug info kind generated by Clang can be set by one of the flags listed
below. If multiple flags are present, the last one is used.
+```{eval-rst}
.. option:: -g0
Don't generate any debug info (default).
+```
+```{eval-rst}
.. option:: -gline-tables-only
Generate line number tables only.
@@ -3855,7 +4062,9 @@ below. If multiple flags are present, the last one is used.
file names and line numbers (by such tools as ``gdb`` or ``addr2line``). It
doesn't contain any other data (e.g. description of local variables or
function parameters).
+```
+```{eval-rst}
.. option:: -fstandalone-debug
Clang supports a number of optimizations to reduce the size of debug
@@ -3877,17 +4086,23 @@ below. If multiple flags are present, the last one is used.
This is useful when working with 3rd-party libraries that don't come
with debug information. Note that Clang will never emit type
information for types that are not referenced at all by the program.
+```
+```{eval-rst}
.. option:: -fno-standalone-debug
On Darwin **-fstandalone-debug** is enabled by default. The
**-fno-standalone-debug** option can be used to get to turn on the
vtable-based optimization described above.
+```
+```{eval-rst}
.. option:: -g
Generate complete debug info.
+```
+```{eval-rst}
.. option:: -feliminate-unused-debug-types
By default, Clang does not emit type information for types that are defined
@@ -3896,66 +4111,73 @@ below. If multiple flags are present, the last one is used.
This can be particularly useful on Windows, when using NATVIS files that
can reference const symbols that would otherwise be stripped, even in full
debug or standalone debug modes.
+```
-Controlling Macro Debug Info Generation
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+#### Controlling Macro Debug Info Generation
Debug info for C preprocessor macros increases the size of debug information in
the binary. Macro debug info generated by Clang can be controlled by the flags
listed below.
+```{eval-rst}
.. option:: -fdebug-macro
Generate debug info for preprocessor macros. This flag is discarded when
**-g0** is enabled.
+```
+```{eval-rst}
.. option:: -fno-debug-macro
Do not generate debug info for preprocessor macros (default).
+```
-Controlling Debugger "Tuning"
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+#### Controlling Debugger "Tuning"
-While Clang generally emits standard DWARF debug info (http://dwarfstd.org),
+While Clang generally emits standard DWARF debug info (<http://dwarfstd.org>),
different debuggers may know how to take advantage of different specific DWARF
features. You can "tune" the debug info for one of several different debuggers.
+```{eval-rst}
.. option:: -ggdb, -glldb, -gsce, -gdbx
Tune the debug info for the ``gdb``, ``lldb``, Sony PlayStation\ |reg|
debugger, or ``dbx``, respectively. Each of these options implies **-g**.
(Therefore, if you want both **-gline-tables-only** and debugger tuning, the
tuning option must come first.)
+```
-Controlling LLVM IR Output
---------------------------
+### Controlling LLVM IR Output
-Controlling Value Names in LLVM IR
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+#### Controlling Value Names in LLVM IR
Emitting value names in LLVM IR increases the size and verbosity of the IR.
By default, value names are only emitted in assertion-enabled builds of Clang.
However, when reading IR it can be useful to re-enable the emission of value
names to improve readability.
+```{eval-rst}
.. option:: -fdiscard-value-names
Discard value names when generating LLVM IR.
+```
+```{eval-rst}
.. option:: -fno-discard-value-names
Do not discard value names when generating LLVM IR. This option can be used
to re-enable names for release builds of Clang.
+```
-Comment Parsing Options
------------------------
+### Comment Parsing Options
Clang parses Doxygen and non-Doxygen style documentation comments and attaches
-them to the appropriate declaration nodes. By default, it only parses
-Doxygen-style comments and ignores ordinary comments starting with ``//`` and
-``/*``.
+them to the appropriate declaration nodes. By default, it only parses
+Doxygen-style comments and ignores ordinary comments starting with `//` and
+`/*`.
+```{eval-rst}
.. option:: -Wdocumentation
Emit warnings about use of documentation comments. This warning group is off
@@ -3964,16 +4186,22 @@ Doxygen-style comments and ignores ordinary comments starting with ``//`` and
This includes checking that ``\param`` commands name parameters that actually
present in the function signature, checking that ``\returns`` is used only on
functions that actually return a value etc.
+```
+```{eval-rst}
.. option:: -Wno-documentation-unknown-command
Don't warn when encountering an unknown Doxygen command.
+```
+```{eval-rst}
.. option:: -fparse-all-comments
Parse all comments as documentation comments (including ordinary comments
starting with ``//`` and ``/*``).
+```
+```{eval-rst}
.. option:: -fcomment-block-commands=[commands]
Define custom documentation commands as block commands. This allows Clang to
@@ -3985,278 +4213,274 @@ Doxygen-style comments and ignores ordinary comments starting with ``//`` and
It is also possible to use ``-fcomment-block-commands`` several times; e.g.
``-fcomment-block-commands=foo -fcomment-block-commands=bar`` does the same
as above.
+```
+
+(ccc-override-options)=
-.. _ccc-override-options:
+### CCC_OVERRIDE_OPTIONS
-CCC_OVERRIDE_OPTIONS
---------------------
-The environment variable ``CCC_OVERRIDE_OPTIONS`` can be used to edit clang's
+The environment variable `CCC_OVERRIDE_OPTIONS` can be used to edit clang's
command line arguments. The value of this variable is a space-separated list of
edits to perform. The edits are applied in the order in which they appear in
-``CCC_OVERRIDE_OPTIONS``. Each edit should be one of the following forms:
+`CCC_OVERRIDE_OPTIONS`. Each edit should be one of the following forms:
-- ``#``: Silence information about the changes to the command line arguments.
-
-- ``^FOO``: Add ``FOO`` as a new argument at the beginning of the command line
+- `#`: Silence information about the changes to the command line arguments.
+- `^FOO`: Add `FOO` as a new argument at the beginning of the command line
right after the name of the compiler executable.
-
-- ``+FOO``: Add ``FOO`` as a new argument at the end of the command line.
-
-- ``s/XXX/YYY/``: Substitute the regular expression ``XXX`` with ``YYY`` in the
+- `+FOO`: Add `FOO` as a new argument at the end of the command line.
+- `s/XXX/YYY/`: Substitute the regular expression `XXX` with `YYY` in the
command line.
-
-- ``xOPTION``: Removes all instances of the literal argument ``OPTION``.
-
-- ``XOPTION``: Removes all instances of the literal argument ``OPTION``, and the
+- `xOPTION`: Removes all instances of the literal argument `OPTION`.
+- `XOPTION`: Removes all instances of the literal argument `OPTION`, and the
following argument.
-
-- ``Ox``: Removes all flags matching ``O`` or ``O[sz0-9]`` and adds ``Ox`` at
+- `Ox`: Removes all flags matching `O` or `O[sz0-9]` and adds `Ox` at
the end of the command line.
This environment variable does not affect the options added by the config files.
-.. _c:
+(c)=
-C Language Features
-===================
+## C Language Features
-The support for standard C in Clang is mostly feature-complete, see the `C
-status page <https://clang.llvm.org/c_status.html>`_ for more details.
+The support for standard C in Clang is mostly feature-complete, see the [C
+status page](https://clang.llvm.org/c_status.html) for more details.
-Extensions supported by clang
------------------------------
+### Extensions supported by clang
-See :doc:`LanguageExtensions`.
+See {doc}`LanguageExtensions`.
-Differences between various standard modes
-------------------------------------------
+### Differences between various standard modes
-clang supports the ``-std`` option, which changes what language mode clang uses.
+clang supports the `-std` option, which changes what language mode clang uses.
The supported modes for C are c89, gnu89, iso9899:199409 (for C95), c99, gnu99, c11, gnu11, c17,
-gnu17, c23, gnu23, c2y, gnu2y, and various aliases for those modes. If no ``-std``
+gnu17, c23, gnu23, c2y, gnu2y, and various aliases for those modes. If no `-std`
option is specified, clang defaults to gnu17 mode. Many C99 and C11 features
are supported in earlier modes as a conforming extension, with a warning. Use
-``-pedantic-errors`` to request an error if a feature from a later standard
+`-pedantic-errors` to request an error if a feature from a later standard
revision is used in an earlier mode.
-Differences between all ``c*`` and ``gnu*`` modes:
-
-- ``c*`` modes define "``__STRICT_ANSI__``".
-- Target-specific defines not prefixed by underscores, like ``linux``,
- are defined in ``gnu*`` modes.
-- Trigraphs default to being off in ``gnu*`` modes; they can be enabled
- by the ``-trigraphs`` option.
-- The parser recognizes ``asm`` and ``typeof`` as keywords in ``gnu*`` modes;
- the variants ``__asm__`` and ``__typeof__`` are recognized in all modes.
-- The parser recognizes ``inline`` as a keyword in ``gnu*`` mode, in
- addition to recognizing it in the ``*99`` and later modes for which it is
- part of the ISO C standard. The variant ``__inline__`` is recognized in all
- modes.
-- The Apple "blocks" extension is recognized by default in ``gnu*`` modes
- on some platforms; it can be enabled in any mode with the ``-fblocks``
- option.
+Differences between all `c*` and `gnu*` modes:
-Differences between ``*89`` and ``*94`` modes:
+- `c*` modes define "`__STRICT_ANSI__`".
+- Target-specific defines not prefixed by underscores, like `linux`,
+ are defined in `gnu*` modes.
+- Trigraphs default to being off in `gnu*` modes; they can be enabled
+ by the `-trigraphs` option.
+- The parser recognizes `asm` and `typeof` as keywords in `gnu*` modes;
+ the variants `__asm__` and `__typeof__` are recognized in all modes.
+- The parser recognizes `inline` as a keyword in `gnu*` mode, in
+ addition to recognizing it in the `*99` and later modes for which it is
+ part of the ISO C standard. The variant `__inline__` is recognized in all
+ modes.
+- The Apple "blocks" extension is recognized by default in `gnu*` modes
+ on some platforms; it can be enabled in any mode with the `-fblocks`
+ option.
-- Digraphs are not recognized in c89 mode.
+Differences between `*89` and `*94` modes:
-Differences between ``*94`` and ``*99`` modes:
+- Digraphs are not recognized in c89 mode.
-- The ``*99`` modes default to implementing ``inline`` / ``__inline__``
- as specified in C99, while the ``*89`` modes implement the GNU version.
- This can be overridden for individual functions with the ``__gnu_inline__``
- attribute.
-- The scope of names defined inside a ``for``, ``if``, ``switch``, ``while``,
- or ``do`` statement is different. (example: ``if ((struct x {int x;}*)0) {}``.)
-- ``__STDC_VERSION__`` is not defined in ``*89`` modes.
-- ``inline`` is not recognized as a keyword in ``c89`` mode.
-- ``restrict`` is not recognized as a keyword in ``*89`` modes.
-- Commas are allowed in integer constant expressions in ``*99`` modes.
-- Arrays which are not lvalues are not implicitly promoted to pointers
- in ``*89`` modes.
-- Some warnings are different.
+Differences between `*94` and `*99` modes:
-Differences between ``*99`` and ``*11`` modes:
+- The `*99` modes default to implementing `inline` / `__inline__`
+ as specified in C99, while the `*89` modes implement the GNU version.
+ This can be overridden for individual functions with the `__gnu_inline__`
+ attribute.
+- The scope of names defined inside a `for`, `if`, `switch`, `while`,
+ or `do` statement is different. (example: `if ((struct x {int x;}*)0) {}`.)
+- `__STDC_VERSION__` is not defined in `*89` modes.
+- `inline` is not recognized as a keyword in `c89` mode.
+- `restrict` is not recognized as a keyword in `*89` modes.
+- Commas are allowed in integer constant expressions in `*99` modes.
+- Arrays which are not lvalues are not implicitly promoted to pointers
+ in `*89` modes.
+- Some warnings are different.
-- Warnings for use of C11 features are disabled.
-- ``__STDC_VERSION__`` is defined to ``201112L`` rather than ``199901L``.
+Differences between `*99` and `*11` modes:
-Differences between ``*11`` and ``*17`` modes:
+- Warnings for use of C11 features are disabled.
+- `__STDC_VERSION__` is defined to `201112L` rather than `199901L`.
-- ``__STDC_VERSION__`` is defined to ``201710L`` rather than ``201112L``.
+Differences between `*11` and `*17` modes:
-Differences between ``*17`` and ``*23`` modes:
+- `__STDC_VERSION__` is defined to `201710L` rather than `201112L`.
-- ``__STDC_VERSION__`` is defined to ``202311L`` rather than ``201710L``.
-- ``nullptr`` and ``nullptr_t`` are supported, only in ``*23`` mode.
-- ``ATOMIC_VAR_INIT`` is removed from ``*23`` mode.
-- ``bool``, ``true``, ``false``, ``alignas``, ``alignof``, ``static_assert``,
- and ``thread_local`` are now first-class keywords, only in ``*23`` mode.
-- ``typeof`` and ``typeof_unqual`` are supported, only ``*23`` mode.
-- Bit-precise integers (``_BitInt(N)``) are supported by default in ``*23``
- mode, and as an extension in ``*17`` and earlier modes.
-- ``[[]]`` attributes are supported by default in ``*23`` mode, and as an
- extension in ``*17`` and earlier modes.
+Differences between `*17` and `*23` modes:
-Differences between ``*23`` and ``*2y`` modes:
+- `__STDC_VERSION__` is defined to `202311L` rather than `201710L`.
+- `nullptr` and `nullptr_t` are supported, only in `*23` mode.
+- `ATOMIC_VAR_INIT` is removed from `*23` mode.
+- `bool`, `true`, `false`, `alignas`, `alignof`, `static_assert`,
+ and `thread_local` are now first-class keywords, only in `*23` mode.
+- `typeof` and `typeof_unqual` are supported, only `*23` mode.
+- Bit-precise integers (`_BitInt(N)`) are supported by default in `*23`
+ mode, and as an extension in `*17` and earlier modes.
+- `[[]]` attributes are supported by default in `*23` mode, and as an
+ extension in `*17` and earlier modes.
-- ``__STDC_VERSION__`` is defined to ``202400L`` rather than ``202311L``.
+Differences between `*23` and `*2y` modes:
-GCC extensions not implemented yet
-----------------------------------
+- `__STDC_VERSION__` is defined to `202400L` rather than `202311L`.
+
+### GCC extensions not implemented yet
clang tries to be compatible with gcc as much as possible, but some gcc
extensions are not implemented:
-- clang does not support decimal floating point types (``_Decimal32`` and
- friends) yet.
-- clang only supports global register variables when the register specified
- is non-allocatable (e.g. the stack pointer). Support for general global
- register variables is unlikely to be implemented soon because it requires
- additional LLVM backend support.
-- clang does not support static initialization of flexible array
- members. This appears to be a rarely used extension, but could be
- implemented pending user demand.
-- clang does not support
- ``__builtin_va_arg_pack``/``__builtin_va_arg_pack_len``. This is
- used rarely, but in some potentially interesting places, like the
- glibc headers, so it may be implemented pending user demand. Note
- that because clang pretends to be like GCC 4.2, and this extension
- was introduced in 4.3, the glibc headers will not try to use this
- extension with clang at the moment.
+- clang does not support decimal floating point types (`_Decimal32` and
+ friends) yet.
+- clang only supports global register variables when the register specified
+ is non-allocatable (e.g. the stack pointer). Support for general global
+ register variables is unlikely to be implemented soon because it requires
+ additional LLVM backend support.
+- clang does not support static initialization of flexible array
+ members. This appears to be a rarely used extension, but could be
+ implemented pending user demand.
+- clang does not support
+ `__builtin_va_arg_pack`/`__builtin_va_arg_pack_len`. This is
+ used rarely, but in some potentially interesting places, like the
+ glibc headers, so it may be implemented pending user demand. Note
+ that because clang pretends to be like GCC 4.2, and this extension
+ was introduced in 4.3, the glibc headers will not try to use this
+ extension with clang at the moment.
This is not a complete list; if you find an unsupported extension
-missing from this list, please file a `feature request <https://github.com/llvm/llvm-project/issues/>`_.
-This list currently excludes C++; see :ref:`C++ Language Features <cxx>`. Also,
+missing from this list, please file a [feature request](https://github.com/llvm/llvm-project/issues/).
+This list currently excludes C++; see {ref}`C++ Language Features <cxx>`. Also,
this list does not include bugs in mostly-implemented features; please see the
-`issues list <https://github.com/llvm/llvm-project/issues/>`_ for known existing
+[issues list](https://github.com/llvm/llvm-project/issues/) for known existing
bugs.
-Intentionally unsupported GCC extensions
-----------------------------------------
-
-- clang does not support the gcc extension that allows variable-length
- arrays in structures. This is for a few reasons: one, it is tricky to
- implement, two, the extension is completely undocumented, and three,
- the extension appears to be rarely used. Note that clang *does*
- support flexible array members (arrays with a zero or unspecified
- size at the end of a structure).
-- GCC accepts many expression forms that are not valid integer constant
- expressions in bit-field widths, enumerator constants, case labels,
- and in array bounds at global scope. Clang also accepts additional
- expression forms in these contexts, but constructs that GCC accepts due to
- simplifications GCC performs while parsing, such as ``x - x`` (where ``x`` is a
- variable) will likely never be accepted by Clang.
-- clang does not support ``__builtin_apply`` and friends; this extension
- is extremely obscure and difficult to implement reliably.
-- clang does not support the gcc extension for forward-declaring
- function parameters.
-- clang does not support nested functions; this is a complex feature which is
- infrequently used, so it is unlikely to be implemented. In C++11 it can be
- emulated by assigning lambda functions to local variables, e.g:
-
- .. code-block:: cpp
-
- auto const local_function = [&](int parameter) {
- // Do something
- };
- ...
- local_function(1);
-
-
-.. _c_ms:
-
-Microsoft extensions
---------------------
+### Intentionally unsupported GCC extensions
+
+- clang does not support the gcc extension that allows variable-length
+ arrays in structures. This is for a few reasons: one, it is tricky to
+ implement, two, the extension is completely undocumented, and three,
+ the extension appears to be rarely used. Note that clang *does*
+ support flexible array members (arrays with a zero or unspecified
+ size at the end of a structure).
+
+- GCC accepts many expression forms that are not valid integer constant
+ expressions in bit-field widths, enumerator constants, case labels,
+ and in array bounds at global scope. Clang also accepts additional
+ expression forms in these contexts, but constructs that GCC accepts due to
+ simplifications GCC performs while parsing, such as `x - x` (where `x` is a
+ variable) will likely never be accepted by Clang.
+
+- clang does not support `__builtin_apply` and friends; this extension
+ is extremely obscure and difficult to implement reliably.
+
+- clang does not support the gcc extension for forward-declaring
+ function parameters.
+
+- clang does not support nested functions; this is a complex feature which is
+ infrequently used, so it is unlikely to be implemented. In C++11 it can be
+ emulated by assigning lambda functions to local variables, e.g:
+
+ ```cpp
+ auto const local_function = [&](int parameter) {
+ // Do something
+ };
+ ...
+ local_function(1);
+ ```
+
+(c-ms)=
+
+### Microsoft extensions
clang has support for many extensions from Microsoft Visual C++. To enable these
-extensions, use the ``-fms-extensions`` command-line option. This is the default
+extensions, use the `-fms-extensions` command-line option. This is the default
for Windows targets. Clang does not implement every pragma or declspec provided
-by MSVC, but the popular ones, such as ``__declspec(dllexport)`` and ``#pragma
-comment(lib)`` are well supported.
+by MSVC, but the popular ones, such as `__declspec(dllexport)` and `#pragma
+comment(lib)` are well supported.
-clang has a ``-fms-compatibility`` flag that makes clang accept enough
+clang has a `-fms-compatibility` flag that makes clang accept enough
invalid C++ to be able to parse most Microsoft headers. For example, it
-allows `unqualified lookup of dependent base class members
-<https://clang.llvm.org/compatibility.html#dep_lookup_bases>`_, which is
+allows [unqualified lookup of dependent base class members](https://clang.llvm.org/compatibility.html#dep_lookup_bases), which is
a common compatibility issue with clang. This flag is enabled by default
for Windows targets.
-``-fdelayed-template-parsing`` lets clang delay parsing of function template
+`-fdelayed-template-parsing` lets clang delay parsing of function template
definitions until the end of a translation unit. This flag is enabled by
default for Windows targets.
For compatibility with existing code that compiles with MSVC, clang defines the
-``_MSC_VER`` and ``_MSC_FULL_VER`` macros. When on Windows, these default to
-either the same value as the currently installed version of cl.exe, or ``1933``
-and ``193300000`` (respectively). The ``-fms-compatibility-version=`` flag
-overrides these values. It accepts a dotted version tuple, such as 19.00.23506.
+`_MSC_VER` and `_MSC_FULL_VER` macros. When on Windows, these default to
+either the same value as the currently installed version of cl.exe, or `1933`
+and `193300000` (respectively). The `-fms-compatibility-version=` flag
+overrides these values. It accepts a dotted version tuple, such as 19.00.23506.
Changing the MSVC compatibility version makes clang behave more like that
-version of MSVC. For example, ``-fms-compatibility-version=19`` will enable
-C++14 features and define ``char16_t`` and ``char32_t`` as builtin types.
+version of MSVC. For example, `-fms-compatibility-version=19` will enable
+C++14 features and define `char16_t` and `char32_t` as builtin types.
-For compatibility with existing MSVC behavior, ``-fms-compatibility`` also
-implicitly enables several other options, including ``-fno-strict-aliasing``,
-``-fwrapv`` and ``-fdelayed-template-parsing``. When MSVC compatibility is
-set to a version earlier than 19, it also enables ``-fno-threadsafe-statics``.
+For compatibility with existing MSVC behavior, `-fms-compatibility` also
+implicitly enables several other options, including `-fno-strict-aliasing`,
+`-fwrapv` and `-fdelayed-template-parsing`. When MSVC compatibility is
+set to a version earlier than 19, it also enables `-fno-threadsafe-statics`.
-.. _cxx:
+(cxx)=
-C++ Language Features
-=====================
+## C++ Language Features
clang fully implements all of standard C++98 except for exported
templates (which were removed in C++11), all of standard C++11,
C++14, and C++17, and most of C++20 and C++23.
-See the `C++ support in Clang <https://clang.llvm.org/cxx_status.html>`_ page
+See the [C++ support in Clang](https://clang.llvm.org/cxx_status.html) page
for detailed information on C++ feature support across Clang versions.
-Controlling implementation limits
----------------------------------
+### Controlling implementation limits
+```{eval-rst}
.. option:: -fbracket-depth=N
Sets the limit for nested parentheses, brackets, and braces to N. The
default is 256.
+```
+```{eval-rst}
.. option:: -fconstexpr-depth=N
Sets the limit for constexpr function invocations to N. The default is 512.
+```
+```{eval-rst}
.. option:: -fconstexpr-steps=N
Sets the limit for the number of full-expressions evaluated in a single
constant expression evaluation. This also controls the maximum size
of array and dynamic array allocation that can be constant evaluated.
The default is 1048576, and the limit can be disabled with `-fconstexpr-steps=0`.
+```
+```{eval-rst}
.. option:: -ftemplate-depth=N
Sets the limit for recursively nested template instantiations to N. The
default is 1024.
+```
+```{eval-rst}
.. option:: -foperator-arrow-depth=N
Sets the limit for iterative calls to 'operator->' functions to N. The
default is 256.
+```
-.. _objc:
+(objc)=
-Objective-C Language Features
-=============================
+## Objective-C Language Features
-.. _objcxx:
+(objcxx)=
-Objective-C++ Language Features
-===============================
+## Objective-C++ Language Features
-.. _openmp:
+(openmp)=
-OpenMP Features
-===============
+## OpenMP Features
-Clang supports all OpenMP 4.5 directives and clauses. See :doc:`OpenMPSupport`
+Clang supports all OpenMP 4.5 directives and clauses. See {doc}`OpenMPSupport`
for additional details.
Use `-fopenmp` to enable OpenMP. Support for OpenMP can be disabled with
@@ -4264,12 +4488,12 @@ Use `-fopenmp` to enable OpenMP. Support for OpenMP can be disabled with
Use `-fopenmp-simd` to enable OpenMP simd features only, without linking
the runtime library; for combined constructs
-(e.g. ``#pragma omp parallel for simd``) the non-simd directives and clauses
+(e.g. `#pragma omp parallel for simd`) the non-simd directives and clauses
will be ignored. This can be disabled with `-fno-openmp-simd`.
-Controlling implementation limits
----------------------------------
+### Controlling implementation limits
+```{eval-rst}
.. option:: -fopenmp-use-tls
Controls code generation for OpenMP threadprivate variables. In presence of
@@ -4277,83 +4501,78 @@ Controlling implementation limits
local variables, using TLS support. If `-fno-openmp-use-tls`
is provided or target does not support TLS, code generation for threadprivate
variables relies on OpenMP runtime library.
+```
-.. _opencl:
+(opencl)=
-OpenCL Features
-===============
+## OpenCL Features
Clang can be used to compile OpenCL kernels for execution on a device
(e.g. GPU). It is possible to compile the kernel into a binary (e.g. for AMDGPU)
that can be uploaded to run directly on a device (e.g. using
-`clCreateProgramWithBinary
-<https://www.khronos.org/registry/OpenCL/specs/opencl-1.1.pdf#111>`_) or
+[clCreateProgramWithBinary](https://www.khronos.org/registry/OpenCL/specs/opencl-1.1.pdf#111)) or
into generic bitcode files loadable into other toolchains.
Compiling to a binary using the default target from the installation can be done
as follows:
- .. code-block:: console
-
- $ echo "kernel void k(){}" > test.cl
- $ clang test.cl
+> ```console
+> $ echo "kernel void k(){}" > test.cl
+> $ clang test.cl
+> ```
Compiling for a specific target can be done by specifying the triple corresponding
to the target, for example:
- .. code-block:: console
-
- $ clang --target=nvptx64-unknown-unknown test.cl
- $ clang --target=amdgcn-amd-amdhsa -mcpu=gfx900 test.cl
+> ```console
+> $ clang --target=nvptx64-unknown-unknown test.cl
+> $ clang --target=amdgcn-amd-amdhsa -mcpu=gfx900 test.cl
+> ```
Compiling to bitcode can be done as follows:
- .. code-block:: console
-
- $ clang -c -emit-llvm test.cl
+> ```console
+> $ clang -c -emit-llvm test.cl
+> ```
This will produce a file `test.bc` that can be used in vendor toolchains
to perform machine code generation.
Note that if compiled to bitcode for generic targets such as SPIR/SPIR-V,
portable IR is produced that can be used with various vendor
-tools as well as open source tools such as `SPIRV-LLVM Translator
-<https://github.com/KhronosGroup/SPIRV-LLVM-Translator>`_
-to produce SPIR-V binary. More details are provided in `the offline
+tools as well as open source tools such as [SPIRV-LLVM Translator](https://github.com/KhronosGroup/SPIRV-LLVM-Translator)
+to produce SPIR-V binary. More details are provided in [the offline
compilation from OpenCL kernel sources into SPIR-V using open source
-tools
-<https://github.com/KhronosGroup/OpenCL-Guide/blob/main/chapters/os_tooling.md>`_.
+tools](https://github.com/KhronosGroup/OpenCL-Guide/blob/main/chapters/os_tooling.md).
From clang 14 onwards SPIR-V can be generated directly as detailed in
-:ref:`the SPIR-V support section <spir-v>`.
+{ref}`the SPIR-V support section <spir-v>`.
Clang currently supports OpenCL C language standards up to v2.0. Clang mainly
supports full profile. There is only very limited support of the embedded
profile.
From clang 9 a C++ mode is available for OpenCL (see
-:ref:`C++ for OpenCL <cxx_for_opencl>`).
+{ref}`C++ for OpenCL <cxx_for_opencl>`).
OpenCL v3.0 support is complete but it remains in experimental state, see more
-details about the experimental features and limitations in :doc:`OpenCLSupport`
+details about the experimental features and limitations in {doc}`OpenCLSupport`
page.
-OpenCL Specific Options
------------------------
+### OpenCL Specific Options
-Most of the OpenCL build options from `the specification v2.0 section 5.8.4
-<https://www.khronos.org/registry/cl/specs/opencl-2.0.pdf#200>`_ are available.
+Most of the OpenCL build options from [the specification v2.0 section 5.8.4](https://www.khronos.org/registry/cl/specs/opencl-2.0.pdf#200) are available.
Examples:
- .. code-block:: console
-
- $ clang -cl-std=CL2.0 -cl-single-precision-constant test.cl
-
+> ```console
+> $ clang -cl-std=CL2.0 -cl-single-precision-constant test.cl
+> ```
Many flags used for the compilation for C sources can also be passed while
-compiling for OpenCL, examples: ``-c``, ``-O<1-4|s>``, ``-o``, ``-emit-llvm``, etc.
+compiling for OpenCL, examples: `-c`, `-O<1-4|s>`, `-o`, `-emit-llvm`, etc.
Some extra options are available to support special OpenCL features.
+```{eval-rst}
.. option:: -cl-no-stdinc
Allows to disable all extra types and functions that are not native to the compiler.
@@ -4370,9 +4589,11 @@ Some extra options are available to support special OpenCL features.
More information about the standard types and functions is provided in :ref:`the
section on the OpenCL Header <opencl_header>`.
+```
-.. _opencl_cl_ext:
+(opencl-cl-ext)=
+```{eval-rst}
.. option:: -cl-ext
Enables/Disables support of OpenCL extensions and optional features. All OpenCL
@@ -4398,53 +4619,50 @@ Some extra options are available to support special OpenCL features.
Note that some generic targets e.g. SPIR/SPIR-V enable all extensions/features in
clang by default.
+```
-OpenCL Targets
---------------
+### OpenCL Targets
OpenCL targets are derived from the regular Clang target classes. The OpenCL
specific parts of the target representation provide address space mapping as
well as a set of supported extensions.
-Specific Targets
-^^^^^^^^^^^^^^^^
+#### Specific Targets
There is a set of concrete HW architectures that OpenCL can be compiled for.
- For AMD target:
- .. code-block:: console
-
- $ clang --target=amdgcn-amd-amdhsa -mcpu=gfx900 test.cl
+ > ```console
+ > $ clang --target=amdgcn-amd-amdhsa -mcpu=gfx900 test.cl
+ > ```
- For Nvidia architectures:
- .. code-block:: console
-
- $ clang --target=nvptx64-unknown-unknown test.cl
-
+ > ```console
+ > $ clang --target=nvptx64-unknown-unknown test.cl
+ > ```
-Generic Targets
-^^^^^^^^^^^^^^^
+#### Generic Targets
- A SPIR-V binary can be produced for 32- or 64-bit targets.
- .. code-block:: console
-
- $ clang --target=spirv32 -c test.cl
- $ clang --target=spirv64 -c test.cl
+ > ```console
+ > $ clang --target=spirv32 -c test.cl
+ > $ clang --target=spirv64 -c test.cl
+ > ```
- More details can be found in :ref:`the SPIR-V support section <spir-v>`.
+ More details can be found in {ref}`the SPIR-V support section <spir-v>`.
- SPIR is available as a generic target to allow portable bitcode to be produced
- that can be used across GPU toolchains. The implementation follows `the SPIR
- specification <https://www.khronos.org/spir>`_. There are two flavors
+ that can be used across GPU toolchains. The implementation follows [the SPIR
+ specification](https://www.khronos.org/spir). There are two flavors
available for 32 and 64 bits.
- .. code-block:: console
-
- $ clang --target=spir test.cl -emit-llvm -c
- $ clang --target=spir64 test.cl -emit-llvm -c
+ > ```console
+ > $ clang --target=spir test.cl -emit-llvm -c
+ > $ clang --target=spir64 test.cl -emit-llvm -c
+ > ```
Clang will generate SPIR v1.2 compatible IR for OpenCL versions up to 2.0 and
SPIR v2.0 for OpenCL v2.0 or C++ for OpenCL.
@@ -4455,255 +4673,234 @@ Generic Targets
work-items on the fly using hardware, which covers practically all non-GPU
devices such as CPUs and DSPs, additional processing is needed for the kernels
to support multiple work-item execution. For this, a 3rd party toolchain,
- such as for example `POCL <http://portablecl.org/>`_, can be used.
+ such as for example [POCL](http://portablecl.org/), can be used.
This target does not support multiple memory segments and, therefore, the fake
- address space map can be added using the :ref:`-ffake-address-space-map
+ address space map can be added using the {ref}`-ffake-address-space-map
<opencl_fake_address_space_map>` flag.
All known OpenCL extensions and features are set to supported in the generic targets,
- however :option:`-cl-ext` flag can be used to toggle individual extensions and
+ however {option}`-cl-ext` flag can be used to toggle individual extensions and
features.
-.. _opencl_header:
+(opencl-header)=
-OpenCL Header
--------------
+### OpenCL Header
By default Clang will include standard headers and therefore most of OpenCL
builtin functions and types are available during compilation. The
default declarations of non-native compiler types and functions can be disabled
-by using flag :option:`-cl-no-stdinc`.
+by using flag {option}`-cl-no-stdinc`.
The following example demonstrates that OpenCL kernel sources with various
standard builtin functions can be compiled without the need for an explicit
includes or compiler flags.
- .. code-block:: console
-
- $ echo "bool is_wg_uniform(int i){return get_enqueued_local_size(i)==get_local_size(i);}" > test.cl
- $ clang -cl-std=CL2.0 test.cl
+> ```console
+> $ echo "bool is_wg_uniform(int i){return get_enqueued_local_size(i)==get_local_size(i);}" > test.cl
+> $ clang -cl-std=CL2.0 test.cl
+> ```
-More information about the default headers is provided in :doc:`OpenCLSupport`.
+More information about the default headers is provided in {doc}`OpenCLSupport`.
-OpenCL Extensions
------------------
+### OpenCL Extensions
-Most of the ``cl_khr_*`` extensions to OpenCL C from `the official OpenCL
-registry <https://www.khronos.org/registry/OpenCL/>`_ are available and
+Most of the `cl_khr_*` extensions to OpenCL C from [the official OpenCL
+registry](https://www.khronos.org/registry/OpenCL/) are available and
configured per target depending on the support available in the specific
architecture.
It is possible to alter the default extensions setting per target using
-``-cl-ext`` flag. (See :ref:`flags description <opencl_cl_ext>` for more details).
+`-cl-ext` flag. (See {ref}`flags description <opencl_cl_ext>` for more details).
Vendor extensions can be added flexibly by declaring the list of types and
functions associated with each extensions enclosed within the following
compiler pragma directives:
- .. code-block:: c
-
- #pragma OPENCL EXTENSION the_new_extension_name : begin
- // declare types and functions associated with the extension here
- #pragma OPENCL EXTENSION the_new_extension_name : end
-
-For example, parsing the following code adds ``my_t`` type and ``my_func``
-function to the custom ``my_ext`` extension.
+> ```c
+> #pragma OPENCL EXTENSION the_new_extension_name : begin
+> // declare types and functions associated with the extension here
+> #pragma OPENCL EXTENSION the_new_extension_name : end
+> ```
- .. code-block:: c
+For example, parsing the following code adds `my_t` type and `my_func`
+function to the custom `my_ext` extension.
- #pragma OPENCL EXTENSION my_ext : begin
- typedef struct{
- int a;
- }my_t;
- void my_func(my_t);
- #pragma OPENCL EXTENSION my_ext : end
+> ```c
+> #pragma OPENCL EXTENSION my_ext : begin
+> typedef struct{
+> int a;
+> }my_t;
+> void my_func(my_t);
+> #pragma OPENCL EXTENSION my_ext : end
+> ```
There is no conflict resolution for identifier clashes among extensions.
It is therefore recommended that the identifiers are prefixed with a
double underscore to avoid clashing with user space identifiers. Vendor
extension should use reserved identifier prefix e.g. amd, arm, intel.
-Clang also supports language extensions documented in `The OpenCL C Language
-Extensions Documentation
-<https://github.com/KhronosGroup/Khronosdotorg/blob/main/api/opencl/assets/OpenCL_LangExt.pdf>`_.
+Clang also supports language extensions documented in [The OpenCL C Language
+Extensions Documentation](https://github.com/KhronosGroup/Khronosdotorg/blob/main/api/opencl/assets/OpenCL_LangExt.pdf).
-OpenCL-Specific Attributes
---------------------------
+### OpenCL-Specific Attributes
OpenCL support in Clang contains a set of attribute taken directly from the
specification as well as additional attributes.
-See also :doc:`AttributeReference`.
+See also {doc}`AttributeReference`.
-nosvm
-^^^^^
+#### nosvm
Clang supports this attribute to comply to OpenCL v2.0 conformance, but it
does not have any effect on the IR. For more details refer to the specification
-`section 6.7.2
-<https://www.khronos.org/registry/cl/specs/opencl-2.0-openclc.pdf#49>`_
+[section 6.7.2](https://www.khronos.org/registry/cl/specs/opencl-2.0-openclc.pdf#49)
-
-opencl_unroll_hint
-^^^^^^^^^^^^^^^^^^
+#### opencl_unroll_hint
The implementation of this feature mirrors the unroll hint for C.
More details on the syntax can be found in the specification
-`section 6.11.5
-<https://www.khronos.org/registry/cl/specs/opencl-2.0-openclc.pdf#61>`_
+[section 6.11.5](https://www.khronos.org/registry/cl/specs/opencl-2.0-openclc.pdf#61)
-convergent
-^^^^^^^^^^
+#### convergent
To make sure no invalid optimizations occur for single program multiple data
(SPMD) / single instruction multiple thread (SIMT) Clang provides attributes that
can be used for special functions that have cross work item semantics.
-An example is the subgroup operations such as `intel_sub_group_shuffle
-<https://www.khronos.org/registry/cl/extensions/intel/cl_intel_subgroups.txt>`_
-
- .. code-block:: c
-
- // Define custom my_sub_group_shuffle(data, c)
- // that makes use of intel_sub_group_shuffle
- r1 = ...
- if (r0) r1 = computeA();
- // Shuffle data from r1 into r3
- // of threads id r2.
- r3 = my_sub_group_shuffle(r1, r2);
- if (r0) r3 = computeB();
+An example is the subgroup operations such as [intel_sub_group_shuffle](https://www.khronos.org/registry/cl/extensions/intel/cl_intel_subgroups.txt)
+
+> ```c
+> // Define custom my_sub_group_shuffle(data, c)
+> // that makes use of intel_sub_group_shuffle
+> r1 = ...
+> if (r0) r1 = computeA();
+> // Shuffle data from r1 into r3
+> // of threads id r2.
+> r3 = my_sub_group_shuffle(r1, r2);
+> if (r0) r3 = computeB();
+> ```
with non-SPMD semantics this is optimized to the following equivalent code:
- .. code-block:: c
-
- r1 = ...
- if (!r0)
- // Incorrect functionality! The data in r1
- // have not been computed by all threads yet.
- r3 = my_sub_group_shuffle(r1, r2);
- else {
- r1 = computeA();
- r3 = my_sub_group_shuffle(r1, r2);
- r3 = computeB();
- }
-
-Declaring the function ``my_sub_group_shuffle`` with the convergent attribute
+> ```c
+> r1 = ...
+> if (!r0)
+> // Incorrect functionality! The data in r1
+> // have not been computed by all threads yet.
+> r3 = my_sub_group_shuffle(r1, r2);
+> else {
+> r1 = computeA();
+> r3 = my_sub_group_shuffle(r1, r2);
+> r3 = computeB();
+> }
+> ```
+
+Declaring the function `my_sub_group_shuffle` with the convergent attribute
would prevent this:
- .. code-block:: c
+> ```c
+> my_sub_group_shuffle() __attribute__((convergent));
+> ```
- my_sub_group_shuffle() __attribute__((convergent));
+Using `convergent` guarantees correct execution by keeping CFG equivalence
+wrt operations marked as `convergent`. CFG `G´` is equivalent to `G` wrt
+node `Ni` : `iff ∀ Nj (i≠j)` domination and post-domination relations with
+respect to `Ni` remain the same in both `G` and `G´`.
-Using ``convergent`` guarantees correct execution by keeping CFG equivalence
-wrt operations marked as ``convergent``. CFG ``G´`` is equivalent to ``G`` wrt
-node ``Ni`` : ``iff ∀ Nj (i≠j)`` domination and post-domination relations with
-respect to ``Ni`` remain the same in both ``G`` and ``G´``.
+#### noduplicate
-noduplicate
-^^^^^^^^^^^
-
-``noduplicate`` is more restrictive with respect to optimizations than
-``convergent`` because a convergent function only preserves CFG equivalence.
+`noduplicate` is more restrictive with respect to optimizations than
+`convergent` because a convergent function only preserves CFG equivalence.
This allows some optimizations to happen as long as the control flow remains
unmodified.
- .. code-block:: c
-
- for (int i=0; i<4; i++)
- my_sub_group_shuffle()
+> ```c
+> for (int i=0; i<4; i++)
+> my_sub_group_shuffle()
+> ```
can be modified to:
- .. code-block:: c
+> ```c
+> my_sub_group_shuffle();
+> my_sub_group_shuffle();
+> my_sub_group_shuffle();
+> my_sub_group_shuffle();
+> ```
- my_sub_group_shuffle();
- my_sub_group_shuffle();
- my_sub_group_shuffle();
- my_sub_group_shuffle();
-
-while using ``noduplicate`` would disallow this. Also ``noduplicate`` doesn't
-have the same safe semantics of CFG as ``convergent`` and can cause changes in
+while using `noduplicate` would disallow this. Also `noduplicate` doesn't
+have the same safe semantics of CFG as `convergent` and can cause changes in
CFG that modify semantics of the original program.
-``noduplicate`` is kept for backwards compatibility only and it considered to be
+`noduplicate` is kept for backwards compatibility only and it considered to be
deprecated for future uses.
-.. _cxx_for_opencl:
+(cxx-for-opencl)=
-C++ for OpenCL
---------------
+### C++ for OpenCL
Starting from clang 9 kernel code can contain C++17 features: classes, templates,
function overloading, type deduction, etc. Please note that this is not an
-implementation of `OpenCL C++
-<https://www.khronos.org/registry/OpenCL/specs/2.2/pdf/OpenCL_Cxx.pdf>`_ and
+implementation of [OpenCL C++](https://www.khronos.org/registry/OpenCL/specs/2.2/pdf/OpenCL_Cxx.pdf) and
there is no plan to support it in clang in any new releases in the near future.
Clang currently supports C++ for OpenCL 1.0 and 2021.
For detailed information about this language refer to the C++ for OpenCL
Programming Language Documentation available
-in `the latest build
-<https://www.khronos.org/opencl/assets/CXX_for_OpenCL.html>`_
-or in `the official release
-<https://github.com/KhronosGroup/OpenCL-Docs/releases/tag/cxxforopencl-docrev2021.12>`_.
+in [the latest build](https://www.khronos.org/opencl/assets/CXX_for_OpenCL.html)
+or in [the official release](https://github.com/KhronosGroup/OpenCL-Docs/releases/tag/cxxforopencl-docrev2021.12).
To enable the C++ for OpenCL mode, pass one of following command line options when
-compiling ``.clcpp`` file:
-
-- C++ for OpenCL 1.0: ``-cl-std=clc++``, ``-cl-std=CLC++``, ``-cl-std=clc++1.0``,
- ``-cl-std=CLC++1.0``, ``-std=clc++``, ``-std=CLC++``, ``-std=clc++1.0`` or
- ``-std=CLC++1.0``.
+compiling `.clcpp` file:
-- C++ for OpenCL 2021: ``-cl-std=clc++2021``, ``-cl-std=CLC++2021``,
- ``-std=clc++2021``, ``-std=CLC++2021``.
+- C++ for OpenCL 1.0: `-cl-std=clc++`, `-cl-std=CLC++`, `-cl-std=clc++1.0`,
+ `-cl-std=CLC++1.0`, `-std=clc++`, `-std=CLC++`, `-std=clc++1.0` or
+ `-std=CLC++1.0`.
+- C++ for OpenCL 2021: `-cl-std=clc++2021`, `-cl-std=CLC++2021`,
+ `-std=clc++2021`, `-std=CLC++2021`.
Example of use:
- .. code-block:: c++
-
- template<class T> T add( T x, T y )
- {
- return x + y;
- }
-
- __kernel void test( __global float* a, __global float* b)
- {
- auto index = get_global_id(0);
- a[index] = add(b[index], b[index+1]);
- }
-
-
- .. code-block:: console
+: ```c++
+ template<class T> T add( T x, T y )
+ {
+ return x + y;
+ }
- clang -cl-std=clc++1.0 test.clcpp
- clang -cl-std=clc++ -c --target=spirv64 test.cl
+ __kernel void test( __global float* a, __global float* b)
+ {
+ auto index = get_global_id(0);
+ a[index] = add(b[index], b[index+1]);
+ }
+ ```
+ ```console
+ clang -cl-std=clc++1.0 test.clcpp
+ clang -cl-std=clc++ -c --target=spirv64 test.cl
+ ```
-By default, files with ``.clcpp`` extension are compiled with the C++ for
+By default, files with `.clcpp` extension are compiled with the C++ for
OpenCL 1.0 mode.
- .. code-block:: console
-
- clang test.clcpp
+> ```console
+> clang test.clcpp
+> ```
-For backward compatibility files with ``.cl`` extensions can also be compiled
+For backward compatibility files with `.cl` extensions can also be compiled
in C++ for OpenCL mode but the desirable language mode must be activated with
a flag.
- .. code-block:: console
-
- clang -cl-std=clc++ test.cl
+> ```console
+> clang -cl-std=clc++ test.cl
+> ```
Support of C++ for OpenCL 2021 is currently in experimental phase, refer to
-:doc:`OpenCLSupport` for more details.
+{doc}`OpenCLSupport` for more details.
C++ for OpenCL kernel sources can also be compiled online in drivers supporting
-`cl_ext_cxx_for_opencl
-<https://www.khronos.org/registry/OpenCL/extensions/ext/cl_ext_cxx_for_opencl.html>`_
+[cl_ext_cxx_for_opencl](https://www.khronos.org/registry/OpenCL/extensions/ext/cl_ext_cxx_for_opencl.html)
extension.
-Constructing and destroying global objects
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+#### Constructing and destroying global objects
Global objects with non-trivial constructors require the constructors to be run
before the first kernel using the global objects is executed. Similarly global
@@ -4712,10 +4909,10 @@ the last kernel using the program objects is executed.
In OpenCL versions earlier than v2.2 there is no support for invoking global
constructors. However, an easy workaround is to manually enqueue the
constructor initialization kernel that has the following name scheme
-``_GLOBAL__sub_I_<compiled file name>``.
+`_GLOBAL__sub_I_<compiled file name>`.
This kernel is only present if there are global objects with non-trivial
constructors present in the compiled binary. One way to check this is by
-passing ``CL_PROGRAM_KERNEL_NAMES`` to ``clGetProgramInfo`` (OpenCL v2.0
+passing `CL_PROGRAM_KERNEL_NAMES` to `clGetProgramInfo` (OpenCL v2.0
s5.8.7) and then checking whether any kernel name matches the naming scheme of
global constructor initialization kernel above.
@@ -4726,12 +4923,12 @@ invoked.
Applications are currently required to run initialization of global objects
manually before running any kernels in which the objects are used.
- .. code-block:: console
-
- clang -cl-std=clc++ test.cl
+> ```console
+> clang -cl-std=clc++ test.cl
+> ```
If there are any global objects to be initialized, the final binary will
-contain the ``_GLOBAL__sub_I_test.cl`` kernel to be enqueued.
+contain the `_GLOBAL__sub_I_test.cl` kernel to be enqueued.
Note that the manual workaround only applies to objects declared at the
program scope. There is no manual workaround for the construction of static
@@ -4739,36 +4936,33 @@ objects with non-trivial constructors inside functions.
Global destructors can not be invoked manually in the OpenCL v2.0 drivers.
However, all memory used for program scope objects should be released on
-``clReleaseProgram``.
+`clReleaseProgram`.
+
+#### Libraries
-Libraries
-^^^^^^^^^
Limited experimental support of C++ standard libraries for OpenCL is
-described in :doc:`OpenCLSupport` page.
+described in {doc}`OpenCLSupport` page.
-.. _target_features:
+(target-features)=
-Target-Specific Features and Limitations
-========================================
+## Target-Specific Features and Limitations
-CPU Architectures Features and Limitations
-------------------------------------------
+### CPU Architectures Features and Limitations
-X86
-^^^
+#### X86
The support for X86 (both 32-bit and 64-bit) is considered stable on
Darwin (macOS), Linux, FreeBSD, and Dragonfly BSD: it has been tested
to correctly compile many large C, C++, Objective-C, and Objective-C++
codebases.
-On ``x86_64-mingw32``, passing i128(by value) is incompatible with the
+On `x86_64-mingw32`, passing i128(by value) is incompatible with the
Microsoft x64 calling convention. You might need to tweak
-``WinX86_64ABIInfo::classify()`` in ``lib/CodeGen/Targets/X86.cpp``.
+`WinX86_64ABIInfo::classify()` in `lib/CodeGen/Targets/X86.cpp`.
For the X86 target, clang supports the `-m16` command line
argument which enables 16-bit code output. This is broadly similar to
-using ``asm(".code16gcc")`` with the GNU toolchain. The generated code
+using `asm(".code16gcc")` with the GNU toolchain. The generated code
and the ABI remains 32-bit but the assembler emits instructions
appropriate for a CPU running in 16-bit mode, with address-size and
operand-size prefixes to enable 32-bit addressing and operations.
@@ -4777,22 +4971,21 @@ Several micro-architecture levels as specified by the x86-64 psABI are defined.
They are cumulative in the sense that features from previous levels are
implicitly included in later levels.
-- ``-march=x86-64``: CMOV, CMPXCHG8B, FPU, FXSR, MMX, FXSR, SCE, SSE, SSE2
-- ``-march=x86-64-v2``: (close to Nehalem) CMPXCHG16B, LAHF-SAHF, POPCNT, SSE3, SSE4.1, SSE4.2, SSSE3
-- ``-march=x86-64-v3``: (close to Haswell) AVX, AVX2, BMI1, BMI2, F16C, FMA, LZCNT, MOVBE, XSAVE
-- ``-march=x86-64-v4``: AVX512F, AVX512BW, AVX512CD, AVX512DQ, AVX512VL
+- `-march=x86-64`: CMOV, CMPXCHG8B, FPU, FXSR, MMX, FXSR, SCE, SSE, SSE2
+- `-march=x86-64-v2`: (close to Nehalem) CMPXCHG16B, LAHF-SAHF, POPCNT, SSE3, SSE4.1, SSE4.2, SSSE3
+- `-march=x86-64-v3`: (close to Haswell) AVX, AVX2, BMI1, BMI2, F16C, FMA, LZCNT, MOVBE, XSAVE
+- `-march=x86-64-v4`: AVX512F, AVX512BW, AVX512CD, AVX512DQ, AVX512VL
-`Intel AVX10 ISA <https://cdrdv2.intel.com/v1/dl/getContent/784343>`_ is
+[Intel AVX10 ISA](https://cdrdv2.intel.com/v1/dl/getContent/784343) is
a major new vector ISA incorporating the modern vectorization aspects of
Intel AVX-512. This ISA will be supported on all future Intel processors.
-Users are supposed to use the new options ``-mavx10.N`` on these processors
-and should not use traditional AVX512 options anymore. The ``N`` in
-``-mavx10.N`` represents a continuous integer number starting
-from ``1``. Current binaries built with AVX512 features can run on Intel AVX10
+Users are supposed to use the new options `-mavx10.N` on these processors
+and should not use traditional AVX512 options anymore. The `N` in
+`-mavx10.N` represents a continuous integer number starting
+from `1`. Current binaries built with AVX512 features can run on Intel AVX10
capable processors without re-compile.
-ARM
-^^^
+#### ARM
The support for ARM (specifically ARMv6 and ARMv7) is considered stable
on Darwin (iOS): it has been tested to correctly compile many large C,
@@ -4800,16 +4993,14 @@ C++, Objective-C, and Objective-C++ codebases. Clang only supports a
limited number of ARM architectures. It does not yet fully support
ARMv5, for example.
-PowerPC
-^^^^^^^
+#### PowerPC
The support for PowerPC (especially PowerPC64) is considered stable
on Linux and FreeBSD: it has been tested to correctly compile many
large C and C++ codebases. PowerPC (32bit) is still missing certain
features (e.g. PIC code on ELF platforms).
-Other platforms
-^^^^^^^^^^^^^^^
+#### Other platforms
clang currently contains some support for other architectures (e.g. Sparc);
however, significant pieces of code generation are still missing, and they
@@ -4821,89 +5012,84 @@ experimental.
Other platforms are completely unsupported at the moment. Adding the
minimal support needed for parsing and semantic analysis on a new
-platform is quite easy; see ``lib/Basic/Targets.cpp`` in the clang source
+platform is quite easy; see `lib/Basic/Targets.cpp` in the clang source
tree. This level of support is also sufficient for conversion to LLVM IR
for simple programs. Proper support for conversion to LLVM IR requires
-adding code to ``lib/CodeGen/CGCall.cpp`` at the moment; this is likely to
+adding code to `lib/CodeGen/CGCall.cpp` at the moment; this is likely to
change soon, though. Generating assembly requires a suitable LLVM
backend.
-Operating System Features and Limitations
------------------------------------------
+### Operating System Features and Limitations
-Windows
-^^^^^^^
+#### Windows
Clang has experimental support for targeting "Cygming" (Cygwin / MinGW)
platforms.
-See also :ref:`Microsoft Extensions <c_ms>`.
+See also {ref}`Microsoft Extensions <c_ms>`.
-Cygwin
-""""""
+##### Cygwin
Clang works on Cygwin-1.7.
-MinGW32
-"""""""
+##### MinGW32
Clang works on some mingw32 distributions. Clang assumes directories as
below;
-- ``C:/mingw/include``
-- ``C:/mingw/lib``
-- ``C:/mingw/lib/gcc/mingw32/4.[3-5].0/include/c++``
+- `C:/mingw/include`
+- `C:/mingw/lib`
+- `C:/mingw/lib/gcc/mingw32/4.[3-5].0/include/c++`
On MSYS, a few tests might fail.
-MinGW-w64
-"""""""""
+##### MinGW-w64
-For 32-bit (i686-w64-mingw32), and 64-bit (x86\_64-w64-mingw32), Clang
+For 32-bit (i686-w64-mingw32), and 64-bit (x86_64-w64-mingw32), Clang
assumes as below;
-- ``GCC versions 4.5.0 to 4.5.3, 4.6.0 to 4.6.2, or 4.7.0 (for the C++ header search path)``
-- ``some_directory/bin/gcc.exe``
-- ``some_directory/bin/clang.exe``
-- ``some_directory/bin/clang++.exe``
-- ``some_directory/bin/../include/c++/GCC_version``
-- ``some_directory/bin/../include/c++/GCC_version/x86_64-w64-mingw32``
-- ``some_directory/bin/../include/c++/GCC_version/i686-w64-mingw32``
-- ``some_directory/bin/../include/c++/GCC_version/backward``
-- ``some_directory/bin/../x86_64-w64-mingw32/include``
-- ``some_directory/bin/../i686-w64-mingw32/include``
-- ``some_directory/bin/../include``
+- `GCC versions 4.5.0 to 4.5.3, 4.6.0 to 4.6.2, or 4.7.0 (for the C++ header search path)`
+- `some_directory/bin/gcc.exe`
+- `some_directory/bin/clang.exe`
+- `some_directory/bin/clang++.exe`
+- `some_directory/bin/../include/c++/GCC_version`
+- `some_directory/bin/../include/c++/GCC_version/x86_64-w64-mingw32`
+- `some_directory/bin/../include/c++/GCC_version/i686-w64-mingw32`
+- `some_directory/bin/../include/c++/GCC_version/backward`
+- `some_directory/bin/../x86_64-w64-mingw32/include`
+- `some_directory/bin/../i686-w64-mingw32/include`
+- `some_directory/bin/../include`
This directory layout is standard for any toolchain you will find on the
-official `MinGW-w64 website <http://mingw-w64.sourceforge.net>`_.
+official [MinGW-w64 website](http://mingw-w64.sourceforge.net).
Clang expects the GCC executable "gcc.exe" compiled for
-``i686-w64-mingw32`` (or ``x86_64-w64-mingw32``) to be present on PATH.
+`i686-w64-mingw32` (or `x86_64-w64-mingw32`) to be present on PATH.
+
+[Some tests might fail](https://bugs.llvm.org/show_bug.cgi?id=9072) on
+`x86_64-w64-mingw32`.
-`Some tests might fail <https://bugs.llvm.org/show_bug.cgi?id=9072>`_ on
-``x86_64-w64-mingw32``.
+#### AIX
-AIX
-^^^
-TOC Data Transformation
-"""""""""""""""""""""""
-TOC data transformation is off by default (``-mno-tocdata``).
-When ``-mtocdata`` is specified, the TOC data transformation will be applied to
+##### TOC Data Transformation
+
+TOC data transformation is off by default (`-mno-tocdata`).
+When `-mtocdata` is specified, the TOC data transformation will be applied to
all suitable variables with static storage duration, including static data
members of classes and block-scope static variables (if not marked as exceptions,
see further below).
Suitable variables must:
-- have complete types
-- be independently generated (i.e., not placed in a pool)
-- be at most as large as a pointer
-- not be aligned more strictly than a pointer
-- not be structs containing flexible array members
-- not have internal linkage
-- not have aliases
-- not have section attributes
-- not be thread local storage
+- have complete types
+- be independently generated (i.e., not placed in a pool)
+- be at most as large as a pointer
+- not be aligned more strictly than a pointer
+- not be structs containing flexible array members
+- not have internal linkage
+- not have aliases
+- not have section attributes
+- not be thread local storage
The TOC data transformation results in the variable, not its address,
being placed in the TOC. This eliminates the need to load the address of the
@@ -4915,69 +5101,75 @@ is imported, the linker will generate fixup code for reading or writing to the
variable.
When multiple toc-data options are used, the last option used has the affect.
-For example: ``-mno-tocdata=g5,g1 -mtocdata=g1,g2 -mno-tocdata=g2 -mtocdata=g3,g4``
-results in ``-mtocdata=g1,g3,g4``
+For example: `-mno-tocdata=g5,g1 -mtocdata=g1,g2 -mno-tocdata=g2 -mtocdata=g3,g4`
+results in `-mtocdata=g1,g3,g4`
Names of variables not having external linkage will be ignored.
**Options:**
+```{eval-rst}
.. option:: -mno-tocdata
This is the default behaviour. Only variables explicitly specified with
``-mtocdata=`` will have the TOC data transformation applied.
+```
+```{eval-rst}
.. option:: -mtocdata
Apply the TOC data transformation to all suitable variables with static
storage duration (including static data members of classes and block-scope
static variables) that are not explicitly specified with ``-mno-tocdata=``.
+```
+```{eval-rst}
.. option:: -mno-tocdata=
Can be used in conjunction with ``-mtocdata`` to mark the comma-separated
list of external linkage variables, specified using their mangled names, as
exceptions to ``-mtocdata``.
+```
+```{eval-rst}
.. option:: -mtocdata=
Apply the TOC data transformation to the comma-separated list of external
linkage variables, specified using their mangled names, if they are suitable.
Emit diagnostics for all unsuitable variables specified.
+```
+
+##### Default Visibility Export Mapping
-Default Visibility Export Mapping
-"""""""""""""""""""""""""""""""""
-The ``-mdefault-visibility-export-mapping=`` option can be used to control
+The `-mdefault-visibility-export-mapping=` option can be used to control
mapping of default visibility to an explicit shared object export
(i.e. XCOFF exported visibility). Three values are provided for the option:
-* ``-mdefault-visibility-export-mapping=none``: no additional export
+- `-mdefault-visibility-export-mapping=none`: no additional export
information is created for entities with default visibility.
-* ``-mdefault-visibility-export-mapping=explicit``: mark entities for export
+- `-mdefault-visibility-export-mapping=explicit`: mark entities for export
if they have explicit (e.g. via an attribute) default visibility from the
source, including RTTI.
-* ``-mdefault-visibility-export-mapping=all``: set XCOFF exported visibility
+- `-mdefault-visibility-export-mapping=all`: set XCOFF exported visibility
for all entities with default visibility from any source. This gives a
export behavior similar to ELF platforms where all entities with default
visibility are exported.
-.. _spir-v:
+(spir-v)=
-SPIR-V support
---------------
+### SPIR-V support
-Clang supports generation of SPIR-V conformant to `the OpenCL Environment
-Specification
-<https://www.khronos.org/registry/OpenCL/specs/3.0-unified/html/OpenCL_Env.html>`_.
+Clang supports generation of SPIR-V conformant to [the OpenCL Environment
+Specification](https://www.khronos.org/registry/OpenCL/specs/3.0-unified/html/OpenCL_Env.html).
To generate SPIR-V binaries, Clang uses the in-tree LLVM SPIR-V backend.
Example usage for OpenCL kernel compilation:
- .. code-block:: console
-
- $ clang --target=spirv32 -c test.cl
- $ clang --target=spirv64 -c test.cl
+> ```console
+> $ clang --target=spirv32 -c test.cl
+> $ clang --target=spirv64 -c test.cl
+> ```
Both invocations of Clang will result in the generation of a SPIR-V binary file
`test.o` for 32 bit and 64 bit respectively. This file can be imported
@@ -4988,25 +5180,21 @@ Converting to SPIR-V produced with the optimization levels other than `-O0` is
currently available as an experimental feature and it is not guaranteed to work
in all cases.
-Linking is done using ``spirv-link`` from `the SPIRV-Tools project
-<https://github.com/KhronosGroup/SPIRV-Tools#linker>`_. Similar to other external
-linkers, Clang will expect ``spirv-link`` to be installed separately and to be
-present in the ``PATH`` environment variable. Please refer to `the build and
-installation instructions
-<https://github.com/KhronosGroup/SPIRV-Tools#build>`_.
+Linking is done using `spirv-link` from [the SPIRV-Tools project](https://github.com/KhronosGroup/SPIRV-Tools#linker). Similar to other external
+linkers, Clang will expect `spirv-link` to be installed separately and to be
+present in the `PATH` environment variable. Please refer to [the build and
+installation instructions](https://github.com/KhronosGroup/SPIRV-Tools#build).
- .. code-block:: console
-
- $ clang --target=spirv64 test1.cl test2.cl
+> ```console
+> $ clang --target=spirv64 test1.cl test2.cl
+> ```
More information about the SPIR-V target settings and supported versions of SPIR-V
-format can be found in `the SPIR-V target guide
-<https://llvm.org/docs/SPIRVUsage.html>`__.
+format can be found in [the SPIR-V target guide](https://llvm.org/docs/SPIRVUsage.html).
-.. _clang-cl:
+(clang-cl)=
-clang-cl
-========
+## clang-cl
clang-cl is an alternative command-line interface to Clang, designed for
compatibility with the Visual C++ compiler, cl.exe.
@@ -5014,1011 +5202,1007 @@ compatibility with the Visual C++ compiler, cl.exe.
To enable clang-cl to find system headers, libraries, and the linker when run
from the command-line, it should be executed inside a Visual Studio Native Tools
Command Prompt or a regular Command Prompt where the environment has been set
-up using e.g. `vcvarsall.bat <https://msdn.microsoft.com/en-us/library/f2ccy3wt.aspx>`_.
+up using e.g. [vcvarsall.bat](https://msdn.microsoft.com/en-us/library/f2ccy3wt.aspx).
clang-cl can also be used from inside Visual Studio by selecting the LLVM
Platform Toolset. The toolset is not part of the installer, but may be installed
separately from the
-`Visual Studio Marketplace <https://marketplace.visualstudio.com/items?itemName=LLVMExtensions.llvm-toolchain>`_.
+[Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=LLVMExtensions.llvm-toolchain).
To use the toolset, select a project in Solution Explorer, open its Property
Page (Alt+F7), and in the "General" section of "Configuration Properties"
-change "Platform Toolset" to LLVM. Doing so enables an additional Property
+change "Platform Toolset" to LLVM. Doing so enables an additional Property
Page for selecting the clang-cl executable to use for builds.
To use the toolset with MSBuild directly, invoke it with e.g.
-``/p:PlatformToolset=LLVM``. This allows trying out the clang-cl toolchain
+`/p:PlatformToolset=LLVM`. This allows trying out the clang-cl toolchain
without modifying your project files.
It's also possible to point MSBuild at clang-cl without changing toolset by
-passing ``/p:CLToolPath=c:\llvm\bin /p:CLToolExe=clang-cl.exe``.
-
-When using CMake and the Visual Studio generators, the toolset can be set with the ``-T`` flag:
+passing `/p:CLToolPath=c:\llvm\bin /p:CLToolExe=clang-cl.exe`.
- ::
-
- cmake -G"Visual Studio 16 2019" -T LLVM ..
+When using CMake and the Visual Studio generators, the toolset can be set with the `-T` flag:
-When using CMake with the Ninja generator, set the ``CMAKE_C_COMPILER`` and
-``CMAKE_CXX_COMPILER`` variables to clang-cl:
-
- ::
+> ```
+> cmake -G"Visual Studio 16 2019" -T LLVM ..
+> ```
- cmake -GNinja -DCMAKE_C_COMPILER="c:/Program Files (x86)/LLVM/bin/clang-cl.exe"
- -DCMAKE_CXX_COMPILER="c:/Program Files (x86)/LLVM/bin/clang-cl.exe" ..
+When using CMake with the Ninja generator, set the `CMAKE_C_COMPILER` and
+`CMAKE_CXX_COMPILER` variables to clang-cl:
+> ```
+> cmake -GNinja -DCMAKE_C_COMPILER="c:/Program Files (x86)/LLVM/bin/clang-cl.exe"
+> -DCMAKE_CXX_COMPILER="c:/Program Files (x86)/LLVM/bin/clang-cl.exe" ..
+> ```
-Command-Line Options
---------------------
+### Command-Line Options
To be compatible with cl.exe, clang-cl supports most of the same command-line
-options. Those options can start with either ``/`` or ``-``. It also supports
-some of Clang's core options, such as the ``-W`` options.
+options. Those options can start with either `/` or `-`. It also supports
+some of Clang's core options, such as the `-W` options.
Options that are known to clang-cl, but not currently supported, are ignored
with a warning. For example:
- ::
-
- clang-cl.exe: warning: argument unused during compilation: '/AI'
+> ```
+> clang-cl.exe: warning: argument unused during compilation: '/AI'
+> ```
-To suppress warnings about unused arguments, use the ``-Qunused-arguments`` option.
+To suppress warnings about unused arguments, use the `-Qunused-arguments` option.
Options that are not known to clang-cl will be ignored by default. Use the
-``-Werror=unknown-argument`` option in order to treat them as errors. If these
-options are spelled with a leading ``/``, they will be mistaken for a filename:
-
- ::
+`-Werror=unknown-argument` option in order to treat them as errors. If these
+options are spelled with a leading `/`, they will be mistaken for a filename:
- clang-cl.exe: error: no such file or directory: '/foobar'
+> ```
+> clang-cl.exe: error: no such file or directory: '/foobar'
+> ```
-Please `file a bug <https://github.com/llvm/llvm-project/issues/new?labels=clang-cl>`_
+Please [file a bug](https://github.com/llvm/llvm-project/issues/new?labels=clang-cl)
for any valid cl.exe flags that clang-cl does not understand.
-Execute ``clang-cl /?`` to see a list of supported options:
-
- ::
-
- CL.EXE COMPATIBILITY OPTIONS:
- /? Display available options
- /arch:<value> Set architecture for code generation
- /arm64EC Set build target to arm64ec
- /Brepro- Write current time into COFF output (default)
- /Brepro Do not write current time into COFF output (breaks link.exe /incremental)
- /clang:<arg> Pass <arg> to the clang driver
- /C Do not discard comments when preprocessing
- /c Compile only
- /d1PP Retain macro definitions in /E mode
- /d1reportAllClassLayout Dump record layout information
- /d2epilogunwindrequirev2
- Require generation of unwind v2 (epilog) information for x64 Windows
- /d2epilogunwind Best effort generate unwind v2 (epilog) information for x64 Windows
- /diagnostics:caret Enable caret and column diagnostics (default)
- /diagnostics:classic Disable column and caret diagnostics
- /diagnostics:column Disable caret diagnostics but keep column info
- /diasdkdir <dir> Path to the DIA SDK
- /D <macro[=value]> Define macro
- /EH<value> Set exception handling model
- /EP Disable linemarker output and preprocess to stdout
- /execution-charset:<value>
- Set runtime encoding, supports only UTF-8
- /external:env:<var> Add dirs in env var <var> to include search path with warnings suppressed
- /external:I <dir> Add directory to include search path with warnings suppressed
- /external:W0 Ignore warnings from system headers (default)
- /external:W1 Enable -Wsystem-headers
- /external:W2 Enable -Wsystem-headers
- /external:W3 Enable -Wsystem-headers
- /external:W4 Enable -Wsystem-headers
- /E Preprocess to stdout
- /FA<value> Output assembly code file during compilation
- /Fa<file or dir/> Set assembly output file name (with /FA)
- /Fe<file or dir/> Set output executable file name
- /FI <value> Include file before parsing
- /Fi<file> Set preprocess output file name (with /P)
- /Fo<file or dir/> Set output object file (with /c)
- /Fp<file> Set pch file name (with /Yc and /Yu)
- /fsanitize=address Enable AddressSanitizer
- /funcoverride:<function>
- Mark <function> as being replaceable by the Windows kernel loader
- /GA Assume thread-local variables are defined in the executable
- /Gd Set __cdecl as a default calling convention
- /GF- Disable string pooling
- /GF Enable string pooling (default)
- /GR- Do not emit RTTI data
- /Gregcall4 Set __regcall4 as a default calling convention to respect __regcall ABI v.4
- /Gregcall Set __regcall as a default calling convention
- /GR Emit RTTI data (default)
- /Gr Set __fastcall as a default calling convention
- /GS- Disable buffer security check
- /GS Enable buffer security check (default)
- /Gs Use stack probes (default)
- /Gs<value> Set stack probe size (default 4096)
- /guard:<value> Enable Control Flow Guard with /guard:cf, or only the table with /guard:cf,nochecks. Enable EH Continuation Guard with /guard:ehcont
- /Gv Set __vectorcall as a default calling convention
- /Gw- Do not put each data item in its own section (default)
- /Gw Put each data item in its own section
- /GX- Deprecated (like not passing /EH)
- /GX Deprecated; use /EHsc
- /Gy- Do not put each function in its own section (default)
- /Gy Put each function in its own section
- /Gz Set __stdcall as a default calling convention
- /help Display available options
- /hotpatch Create hotpatchable image
- /imsvc <dir> Add <dir> to system include search path, as if in %INCLUDE%
- /I <dir> Add directory to include search path
- /JMC- Disable just-my-code debugging (default)
- /JMC Enable just-my-code debugging
- /J Make char type unsigned
- /LDd Create debug DLL
- /LD Create DLL
- /link <options> Forward options to the linker
- /MDd Use DLL debug run-time
- /MD Use DLL run-time
- /MTd Use static debug run-time
- /MT Use static run-time
- /O1 Optimize for size (like /Og /Os /Oy /Ob2 /GF /Gy)
- /O2 Optimize for speed (like /Og /Oi /Ot /Oy /Ob2 /GF /Gy)
- /Ob0 Disable function inlining
- /Ob1 Only inline functions explicitly or implicitly marked inline
- /Ob2 Inline functions as deemed beneficial by the compiler
- /Ob3 Same as /Ob2
- /Od Disable optimization
- /Og No effect
- /Oi- Disable use of builtin functions
- /Oi Enable use of builtin functions
- /openmp- Disable OpenMP support
- /openmp:experimental Enable OpenMP support with experimental SIMD support
- /openmp Enable OpenMP support
- /Os Optimize for size (like clang -Os)
- /Ot Optimize for speed (like clang -O3)
- /Ox Deprecated (like /Og /Oi /Ot /Oy /Ob2); use /O2
- /Oy- Disable frame pointer omission (x86 only, default)
- /Oy Enable frame pointer omission (x86 only)
- /O<flags> Set multiple /O flags at once; e.g. '/O2y-' for '/O2 /Oy-'
- /o <file or dir/> Deprecated (set output file name); use /Fe or /Fe
- /permissive- Disable non conforming code from compiling (default)
- /permissive Enable some non conforming code to compile
- /P Preprocess to file
- /Qgather- Disable generation of gather instructions in auto-vectorization(x86 only)
- /QIntel-jcc-erratum Align branches within 32-byte boundaries to mitigate the performance impact of the Intel JCC erratum.
- /Qscatter- Disable generation of scatter instructions in auto-vectorization(x86 only)
- /Qvec- Disable the loop vectorization passes
- /Qvec Enable the loop vectorization passes
- /showFilenames- Do not print the name of each compiled file (default)
- /showFilenames Print the name of each compiled file
- /showIncludes:user Like /showIncludes but omit system headers
- /showIncludes Print info about included files to stderr
- /source-charset:<value> Set source encoding, supports only UTF-8
- /std:<value> Set language version (c++14,c++17,c++20,c++23preview,c++26preview,c++latest,c11,c17)
- /TC Treat all source files as C
- /Tc <file> Treat <file> as C source file
- /TP Treat all source files as C++
- /Tp <file> Treat <file> as C++ source file
- /tune:<value> Set CPU for optimization without affecting instruction set
- /utf-8 Set source and runtime encoding to UTF-8 (default)
- /U <macro> Undefine macro
- /vctoolsdir <dir> Path to the VCToolChain
- /vctoolsversion <value> For use with /winsysroot, defaults to newest found
- /vd<value> Control vtordisp placement
- /vlen=256 Set vector length of 256 bits for autovectorization and other optimizations
- /vlen=512 Set vector length of 512 bits for autovectorization and other optimizations
- /vlen Set default vector length for autovectorization and other optimizations
- /vmb Use a best-case representation method for member pointers
- /vmg Use a most-general representation for member pointers
- /vmm Set the default most-general representation to multiple inheritance
- /vms Set the default most-general representation to single inheritance
- /vmv Set the default most-general representation to virtual inheritance
- /W0 Disable all warnings
- /W1 Enable -Wall
- /W2 Enable -Wall
- /W3 Enable -Wall
- /W4 Enable -Wall and -Wextra
- /Wall Enable -Weverything
- /winsdkdir <dir> Path to the Windows SDK
- /winsdkversion <value> Full version of the Windows SDK, defaults to newest found
- /winsysroot <dir> Same as "/diasdkdir <dir>/DIA SDK" /vctoolsdir <dir>/VC/Tools/MSVC/<vctoolsversion> "/winsdkdir <dir>/Windows Kits/10"
- /WX- Do not treat warnings as errors (default)
- /WX Treat warnings as errors
- /w Disable all warnings
- /X Do not add %INCLUDE% to include search path
- /Y- Disable precompiled headers, overrides /Yc and /Yu
- /Yc<filename> Generate a pch file for all code up to and including <filename>
- /Yu<filename> Load a pch file and use it instead of all code up to and including <filename>
- /Z7 Enable CodeView debug information in object files
- /Zc:__STDC__ Define __STDC__
- /Zc:alignedNew- Disable C++17 aligned allocation functions
- /Zc:alignedNew Enable C++17 aligned allocation functions
- /Zc:char8_t- Disable char8_t from c++2a
- /Zc:char8_t Enable char8_t from C++2a
- /Zc:dllexportInlines- Do not dllexport/dllimport inline member functions of dllexport/import classes
- /Zc:dllexportInlines dllexport/dllimport inline member functions of dllexport/import classes (default)
- /Zc:sizedDealloc- Disable C++14 sized global deallocation functions
- /Zc:sizedDealloc Enable C++14 sized global deallocation functions
- /Zc:strictStrings Treat string literals as const
- /Zc:threadSafeInit- Disable thread-safe initialization of static variables
- /Zc:threadSafeInit Enable thread-safe initialization of static variables
- /Zc:tlsGuards- Disable on-demand initialization of thread-local variables
- /Zc:tlsGuards Enable on-demand initialization of thread-local variables
- /Zc:trigraphs- Disable trigraphs (default)
- /Zc:trigraphs Enable trigraphs
- /Zc:twoPhase- Disable two-phase name lookup in templates (default)
- /Zc:twoPhase Enable two-phase name lookup in templates
- /Zc:wchar_t- Disable C++ builtin type wchar_t
- /Zc:wchar_t Enable C++ builtin type wchar_t (default)
- /ZH:MD5 Use MD5 for file checksums in debug info (default)
- /ZH:SHA1 Use SHA1 for file checksums in debug info
- /ZH:SHA_256 Use SHA256 for file checksums in debug info
- /Zi Like /Z7
- /Zl Do not let object file auto-link default libraries
- /Zp Set default maximum struct packing alignment to 1
- /Zp<value> Set default maximum struct packing alignment
- /Zs Run the preprocessor, parser and semantic analysis stages
-
- OPTIONS:
- -### Print (but do not run) the commands to run for this compilation
- --analyze Run the static analyzer
- --config=<file> Specify configuration file
- --cuda-compile-host-device
- Compile CUDA code for both host and device (default). Has no effect on non-CUDA compilations.
- --cuda-device-only Compile CUDA code for device only
- --cuda-feature=<value> Manually specify the CUDA feature to use
- --cuda-host-only Compile CUDA code for host only. Has no effect on non-CUDA compilations.
- --cuda-include-ptx=<value>
- Include PTX for the following GPU architecture (e.g. sm_35) or 'all'. May be specified more than once.
- --cuda-noopt-device-debug
- Enable device-side debug info generation. Disables ptxas optimizations.
- --cuda-path-ignore-env Ignore environment variables to detect CUDA installation
- --cuda-path=<value> CUDA installation path
- -cuid=<value> An ID for compilation unit, which should be the same for the same compilation unit but different for different compilation units. It is used to externalize device-side static variables for single source offloading languages CUDA and HIP so that they can be accessed by the host code of the same compilation unit.
- -darwin-target-variant <value>
- Generate code for an additional runtime variant of the deployment target
- -emit-ast Emit Clang AST files for source inputs
- --end-no-unused-arguments
- Start emitting warnings for unused driver arguments
- -faddrsig Emit an address-significance table
- -fansi-escape-codes Use ANSI escape codes for diagnostics
- -fblocks Enable the 'blocks' language feature
- -fcaret-diagnostics-max-lines=<value>
- Set the maximum number of source lines to show in a caret diagnostic (0 = no limit).
- -fcf-protection=<value> Instrument control-flow architecture protection
- -fcf-protection Enable cf-protection in 'full' mode
- -fcodegen-data-generate=<path>
- Emit codegen data into the object file. LLD for MachO (currently) merges them into the specified <path>.
- -fcodegen-data-generate Emit codegen data into the object file. LLD for MachO (currently) merges them into default.cgdata.
- -fcodegen-data-use=<path>
- Use codegen data read from the specified <path>.
- -fcodegen-data-use Use codegen data read from default.cgdata to optimize the binary
- -fcolor-diagnostics Enable colors in diagnostics
- -fcommon Place uninitialized global variables in a common block
- -fcomplete-member-pointers
- Require member pointer base types to be complete if they would be significant under the Microsoft ABI
- -fcoverage-compilation-dir=<value>
- The compilation directory to embed in the coverage mapping.
- -fcoverage-mapping Generate coverage mapping to enable code coverage analysis
- -fcoverage-mcdc Enable MC/DC criteria when generating code coverage
- -fcrash-diagnostics-dir=<dir>
- Put crash-report files in <dir>
- -fcrash-diagnostics=<value>
- Set level of crash diagnostic reporting, (option: off, compiler, all)
- -fcrash-diagnostics Enable crash diagnostic reporting (default)
- -fcs-profile-generate=<directory>
- Generate instrumented code to collect context sensitive execution counts into <directory>/default.profraw (overridden by LLVM_PROFILE_FILE env var)
- -fcs-profile-generate Generate instrumented code to collect context sensitive execution counts into default.profraw (overridden by LLVM_PROFILE_FILE env var)
- -fcuda-short-ptr Use 32-bit pointers for accessing const/local/shared address spaces
- -fdebug-compilation-dir=<value>
- The compilation directory to embed in the debug info
- -fdebug-macro Emit macro debug information
- -fdelayed-template-parsing
- Parse templated function definitions at the end of the translation unit
- -fdelete-null-pointer-checks
- Treat usage of null pointers as undefined behavior (default)
- -fdevirtualize-speculatively
- Enables speculative devirtualization optimization.
- -fdiagnostics-absolute-paths
- Print absolute paths in diagnostics
- -fdiagnostics-color=<value>
- When to use colors in diagnostics
- -fdiagnostics-parseable-fixits
- Print fix-its in machine parseable form
- -fdriver-only Only run the driver.
- -feliminate-unused-debug-types
- Do not emit debug info for defined but unused types
- -fexcess-precision=<value>
- Allows control over excess precision on targets where native support for the precision types is not available. By default, excess precision is used to calculate intermediate results following the rules specified in ISO C99.
- -fexperimental-library Control whether unstable and experimental library features are enabled. This option enables various library features that are either experimental (also known as TSes), or have been but are not stable yet in the selected Standard Library implementation. It is not recommended to use this option in production code, since neither ABI nor API stability are guaranteed. This is intended to provide a preview of features that will ship in the future for experimentation purposes
- -fexperimental-sanitize-metadata-ignorelist=<value>
- Disable sanitizer metadata for modules and functions that match the provided special case list
- -fexperimental-sanitize-metadata=<value>
- Specify the type of metadata to emit for binary analysis sanitizers
- -ffile-compilation-dir=<value>
- The compilation directory to embed in the debug info and coverage mapping.
- -ffile-reproducible Use the target's platform-specific path separator character when expanding the __FILE__ macro
- -ffixed-x10 Reserve the x10 register (AArch64/RISC-V only)
- -ffixed-x11 Reserve the x11 register (AArch64/RISC-V only)
- -ffixed-x12 Reserve the x12 register (AArch64/RISC-V only)
- -ffixed-x13 Reserve the x13 register (AArch64/RISC-V only)
- -ffixed-x14 Reserve the x14 register (AArch64/RISC-V only)
- -ffixed-x15 Reserve the x15 register (AArch64/RISC-V only)
- -ffixed-x16 Reserve the x16 register (AArch64/RISC-V only)
- -ffixed-x17 Reserve the x17 register (AArch64/RISC-V only)
- -ffixed-x18 Reserve the x18 register (AArch64/RISC-V only)
- -ffixed-x19 Reserve the x19 register (AArch64/RISC-V only)
- -ffixed-x1 Reserve the x1 register (AArch64/RISC-V only)
- -ffixed-x20 Reserve the x20 register (AArch64/RISC-V only)
- -ffixed-x21 Reserve the x21 register (AArch64/RISC-V only)
- -ffixed-x22 Reserve the x22 register (AArch64/RISC-V only)
- -ffixed-x23 Reserve the x23 register (AArch64/RISC-V only)
- -ffixed-x24 Reserve the x24 register (AArch64/RISC-V only)
- -ffixed-x25 Reserve the x25 register (AArch64/RISC-V only)
- -ffixed-x26 Reserve the x26 register (AArch64/RISC-V only)
- -ffixed-x27 Reserve the x27 register (AArch64/RISC-V only)
- -ffixed-x28 Reserve the x28 register (AArch64/RISC-V only)
- -ffixed-x29 Reserve the x29 register (AArch64/RISC-V only)
- -ffixed-x2 Reserve the x2 register (AArch64/RISC-V only)
- -ffixed-x30 Reserve the x30 register (AArch64/RISC-V only)
- -ffixed-x31 Reserve the x31 register (AArch64/RISC-V only)
- -ffixed-x3 Reserve the x3 register (AArch64/RISC-V only)
- -ffixed-x4 Reserve the x4 register (AArch64/RISC-V only)
- -ffixed-x5 Reserve the x5 register (AArch64/RISC-V only)
- -ffixed-x6 Reserve the x6 register (AArch64/RISC-V only)
- -ffixed-x7 Reserve the x7 register (AArch64/RISC-V only)
- -ffixed-x8 Reserve the x8 register (AArch64/RISC-V only)
- -ffixed-x9 Reserve the x9 register (AArch64/RISC-V only)
- -fforce-emit-vtables Emits more virtual tables to improve devirtualization
- -ffuchsia-api-level=<value>
- Set Fuchsia API level
- -fgnuc-version=<value> Sets various macros to claim compatibility with the given GCC version (default is 4.2.1)
- -fgpu-allow-device-init Allow device side init function in HIP (experimental)
- -fgpu-default-stream=<value>
- Specify default stream. The default value is 'legacy'. (CUDA/HIP only)
- -fgpu-defer-diag Defer host/device related diagnostic messages for CUDA/HIP
- -fgpu-flush-denormals-to-zero
- Flush denormal floating point values to zero in CUDA/HIP device mode.
- -fgpu-rdc Generate relocatable device code, also known as separate compilation mode
- -fgpu-sanitize Enable sanitizer for supported offloading devices
- -fhip-emit-relocatable Compile HIP source to relocatable
- -fhip-fp32-correctly-rounded-divide-sqrt
- Specify that single precision floating-point divide and sqrt used in the program source are correctly rounded (HIP device compilation only)
- -fhip-kernel-arg-name Specify that kernel argument names are preserved (HIP only)
- -fhip-new-launch-api Use new kernel launching API for HIP
- -fimplicit-module-maps Implicitly search the file system for module map files.
- -finline-max-stacksize=<value>
- Suppress inlining of functions whose stack size exceeds the given value
- -fintegrated-cc1 Run cc1 in-process
- -fintegrated-objemitter Use internal machine object code emitter.
- -flto=<value> Set LTO mode
- -flto Enable LTO in 'full' mode
- -fmacro-backtrace-limit=<value>
- Set the maximum number of entries to print in a macro expansion backtrace (0 = no limit)
- -fmemory-profile-use=<pathname>
- Use memory profile for profile-guided memory optimization
- -fmerge-all-constants Allow merging of constants
- -fmodule-file=[<name>=]<file>
- Specify the mapping of module name to precompiled module file, or load a module file if name is omitted.
- -fmodule-header=<kind> Build a C++20 Header Unit from a header that should be found in the user (fmodule-header=user) or system (fmodule-header=system) search path.
- -fmodule-header Build a C++20 Header Unit from a header
- -fmodule-map-file=<file>
- Load this module map file
- -fmodule-name=<name> Specify the name of the module to build
- -fmodule-output=<value> Save intermediate module file results when compiling a standard C++ module unit.
- -fmodule-output Save intermediate module file results when compiling a standard C++ module unit.
- -fmodules-decluse Require declaration of modules used within a module
- -fmodules-embed-all-files<value>
- Embed the contents of all files read by this compilation into the produced module file.
- -fmodules-ignore-macro=<value>
- Ignore the definition of the given macro when building and loading modules
- -fmodules-search-all Search even non-imported modules to resolve references
- -fmodules-strict-decluse
- Like -fmodules-decluse but requires all headers to be in modules
- -fmodules Enable the 'modules' language feature
- -fms-compatibility-version=<value>
- Dot-separated value representing the Microsoft compiler version number to report in _MSC_VER (0 = don't define it (default))
- -fms-compatibility Enable full Microsoft Visual C++ compatibility
- -fms-define-stdc Define '__STDC__' to '1' in MSVC Compatibility mode
- -fms-extensions Accept some non-standard constructs supported by the Microsoft compiler
- -fms-hotpatch Ensure that all functions can be hotpatched at runtime
- -fms-runtime-lib=<value>
- Select Windows run-time library
- -fms-secure-hotpatch-functions-file=<value>
- Path to a file that contains a list of mangled names of functions that should be hot-patched for Windows Secure Hot-Patching
- -fms-secure-hotpatch-functions-list=<value>
- List of mangled symbol names of functions that should be hot-patched for Windows Secure Hot-Patching
- -fmsc-version=<value> Microsoft compiler version number to report in _MSC_VER (0 = don't define it (default))
- -fno-addrsig Don't emit an address-significance table
- -fno-assume-unique-vtables
- Disable optimizations based on vtable pointer identity
- -fno-builtin-<value> Disable implicit builtin knowledge of a specific function
- -fno-builtin Disable implicit builtin knowledge of functions
- -fno-color-diagnostics Disable colors in diagnostics
- -fno-complete-member-pointers
- Do not require member pointer base types to be complete if they would be significant under the Microsoft ABI
- -fno-coverage-mapping Disable code coverage analysis
- -fno-coverage-mcdc Disable MC/DC coverage criteria
- -fno-crash-diagnostics Disable auto-generation of preprocessed source files and a script for reproduction during a clang crash
- -fno-debug-macro Do not emit macro debug information
- -fno-delayed-template-parsing
- Disable delayed template parsing
- -fno-delete-null-pointer-checks
- Do not treat usage of null pointers as undefined behavior
- -fno-eliminate-unused-debug-types
- Emit debug info for defined but unused types
- -fno-experimental-sanitize-metadata=<value>
- Disable emitting metadata for binary analysis sanitizers
- -fno-file-reproducible Use the host's platform-specific path separator character when expanding the __FILE__ macro
- -fno-gpu-allow-device-init
- Don't allow device side init function in HIP (experimental)
- -fno-gpu-defer-diag Don't defer host/device related diagnostic messages for CUDA/HIP
- -fno-hip-emit-relocatable
- Do not override toolchain to compile HIP source to relocatable
- -fno-hip-fp32-correctly-rounded-divide-sqrt
- Don't specify that single precision floating-point divide and sqrt used in the program source are correctly rounded (HIP device compilation only)
- -fno-hip-kernel-arg-name
- Don't specify that kernel argument names are preserved (HIP only)
- -fno-hip-new-launch-api Don't use new kernel launching API for HIP
- -fno-integrated-cc1 Spawn a separate process for each cc1
- -fno-integrated-objemitter
- Use external machine object code emitter.
- -fno-knr-functions Disable support for K&R C function declarations
- -fno-lto Disable LTO mode (default)
- -fno-offload-lto Disable LTO mode (default) for offload compilation
- -fno-offload-via-llvm Don't use LLVM/Offload as portable offloading runtime.
- -fno-profile-generate Disable generation of profile instrumentation.
- -fno-profile-instr-generate
- Disable generation of profile instrumentation.
- -fno-profile-instr-use Disable using instrumentation data for profile-guided optimization
- -fno-pseudo-probe-for-profiling
- Do not emit pseudo probes for sample profiling
- -fno-rtlib-defaultlib On Windows, do not emit /defaultlib: directives to link compiler-rt libraries
- -fno-sanitize-address-globals-dead-stripping
- Disable linker dead stripping of globals in AddressSanitizer
- -fno-sanitize-address-outline-instrumentation
- Use default code inlining logic for the address sanitizer
- -fno-sanitize-address-poison-custom-array-cookie
- Disable poisoning array cookies when using custom operator new[] in AddressSanitizer
- -fno-sanitize-address-use-after-scope
- Disable use-after-scope detection in AddressSanitizer
- -fno-sanitize-address-use-odr-indicator
- Disable ODR indicator globals
- -fno-sanitize-alloc-token-extended
- Disable extended coverage to custom allocation functions
- -fno-sanitize-alloc-token-fast-abi
- Use the default AllocToken ABI
- -fno-sanitize-annotate-debug-info=<value>
- Do not allow compiler to annotate sanitizer instrumentation with extra debug info for the specified sanitizers
- -fno-sanitize-annotate-debug-info
- Do not allow compiler to annotate sanitizer instrumentation with extra debug info for any sanitizers
- -fno-sanitize-cfi-canonical-jump-tables
- Do not make the jump table addresses canonical in the symbol table
- -fno-sanitize-cfi-cross-dso
- Disable control flow integrity (CFI) checks for cross-DSO calls.
- -fno-sanitize-coverage=<value>
- Disable features of coverage instrumentation for Sanitizers
- -fno-sanitize-debug-trap-reasons
- Alias for -fsanitize-debug-trap-reasons=none
- -fno-sanitize-handler-preserve-all-regs
- Disable handlers with preserve_all calling convention
- -fno-sanitize-hwaddress-experimental-aliasing
- Disable aliasing mode in HWAddressSanitizer
- -fno-sanitize-ignorelist
- Don't use ignorelist file for sanitizers
- -fno-sanitize-memory-param-retval
- Disable detection of uninitialized parameters and return values
- -fno-sanitize-memory-track-origins
- Disable origins tracking in MemorySanitizer
- -fno-sanitize-memory-use-after-dtor
- Disable use-after-destroy detection in MemorySanitizer
- -fno-sanitize-merge=<value>
- Do not allow compiler to merge handlers for specified sanitizers
- -fno-sanitize-merge Do not allow compiler to merge handlers for any sanitizers
- -fno-sanitize-recover=<value>
- Disable recovery for specified sanitizers
- -fno-sanitize-stable-abi
- Conventional ABI instrumentation for sanitizer runtime. Default: Conventional
- -fno-sanitize-stats Disable sanitizer statistics gathering.
- -fno-sanitize-thread-atomics
- Disable atomic operations instrumentation in ThreadSanitizer
- -fno-sanitize-thread-func-entry-exit
- Disable function entry/exit instrumentation in ThreadSanitizer
- -fno-sanitize-thread-memory-access
- Disable memory access instrumentation in ThreadSanitizer
- -fno-sanitize-trap=<value>
- Disable trapping for specified sanitizers
- -fno-sanitize-trap Disable trapping for all sanitizers
- -fno-sanitize-type-outline-instrumentation
- Use code inlining logic for the type sanitizer
- -fno-standalone-debug Limit debug information produced to reduce size of debug binary
- -fno-strict-aliasing Disable optimizations based on strict aliasing rules
- -fno-sycl Disable SYCL C++ extensions
- -fno-temp-file Directly create compilation output files. This may lead to incorrect incremental builds if the compiler crashes
- -fno-verify-intermediate-code
- Disable verification of LLVM IR
- -fobjc-runtime=<value> Specify the target Objective-C runtime kind and version
- -foffload-implicit-host-device-templates
- Template functions or specializations without host, device and global attributes have implicit host device attributes (CUDA/HIP only)
- -foffload-lto=<value> Set LTO mode for offload compilation
- -foffload-lto Enable LTO in 'full' mode for offload compilation
- -foffload-via-llvm Use LLVM/Offload as portable offloading runtime.
- -fopenmp-target-jit Emit code that can be JIT compiled for OpenMP offloading. Implies -foffload-lto=full
- -fpch-instantiate-templates
- Instantiate templates already while building a PCH
- -fprebuilt-module-path=<directory>
- Specify the prebuilt module path
- -fprofile-exclude-files=<value>
- Instrument only functions from files where names don't match all the regexes separated by a semi-colon
- -fprofile-filter-files=<value>
- Instrument only functions from files where names match any regex separated by a semi-colon
- -fprofile-generate-cold-function-coverage=<directory>
- Generate instrumented code to collect coverage info for cold functions into <directory>/default.profraw (overridden by LLVM_PROFILE_FILE env var)
- -fprofile-generate-cold-function-coverage
- Generate instrumented code to collect coverage info for cold functions into default.profraw file (overridden by '=' form of option or LLVM_PROFILE_FILE env var)
- -fprofile-generate=<directory>
- Generate instrumented code to collect execution counts into <directory>/default.profraw (overridden by LLVM_PROFILE_FILE env var)
- -fprofile-generate Generate instrumented code to collect execution counts into default.profraw (overridden by LLVM_PROFILE_FILE env var)
- -fprofile-instr-generate=<file>
- Generate instrumented code to collect execution counts into <file> (overridden by LLVM_PROFILE_FILE env var)
- -fprofile-instr-generate
- Generate instrumented code to collect execution counts into default.profraw file (overridden by '=' form of option or LLVM_PROFILE_FILE env var)
- -fprofile-instr-use=<value>
- Use instrumentation data for profile-guided optimization
- -fprofile-list=<value> Filename defining the list of functions/files to instrument. The file uses the sanitizer special case list format.
- -fprofile-remapping-file=<file>
- Use the remappings described in <file> to match the profile data against names in the program
- -fprofile-sample-use=<value>
- Enable sample-based profile guided optimizations
- -fprofile-update=<method>
- Set update method of profile counters
- -fprofile-use=<pathname>
- Use instrumentation data for profile-guided optimization. If pathname is a directory, it reads from <pathname>/default.profdata. Otherwise, it reads from file <pathname>.
- -fprotect-parens Determines whether the optimizer honors parentheses when floating-point expressions are evaluated
- -fpseudo-probe-for-profiling
- Emit pseudo probes for sample profiling
- -frtlib-defaultlib On Windows, emit /defaultlib: directives to link compiler-rt libraries (default)
- -fsanitize-address-destructor=<value>
- Set the kind of module destructors emitted by AddressSanitizer instrumentation. These destructors are emitted to unregister instrumented global variables when code is unloaded (e.g. via `dlclose()`).
- -fsanitize-address-field-padding=<value>
- Level of field padding for AddressSanitizer
- -fsanitize-address-globals-dead-stripping
- Enable linker dead stripping of globals in AddressSanitizer
- -fsanitize-address-outline-instrumentation
- Always generate function calls for address sanitizer instrumentation
- -fsanitize-address-poison-custom-array-cookie
- Enable poisoning array cookies when using custom operator new[] in AddressSanitizer
- -fsanitize-address-use-after-return=<mode>
- Select the mode of detecting stack use-after-return in AddressSanitizer
- -fsanitize-address-use-after-scope
- Enable use-after-scope detection in AddressSanitizer
- -fsanitize-address-use-odr-indicator
- Enable ODR indicator globals to avoid false ODR violation reports in partially sanitized programs at the cost of an increase in binary size
- -fsanitize-alloc-token-extended
- Enable extended coverage to custom allocation functions
- -fsanitize-alloc-token-fast-abi
- Use the AllocToken fast ABI
- -fsanitize-annotate-debug-info=<value>
- Annotate sanitizer instrumentation with extra debug info for the specified sanitizers, if supported
- -fsanitize-annotate-debug-info
- Allow compiler to annotate sanitizer instrumentation with extra debug info for all sanitizers, where supported
- -fsanitize-cfi-canonical-jump-tables
- Make the jump table addresses canonical in the symbol table
- -fsanitize-cfi-cross-dso
- Enable control flow integrity (CFI) checks for cross-DSO calls.
- -fsanitize-cfi-icall-experimental-normalize-integers
- Normalize integers in CFI indirect call type signature checks
- -fsanitize-cfi-icall-generalize-pointers
- Generalize pointers in CFI indirect call type signature checks
- -fsanitize-coverage-allowlist=<value>
- Restrict sanitizer coverage instrumentation exclusively to modules and functions that match the provided special case list, except the blocked ones
- -fsanitize-coverage-ignorelist=<value>
- Disable sanitizer coverage instrumentation for modules and functions that match the provided special case list, even the allowed ones
- -fsanitize-coverage-stack-depth-callback-min=<M>
- Use callback for max stack depth tracing with minimum stack depth M
- -fsanitize-coverage=<value>
- Specify the type of coverage instrumentation for Sanitizers
- -fsanitize-debug-trap-reasons=<value>
- Set how trap reasons are emitted. `none` - Not emitted. This gives the smallest debug info; `basic` - Emit a fixed trap message per check type. This increases the debug info size but not as much as `detailed`; `detailed` - Emit a more detailed trap message. This increases the debug info size the most. Default is `detailed`.
- -fsanitize-debug-trap-reasons
- Alias for -fsanitize-debug-trap-reasons=detailed
- -fsanitize-handler-preserve-all-regs
- Enable handlers with preserve_all calling convention
- -fsanitize-hwaddress-abi=<value>
- Select the HWAddressSanitizer ABI to target (interceptor or platform, default interceptor). This option is currently unused.
- -fsanitize-hwaddress-experimental-aliasing
- Enable aliasing mode in HWAddressSanitizer
- -fsanitize-ignorelist=<value>
- Path to ignorelist file for sanitizers
- -fsanitize-kcfi-arity Embed function arity information into the KCFI patchable function prefix
- -fsanitize-kcfi-hash=<value>
- Select hash algorithm for KCFI type IDs (xxHash64, FNV-1a)
- -fsanitize-memory-param-retval
- Enable detection of uninitialized parameters and return values
- -fsanitize-memory-track-origins=<value>
- Enable origins tracking in MemorySanitizer
- -fsanitize-memory-track-origins
- Enable origins tracking in MemorySanitizer
- -fsanitize-memory-use-after-dtor
- Enable use-after-destroy detection in MemorySanitizer
- -fsanitize-memtag-mode=<value>
- Set default MTE mode to 'sync' (default) or 'async'
- -fsanitize-merge=<value>
- Allow compiler to merge handlers for specified sanitizers
- -fsanitize-merge Allow compiler to merge handlers for all sanitizers
- -fsanitize-recover=<value>
- Enable recovery for specified sanitizers
- -fsanitize-skip-hot-cutoff=<value>
- Exclude sanitization for the top hottest code responsible for the given fraction of PGO counters (0.0 [default] = skip none; 1.0 = skip all). Argument format: <sanitizer1>=<value1>,<sanitizer2>=<value2>,...
- -fsanitize-stable-abi Stable ABI instrumentation for sanitizer runtime. Default: Conventional
- -fsanitize-stats Enable sanitizer statistics gathering.
- -fsanitize-system-ignorelist=<value>
- Path to system ignorelist file for sanitizers
- -fsanitize-thread-atomics
- Enable atomic operations instrumentation in ThreadSanitizer (default)
- -fsanitize-thread-func-entry-exit
- Enable function entry/exit instrumentation in ThreadSanitizer (default)
- -fsanitize-thread-memory-access
- Enable memory access instrumentation in ThreadSanitizer (default)
- -fsanitize-trap=<value> Enable trapping for specified sanitizers
- -fsanitize-trap Enable trapping for all sanitizers
- -fsanitize-type-outline-instrumentation
- Always generate function calls for type sanitizer instrumentation
- -fsanitize-undefined-ignore-overflow-pattern=<value>
- Specify the overflow patterns to exclude from arithmetic sanitizer instrumentation
- -fsanitize-undefined-strip-path-components=<number>
- Strip (or keep only, if negative) a given number of path components when emitting check metadata.
- -fsanitize=<check> Turn on runtime checks for various forms of undefined or suspicious behavior. See user manual for available checks
- -fsplit-lto-unit Enables splitting of the LTO unit
- -fstandalone-debug Emit full debug info for all types used by the program
- -fstrict-aliasing Enable optimizations based on strict aliasing rules
- -fswift-async-fp=<option>
- Control emission of Swift async extended frame info
- -fsycl-device-only Compile SYCL code for device only
- -fsycl-host-only Compile SYCL code for host only. Has no effect on non-SYCL compilations
- -fsycl Enable SYCL C++ extensions
- -fsyntax-only Run the preprocessor, parser and semantic analysis stages
- -fsystem-module Build this module as a system module. Only used with -emit-module
- -ftemporal-profile Generate instrumented code to collect temporal information
- -fthin-link-bitcode=<value>
- Write minimized bitcode to <file> for the ThinLTO thin link only
- -fthinlto-distributor=<path>
- Path to the ThinLTO distributor process. If specified, ThinLTO backend compilations will be distributed by LLD
- -fthinlto-index=<value> Perform ThinLTO importing using provided function summary index
- -ftime-trace-granularity=<value>
- Minimum time granularity (in microseconds) traced by time profiler
- -ftime-trace-verbose<value>
- Make time trace capture verbose event details (e.g. source filenames). This can increase the size of the output by 2-3 times
- -ftime-trace=<value> Similar to -ftime-trace. Specify the JSON file or a directory which will contain the JSON file
- -ftime-trace Turn on time profiler. Generates JSON file based on output filename.
- -ftrivial-auto-var-init-max-size=<value>
- Stop initializing trivial automatic stack variables if var size exceeds the specified number of instances (in bytes)
- -ftrivial-auto-var-init-stop-after=<value>
- Stop initializing trivial automatic stack variables after the specified number of instances
- -ftrivial-auto-var-init=<value>
- Initialize trivial automatic stack variables. Defaults to 'uninitialized'
- -fuse-cuid=<value> Method to generate ID's for compilation units for single source offloading languages CUDA and HIP: 'hash' (ID's generated by hashing file path and command line options) | 'random' (ID's generated as random numbers) | 'none' (disabled). Default is 'hash'. This option will be overridden by option '-cuid=[ID]' if it is specified.
- -fverify-intermediate-code
- Enable verification of LLVM IR
- -fvirtual-function-elimination
- Enables dead virtual function elimination optimization. Requires -flto=full
- -fwhole-program-vtables Enables whole-program vtable optimization. Requires -flto
- -fwrapv-pointer Treat pointer overflow as two's complement
- -fwrapv Treat signed integer overflow as two's complement
- -gcodeview-command-line Emit compiler path and command line into CodeView debug information
- -gcodeview-ghash Emit type record hashes in a .debug$H section
- -gcodeview Generate CodeView debug information
- -gdwarf Generate source-level debug information with the default DWARF version
- -gen-reproducer=<value> Emit reproducer on (option: off, crash (default), error, always)
- -gkey-instructions Enable Key Instructions, which reduces the jumpiness of debug stepping in optimized C/C++ code in some debuggers. DWARF only.
- -gline-directives-only Emit debug line info directives only
- -gline-tables-only Emit debug line number tables only
- -gno-codeview-command-line
- Don't emit compiler path and command line into CodeView debug information
- -gno-inline-line-tables Don't emit inline line tables.
- --gpu-bundle-output Bundle output files of HIP device compilation
- --gpu-instrument-lib=<value>
- Instrument device library for HIP, which is a LLVM bitcode containing __cyg_profile_func_enter and __cyg_profile_func_exit
- --gpu-max-threads-per-block=<value>
- Default max threads per block for kernel launch bounds for HIP
- -gsplit-dwarf=<value> Set DWARF fission mode
- -gstrict-dwarf Restrict DWARF features to those defined in the specified version, avoiding features from later versions.
- -gstructor-decl-linkage-names
- Attach linkage names to C++ constructor/destructor declarations in DWARF.
- -G <size> Put objects of at most <size> bytes into small data section (MIPS / Hexagon)
- -g Generate source-level debug information
- --hip-device-lib=<value>
- HIP device library
- --hip-link Link clang-offload-bundler bundles for HIP
- --hip-path=<value> HIP runtime installation path, used for finding HIP version and adding HIP include path.
- --hip-version=<value> HIP version in the format of major.minor.patch
- --hipspv-pass-plugin=<dsopath>
- path to a pass plugin for HIP to SPIR-V passes.
- --hipstdpar-interpose-alloc
- Replace all memory allocation / deallocation calls with hipManagedMalloc / hipFree equivalents
- --hipstdpar-path=<value>
- HIP Standard Parallel Algorithm Acceleration library path, used for finding and implicitly including the library header
- --hipstdpar-prim-path=<value>
- rocPrim path, required by the HIP Standard Parallel Algorithm Acceleration library, used to implicitly include the rocPrim library
- --hipstdpar-thrust-path=<value>
- rocThrust path, required by the HIP Standard Parallel Algorithm Acceleration library, used to implicitly include the rocThrust library
- --hipstdpar Enable HIP acceleration for standard parallel algorithms
- -mabi=quadword-atomics Enable quadword atomics ABI on AIX (AIX PPC64 only). Uses lqarx/stqcx. instructions.
- -maix-struct-return Return all structs in memory (PPC32 only)
- -malign-branch-boundary=<value>
- Specify the boundary's size to align branches
- -malign-branch=<value> Specify types of branches to align
- -malign-double Align doubles to two words in structs (x86 only)
- -mamdgpu-expand-waitcnt-profiling
- Expand s_waitcnt instructions to help PC-sampling profilers identify memory stalls. Instead of a single waitcnt(target), emits waitcnt(N-1), waitcnt(N-2), ..., waitcnt(target). (AMDGPU only)
- -mamdgpu-ieee Sets the IEEE bit in the expected default floating point mode register. Floating point opcodes that support exception flag gathering quiet and propagate signaling NaN inputs per IEEE 754-2008. This option changes the ABI. (AMDGPU only)
- -mamdgpu-precise-memory-op
- Enable precise memory mode (AMDGPU only)
- -mannotate-tablejump Enable annotate table jump instruction to correlate it with the jump table.
- -mapx-features=<value> Enable features of APX
- -mapx-inline-asm-use-gpr32
- Enable use of GPR32 in inline assembly for APX
- -march=<value> For a list of available architectures for the target use '-mcpu=help'
- -marm64x<value> Link as a hybrid ARM64X image
- -mbackchain Link stack frames through backchain on System Z
- -mbranch-protection=<value>
- Enforce targets of indirect branches and function returns
- -mbranches-within-32B-boundaries
- Align selected branches (fused, jcc, jmp) within 32-byte boundary
- -mcf-branch-label-scheme=<value>
- Select label scheme for branch control-flow architecture protection
- -mcode-object-version=<value>
- Specify code object ABI version. Defaults to 6. (AMDGPU only)
- -mconstructor-aliases Enable emitting complete constructors and destructors as aliases when possible
- -mcpu=<value> For a list of available CPUs for the target use '-mcpu=help'
- -mcrc Allow use of CRC instructions (ARM/Mips only)
- -mdaz-ftz Globally set the denormals-are-zero (DAZ) and flush-to-zero (FTZ) bits in the floating-point control register on program startup
- -mdefault-visibility-export-mapping=<value>
- Mapping between default visibility and export
- -mdiv32 Use div.w[u] and mod.w[u] instructions with input not sign-extended.
- -mdouble=<n Force double to be <n> bits
- -meabi <value> Set EABI type. Default depends on triple)
- -menable-experimental-extensions
- Enable use of experimental RISC-V extensions.
- -mfentry Insert calls to fentry at function entry (x86/SystemZ only)
- -mfrecipe Enable frecipe.{s/d} and frsqrte.{s/d}
- -mfunction-return=<value>
- Replace returns with jumps to ``__x86_return_thunk`` (x86 only, error otherwise)
- -mgeneral-regs-only Generate code which only uses the general purpose registers (AArch64/x86 only)
- -mglobal-merge Enable merging of globals
- -mguard=<value> Enable or disable Control Flow Guard checks and guard tables emission
- -mharden-sls=<value> Select straight-line speculation hardening scope (ARM/AArch64/X86 only). <arg> must be: all, none, retbr(ARM/AArch64), blr(ARM/AArch64), comdat(ARM/AArch64), nocomdat(ARM/AArch64), return(X86), indirect-jmp(X86)
- -miamcu Use Intel MCU ABI
- -mignore-xcoff-visibility
- Not emit the visibility attribute for asm in AIX OS or give all symbols 'unspecified' visibility in XCOFF object file
- -mimplicit-float Generate implicit floating point or vector instructions
- -mincremental-linker-compatible
- (integrated-as) Emit an object file which can be used with an incremental linker
- -mindirect-branch-cs-prefix
- Add cs prefix to call and jmp to indirect thunk
- -mios-version-min=<value>
- Set iOS deployment target
- -mlam-bh Enable amswap[_db].{b/h} and amadd[_db].{b/h}
- -mlamcas Enable amcas[_db].{b/h/w/d}
- -mlasx Enable Loongson Advanced SIMD Extension (LASX).
- -mld-seq-sa Do not generate same-address load-load barrier instructions (dbar 0x700)
- -mlink-builtin-bitcode-postopt
- Link builtin bitcodes after the optimization pipeline
- -mllvm=<arg> Alias for -mllvm
- -mllvm <value> Additional arguments to forward to LLVM's option processing
- -mlong-calls Generate branches with extended addressability, usually via indirect jumps.
- -mlsx Enable Loongson SIMD Extension (LSX).
- -mlvi-cfi Enable only control-flow mitigations for Load Value Injection (LVI)
- -mlvi-hardening Enable all mitigations for Load Value Injection (LVI)
- -mmacos-version-min=<value>
- Set macOS deployment target
- -mms-bitfields Set the default structure layout to be compatible with the Microsoft compiler standard
- -mno-amdgpu-precise-memory-op
- Disable precise memory mode (AMDGPU only)
- -mno-annotate-tablejump Disable annotate table jump instruction to correlate it with the jump table.
- -mno-apx-features=<value>
- Disable features of APX
- -mno-constructor-aliases
- Disable emitting complete constructors and destructors as aliases when possible
- -mno-daz-ftz Do not globally set the denormals-are-zero (DAZ) and flush-to-zero (FTZ) bits in the floating-point control register on program startup
- -mno-div32 Do not use div.w[u] and mod.w[u] instructions with input not sign-extended.
- -mno-frecipe Disable frecipe.{s/d} and frsqrte.{s/d}
- -mno-gather Disable generation of gather instructions in auto-vectorization(x86 only)
- -mno-global-merge Disable merging of globals
- -mno-implicit-float Don't generate implicit floating point or vector instructions
- -mno-incremental-linker-compatible
- (integrated-as) Emit an object file which cannot be used with an incremental linker
- -mno-lam-bh Disable amswap[_db].{b/h} and amadd[_db].{b/h}
- -mno-lamcas Disable amcas[_db].{b/h/w/d}
- -mno-lasx Disable Loongson Advanced SIMD Extension (LASX).
- -mno-ld-seq-sa Generate same-address load-load barrier instructions (dbar 0x700)
- -mno-long-calls Restore the default behaviour of not generating long calls
- -mno-lsx Disable Loongson SIMD Extension (LSX).
- -mno-lvi-cfi Disable control-flow mitigations for Load Value Injection (LVI)
- -mno-lvi-hardening Disable mitigations for Load Value Injection (LVI)
- -mno-ms-bitfields Do not set the default structure layout to be compatible with the Microsoft compiler standard
- -mno-pic-data-is-text-relative
- Don't assume data segments are relative to text segment
- -mno-regnames Use only register numbers when writing assembly output
- -mno-relax Disable linker relaxation
- -mno-scalar-strict-align
- Allow scalar memory accesses to be unaligned (RISC-V only)
- -mno-scatter Disable generation of scatter instructions in auto-vectorization(x86 only)
- -mno-scq Disable sc.q instruction.
- -mno-seses Disable speculative execution side effect suppression (SESES)
- -mno-stack-arg-probe Disable stack probes which are enabled by default
- -mno-strict-align Allow memory accesses to be unaligned (AArch64/LoongArch/RISC-V only)
- -mno-tls-direct-seg-refs
- Disable direct TLS access through segment registers
- -mno-tocdata=<value> Specifies a list of variables to be exempt from the TOC data transformation.
- -mno-tocdata This is the default. TOC data transformation is not applied to any variables. Only variables specified explicitly in -mtocdata= will have the TOC data transformation.
- -mno-unaligned-access Force all memory accesses to be aligned (AArch32/MIPSr6 only)
- -mno-unaligned-symbols Expect external char-aligned symbols to be without ABI alignment (SystemZ only)
- -mno-vector-strict-align
- Allow vector memory accesses to be unaligned (RISC-V only)
- -mno-wavefrontsize64 Specify wavefront size 32 mode (AMDGPU only)
- -mnop-mcount Generate mcount/__fentry__ calls as nops. To activate they need to be patched in.
- -momit-leaf-frame-pointer
- Omit frame pointer setup for leaf functions
- -mpacked-stack Use packed stack layout (SystemZ only).
- -mpad-max-prefix-size=<value>
- Specify maximum number of prefixes to use for padding
- -mpic-data-is-text-relative
- Assume data segments are relative to text segment
- -mprefer-vector-width=<value>
- Specifies preferred vector width for auto-vectorization. Defaults to 'none' which allows target specific decisions.
- -mprintf-kind=<value> Specify the printf lowering scheme (AMDGPU only), allowed values are "hostcall"(printing happens during kernel execution, this scheme relies on hostcalls which require system to support pcie atomics) and "buffered"(printing happens after all kernel threads exit, this uses a printf buffer and does not rely on pcie atomic support)
- -mqdsp6-compat Enable hexagon-qdsp6 backward compatibility
- -mrecip=<value> Control use of approximate reciprocal and reciprocal square root instructions followed by <n> iterations of Newton-Raphson refinement. <value> = ( ['!'] ['vec-'] ('rcp'|'sqrt') [('h'|'s'|'d')] [':'<n>] ) | 'all' | 'default' | 'none'
- -mrecip Equivalent to '-mrecip=all'
- -mrecord-mcount Generate a __mcount_loc section entry for each __fentry__ call.
- -mregnames Use full register names when writing assembly output
- -mrelax-all (integrated-as) Relax all machine instructions
- -mrelax Enable linker relaxation
- -mreserve-frame-pointer-reg
- Reserve the frame pointer register even if the function doesn't have a frame
- -mrtd Make StdCall calling convention the default
- -mrvv-vector-bits=<value>
- Specify the size in bits of an RVV vector register
- -msave-reg-params Save arguments passed by registers to ABI-defined stack positions
- -mscalar-strict-align Force all scalar memory accesses to be aligned (RISC-V only)
- -mscq Enable sc.q instruction.
- -mseses Enable speculative execution side effect suppression (SESES). Includes LVI control flow integrity mitigations
- -msign-return-address=<value>
- Select return address signing scope
- -msimd=<value> Select the SIMD extension(s) to be enabled in LoongArch either 'none', 'lsx', 'lasx'.
- -mskip-rax-setup Skip setting up RAX register when passing variable arguments (x86 only)
- -msmall-data-limit=<value>
- Put global and static data smaller than the limit into a special section
- -msoft-float Use software floating point
- -msse2avx Specify that the assembler should encode SSE instructions with VEX prefix
- -mstack-alignment=<value>
- Set the stack alignment
- -mstack-arg-probe Enable stack probes
- -mstack-probe-size=<value>
- Set the stack probe size
- -mstack-protector-guard-offset=<value>
- Use the given offset for addressing the stack-protector guard
- -mstack-protector-guard-reg=<value>
- Use the given reg for addressing the stack-protector guard
- -mstack-protector-guard-symbol=<value>
- Use the given symbol for addressing the stack-protector guard
- -mstack-protector-guard=<value>
- Use the given guard (global, tls) for addressing the stack-protector guard
- -mstackrealign Force realign the stack at entry to every function
- -mstrict-align Force all memory accesses to be aligned (AArch64/LoongArch/RISC-V only)
- -msvr4-struct-return Return small structs in registers (PPC32 only)
- -mtargetos=<value> Set the deployment target to be the specified OS and OS version
- -mthread-model <value> The thread model to use. Defaults to 'posix')
- -mtls-dialect=<value> Which thread-local storage dialect to use for dynamic accesses of TLS variables
- -mtls-direct-seg-refs Enable direct TLS access through segment registers (default)
- -mtls-size=<value> Specify bit size of immediate TLS offsets (AArch64 ELF only): 12 (for 4KB) | 24 (for 16MB, default) | 32 (for 4GB) | 48 (for 256TB, needs -mcmodel=large)
- -mtocdata=<value> Specifies a list of variables to which the TOC data transformation will be applied.
- -mtocdata All suitable variables will have the TOC data transformation applied
- -mtune=<value> Only supported on AArch64, PowerPC, RISC-V, SPARC, SystemZ, and X86
- -munaligned-access Allow memory accesses to be unaligned (AArch32/MIPSr6 only)
- -munaligned-symbols Expect external char-aligned symbols to be without ABI alignment (SystemZ only)
- -mvector-strict-align Force all vector memory accesses to be aligned (RISC-V only)
- -mwavefrontsize64 Specify wavefront size 64 mode (AMDGPU only)
- -mxcoff-roptr Place constant objects with relocatable address values in the RO data section and add -bforceimprw to the linker flags (AIX only)
- -mzos-target=<value> Set the z/OS release of the runtime environment
- --no-cuda-include-ptx=<value>
- Do not include PTX for the following GPU architecture (e.g. sm_35) or 'all'. May be specified more than once.
- --no-cuda-version-check Don't error out if the detected version of the CUDA install is too low for the requested CUDA gpu architecture.
- --no-default-config Disable loading default configuration files
- --no-gpu-bundle-output Do not bundle output files of HIP device compilation
- -no-hip-rt Do not link against HIP runtime libraries
- --no-offload-arch=<value>
- Remove CUDA/HIP offloading device architecture (e.g. sm_35, gfx906) from the list of devices to compile for. 'all' resets the list to its default value.
- --no-offload-new-driver Don't Use the new driver for offloading compilation.
- --no-offloadlib Do not link device library for CUDA/HIP/SYCL device compilation
- --no-wasm-opt Disable the wasm-opt optimizer
- -nobuiltininc Disable builtin #include directories only
- -nostdinc Disable both standard system #include directories and builtin #include directories
- -object-file-name=<file>
- Set the output <file> for debug infos
- --offload-arch-tool=<value>
- Tool used for detecting offloading architectures in the system.
- --offload-arch=<value> Specify an offloading device architecture for CUDA, HIP, or OpenMP. (e.g. sm_35). If 'native' is used the compiler will detect locally installed architectures. For HIP offloading, the device architecture can be followed by target ID features delimited by a colon (e.g. gfx908:xnack+:sramecc-). May be specified more than once.
- --offload-compress Compress offload device binaries (HIP only)
- --offload-device-only Only compile for the offloading device.
- --offload-host-device Compile for both the offloading host and device (default).
- --offload-host-only Only compile for the offloading host.
- --offload-jobs=<value> Specify the number of threads to use for device offloading tasks during compilation. Can be a positive integer or the string 'jobserver' to use the make-style jobserver from the environment.
- --offload-new-driver Use the new driver for offloading compilation.
- --offload-targets=<value>
- Specify a list of target architectures to use for offloading.
- --offloadlib Link device libraries for GPU device compilation
- --precompile Only precompile the input
- -print-diagnostic-options
- Print all of Clang's warning options
- -print-effective-triple Print the effective target triple
- -print-enabled-extensions
- Print the extensions enabled by the given target and -march/-mcpu options. (AArch64 and RISC-V only)
- -print-file-name=<file> Print the full library path of <file>
- -print-libgcc-file-name Print the library path for the currently used compiler runtime library ("libgcc.a" or "libclang_rt.builtins.*.a")
- -print-library-module-manifest-path
- Print the path for the C++ Standard library module manifest
- -print-prog-name=<name> Print the full program path of <name>
- -print-resource-dir Print the resource directory pathname
- -print-rocm-search-dirs Print the paths used for finding ROCm installation
- -print-runtime-dir Print the directory pathname containing Clang's runtime libraries
- -print-search-dirs Print the paths used for finding libraries and programs
- -print-supported-cpus Print supported cpu models for the given target (if target is not specified,it will print the supported cpus for the default target)
- -print-supported-extensions
- Print supported -march extensions (RISC-V, AArch64 and ARM only)
- -print-target-triple Print the normalized target triple
- -print-targets Print the registered targets
- --ptxas-path=<value> Path to ptxas (used for compiling CUDA code)
- -Qunused-arguments Don't emit warning for unused driver arguments
- -regcall4 Set __regcall4 as a default calling convention to respect __regcall ABI v.4
- -resource-dir <value> The directory which holds the compiler resource files
- --rocm-device-lib-path=<value>
- ROCm device library path. Alternative to rocm-path.
- --rocm-path=<value> ROCm installation path, used for finding and automatically linking required bitcode libraries.
- -rtlib=<value> Compiler runtime library to use
- --start-no-unused-arguments
- Don't emit warnings about unused arguments for the following arguments
- -sycl-std=<value> SYCL language standard to compile for.
- --target=<value> Generate code for the given target
- --version Print version information
- -vfsoverlay <value> Overlay the virtual filesystem described by file over the real file system. Additionally, pass this overlay file to the linker if it supports it
- /volatile:iso Volatile loads and stores have standard semantics
- /volatile:ms Volatile loads and stores have acquire and release semantics
- -v Show commands to run and use verbose output
- --warning-suppression-mappings=<value>
- File containing diagnostic suppression mappings. See user manual for file format.
- --wasm-opt Enable the wasm-opt optimizer (default)
- -W<warning> Enable the specified warning
- -Xclang=<arg> Alias for -Xclang
- -Xclangas=<arg> Alias for -Xclangas
- -Xclangas <arg> Pass <arg> to clang -cc1as
- -Xclang <arg> Pass <arg> to clang -cc1
- -Xcuda-ptxas <arg> Pass <arg> to the ptxas assembler
- -Xflang <arg> Pass <arg> to the flang compiler
- -Xlinker <arg> Pass <arg> to the linker
- -Xthinlto-distributor=<arg>
- Pass <arg> to the ThinLTO distributor process. Can be specified multiple times or with comma-separated values.
- -x <language> Treat subsequent input files as having type <language>
-
-The /clang: Option
-^^^^^^^^^^^^^^^^^^
-
-When clang-cl is run with a set of ``/clang:<arg>`` options, it will gather all
-of the ``<arg>`` arguments and process them as if they were passed to the clang
+Execute `clang-cl /?` to see a list of supported options:
+
+> ```
+> CL.EXE COMPATIBILITY OPTIONS:
+> /? Display available options
+> /arch:<value> Set architecture for code generation
+> /arm64EC Set build target to arm64ec
+> /Brepro- Write current time into COFF output (default)
+> /Brepro Do not write current time into COFF output (breaks link.exe /incremental)
+> /clang:<arg> Pass <arg> to the clang driver
+> /C Do not discard comments when preprocessing
+> /c Compile only
+> /d1PP Retain macro definitions in /E mode
+> /d1reportAllClassLayout Dump record layout information
+> /d2epilogunwindrequirev2
+> Require generation of unwind v2 (epilog) information for x64 Windows
+> /d2epilogunwind Best effort generate unwind v2 (epilog) information for x64 Windows
+> /diagnostics:caret Enable caret and column diagnostics (default)
+> /diagnostics:classic Disable column and caret diagnostics
+> /diagnostics:column Disable caret diagnostics but keep column info
+> /diasdkdir <dir> Path to the DIA SDK
+> /D <macro[=value]> Define macro
+> /EH<value> Set exception handling model
+> /EP Disable linemarker output and preprocess to stdout
+> /execution-charset:<value>
+> Set runtime encoding, supports only UTF-8
+> /external:env:<var> Add dirs in env var <var> to include search path with warnings suppressed
+> /external:I <dir> Add directory to include search path with warnings suppressed
+> /external:W0 Ignore warnings from system headers (default)
+> /external:W1 Enable -Wsystem-headers
+> /external:W2 Enable -Wsystem-headers
+> /external:W3 Enable -Wsystem-headers
+> /external:W4 Enable -Wsystem-headers
+> /E Preprocess to stdout
+> /FA<value> Output assembly code file during compilation
+> /Fa<file or dir/> Set assembly output file name (with /FA)
+> /Fe<file or dir/> Set output executable file name
+> /FI <value> Include file before parsing
+> /Fi<file> Set preprocess output file name (with /P)
+> /Fo<file or dir/> Set output object file (with /c)
+> /Fp<file> Set pch file name (with /Yc and /Yu)
+> /fsanitize=address Enable AddressSanitizer
+> /funcoverride:<function>
+> Mark <function> as being replaceable by the Windows kernel loader
+> /GA Assume thread-local variables are defined in the executable
+> /Gd Set __cdecl as a default calling convention
+> /GF- Disable string pooling
+> /GF Enable string pooling (default)
+> /GR- Do not emit RTTI data
+> /Gregcall4 Set __regcall4 as a default calling convention to respect __regcall ABI v.4
+> /Gregcall Set __regcall as a default calling convention
+> /GR Emit RTTI data (default)
+> /Gr Set __fastcall as a default calling convention
+> /GS- Disable buffer security check
+> /GS Enable buffer security check (default)
+> /Gs Use stack probes (default)
+> /Gs<value> Set stack probe size (default 4096)
+> /guard:<value> Enable Control Flow Guard with /guard:cf, or only the table with /guard:cf,nochecks. Enable EH Continuation Guard with /guard:ehcont
+> /Gv Set __vectorcall as a default calling convention
+> /Gw- Do not put each data item in its own section (default)
+> /Gw Put each data item in its own section
+> /GX- Deprecated (like not passing /EH)
+> /GX Deprecated; use /EHsc
+> /Gy- Do not put each function in its own section (default)
+> /Gy Put each function in its own section
+> /Gz Set __stdcall as a default calling convention
+> /help Display available options
+> /hotpatch Create hotpatchable image
+> /imsvc <dir> Add <dir> to system include search path, as if in %INCLUDE%
+> /I <dir> Add directory to include search path
+> /JMC- Disable just-my-code debugging (default)
+> /JMC Enable just-my-code debugging
+> /J Make char type unsigned
+> /LDd Create debug DLL
+> /LD Create DLL
+> /link <options> Forward options to the linker
+> /MDd Use DLL debug run-time
+> /MD Use DLL run-time
+> /MTd Use static debug run-time
+> /MT Use static run-time
+> /O1 Optimize for size (like /Og /Os /Oy /Ob2 /GF /Gy)
+> /O2 Optimize for speed (like /Og /Oi /Ot /Oy /Ob2 /GF /Gy)
+> /Ob0 Disable function inlining
+> /Ob1 Only inline functions explicitly or implicitly marked inline
+> /Ob2 Inline functions as deemed beneficial by the compiler
+> /Ob3 Same as /Ob2
+> /Od Disable optimization
+> /Og No effect
+> /Oi- Disable use of builtin functions
+> /Oi Enable use of builtin functions
+> /openmp- Disable OpenMP support
+> /openmp:experimental Enable OpenMP support with experimental SIMD support
+> /openmp Enable OpenMP support
+> /Os Optimize for size (like clang -Os)
+> /Ot Optimize for speed (like clang -O3)
+> /Ox Deprecated (like /Og /Oi /Ot /Oy /Ob2); use /O2
+> /Oy- Disable frame pointer omission (x86 only, default)
+> /Oy Enable frame pointer omission (x86 only)
+> /O<flags> Set multiple /O flags at once; e.g. '/O2y-' for '/O2 /Oy-'
+> /o <file or dir/> Deprecated (set output file name); use /Fe or /Fe
+> /permissive- Disable non conforming code from compiling (default)
+> /permissive Enable some non conforming code to compile
+> /P Preprocess to file
+> /Qgather- Disable generation of gather instructions in auto-vectorization(x86 only)
+> /QIntel-jcc-erratum Align branches within 32-byte boundaries to mitigate the performance impact of the Intel JCC erratum.
+> /Qscatter- Disable generation of scatter instructions in auto-vectorization(x86 only)
+> /Qvec- Disable the loop vectorization passes
+> /Qvec Enable the loop vectorization passes
+> /showFilenames- Do not print the name of each compiled file (default)
+> /showFilenames Print the name of each compiled file
+> /showIncludes:user Like /showIncludes but omit system headers
+> /showIncludes Print info about included files to stderr
+> /source-charset:<value> Set source encoding, supports only UTF-8
+> /std:<value> Set language version (c++14,c++17,c++20,c++23preview,c++26preview,c++latest,c11,c17)
+> /TC Treat all source files as C
+> /Tc <file> Treat <file> as C source file
+> /TP Treat all source files as C++
+> /Tp <file> Treat <file> as C++ source file
+> /tune:<value> Set CPU for optimization without affecting instruction set
+> /utf-8 Set source and runtime encoding to UTF-8 (default)
+> /U <macro> Undefine macro
+> /vctoolsdir <dir> Path to the VCToolChain
+> /vctoolsversion <value> For use with /winsysroot, defaults to newest found
+> /vd<value> Control vtordisp placement
+> /vlen=256 Set vector length of 256 bits for autovectorization and other optimizations
+> /vlen=512 Set vector length of 512 bits for autovectorization and other optimizations
+> /vlen Set default vector length for autovectorization and other optimizations
+> /vmb Use a best-case representation method for member pointers
+> /vmg Use a most-general representation for member pointers
+> /vmm Set the default most-general representation to multiple inheritance
+> /vms Set the default most-general representation to single inheritance
+> /vmv Set the default most-general representation to virtual inheritance
+> /W0 Disable all warnings
+> /W1 Enable -Wall
+> /W2 Enable -Wall
+> /W3 Enable -Wall
+> /W4 Enable -Wall and -Wextra
+> /Wall Enable -Weverything
+> /winsdkdir <dir> Path to the Windows SDK
+> /winsdkversion <value> Full version of the Windows SDK, defaults to newest found
+> /winsysroot <dir> Same as "/diasdkdir <dir>/DIA SDK" /vctoolsdir <dir>/VC/Tools/MSVC/<vctoolsversion> "/winsdkdir <dir>/Windows Kits/10"
+> /WX- Do not treat warnings as errors (default)
+> /WX Treat warnings as errors
+> /w Disable all warnings
+> /X Do not add %INCLUDE% to include search path
+> /Y- Disable precompiled headers, overrides /Yc and /Yu
+> /Yc<filename> Generate a pch file for all code up to and including <filename>
+> /Yu<filename> Load a pch file and use it instead of all code up to and including <filename>
+> /Z7 Enable CodeView debug information in object files
+> /Zc:__STDC__ Define __STDC__
+> /Zc:alignedNew- Disable C++17 aligned allocation functions
+> /Zc:alignedNew Enable C++17 aligned allocation functions
+> /Zc:char8_t- Disable char8_t from c++2a
+> /Zc:char8_t Enable char8_t from C++2a
+> /Zc:dllexportInlines- Do not dllexport/dllimport inline member functions of dllexport/import classes
+> /Zc:dllexportInlines dllexport/dllimport inline member functions of dllexport/import classes (default)
+> /Zc:sizedDealloc- Disable C++14 sized global deallocation functions
+> /Zc:sizedDealloc Enable C++14 sized global deallocation functions
+> /Zc:strictStrings Treat string literals as const
+> /Zc:threadSafeInit- Disable thread-safe initialization of static variables
+> /Zc:threadSafeInit Enable thread-safe initialization of static variables
+> /Zc:tlsGuards- Disable on-demand initialization of thread-local variables
+> /Zc:tlsGuards Enable on-demand initialization of thread-local variables
+> /Zc:trigraphs- Disable trigraphs (default)
+> /Zc:trigraphs Enable trigraphs
+> /Zc:twoPhase- Disable two-phase name lookup in templates (default)
+> /Zc:twoPhase Enable two-phase name lookup in templates
+> /Zc:wchar_t- Disable C++ builtin type wchar_t
+> /Zc:wchar_t Enable C++ builtin type wchar_t (default)
+> /ZH:MD5 Use MD5 for file checksums in debug info (default)
+> /ZH:SHA1 Use SHA1 for file checksums in debug info
+> /ZH:SHA_256 Use SHA256 for file checksums in debug info
+> /Zi Like /Z7
+> /Zl Do not let object file auto-link default libraries
+> /Zp Set default maximum struct packing alignment to 1
+> /Zp<value> Set default maximum struct packing alignment
+> /Zs Run the preprocessor, parser and semantic analysis stages
+>
+> OPTIONS:
+> -### Print (but do not run) the commands to run for this compilation
+> --analyze Run the static analyzer
+> --config=<file> Specify configuration file
+> --cuda-compile-host-device
+> Compile CUDA code for both host and device (default). Has no effect on non-CUDA compilations.
+> --cuda-device-only Compile CUDA code for device only
+> --cuda-feature=<value> Manually specify the CUDA feature to use
+> --cuda-host-only Compile CUDA code for host only. Has no effect on non-CUDA compilations.
+> --cuda-include-ptx=<value>
+> Include PTX for the following GPU architecture (e.g. sm_35) or 'all'. May be specified more than once.
+> --cuda-noopt-device-debug
+> Enable device-side debug info generation. Disables ptxas optimizations.
+> --cuda-path-ignore-env Ignore environment variables to detect CUDA installation
+> --cuda-path=<value> CUDA installation path
+> -cuid=<value> An ID for compilation unit, which should be the same for the same compilation unit but different for different compilation units. It is used to externalize device-side static variables for single source offloading languages CUDA and HIP so that they can be accessed by the host code of the same compilation unit.
+> -darwin-target-variant <value>
+> Generate code for an additional runtime variant of the deployment target
+> -emit-ast Emit Clang AST files for source inputs
+> --end-no-unused-arguments
+> Start emitting warnings for unused driver arguments
+> -faddrsig Emit an address-significance table
+> -fansi-escape-codes Use ANSI escape codes for diagnostics
+> -fblocks Enable the 'blocks' language feature
+> -fcaret-diagnostics-max-lines=<value>
+> Set the maximum number of source lines to show in a caret diagnostic (0 = no limit).
+> -fcf-protection=<value> Instrument control-flow architecture protection
+> -fcf-protection Enable cf-protection in 'full' mode
+> -fcodegen-data-generate=<path>
+> Emit codegen data into the object file. LLD for MachO (currently) merges them into the specified <path>.
+> -fcodegen-data-generate Emit codegen data into the object file. LLD for MachO (currently) merges them into default.cgdata.
+> -fcodegen-data-use=<path>
+> Use codegen data read from the specified <path>.
+> -fcodegen-data-use Use codegen data read from default.cgdata to optimize the binary
+> -fcolor-diagnostics Enable colors in diagnostics
+> -fcommon Place uninitialized global variables in a common block
+> -fcomplete-member-pointers
+> Require member pointer base types to be complete if they would be significant under the Microsoft ABI
+> -fcoverage-compilation-dir=<value>
+> The compilation directory to embed in the coverage mapping.
+> -fcoverage-mapping Generate coverage mapping to enable code coverage analysis
+> -fcoverage-mcdc Enable MC/DC criteria when generating code coverage
+> -fcrash-diagnostics-dir=<dir>
+> Put crash-report files in <dir>
+> -fcrash-diagnostics=<value>
+> Set level of crash diagnostic reporting, (option: off, compiler, all)
+> -fcrash-diagnostics Enable crash diagnostic reporting (default)
+> -fcs-profile-generate=<directory>
+> Generate instrumented code to collect context sensitive execution counts into <directory>/default.profraw (overridden by LLVM_PROFILE_FILE env var)
+> -fcs-profile-generate Generate instrumented code to collect context sensitive execution counts into default.profraw (overridden by LLVM_PROFILE_FILE env var)
+> -fcuda-short-ptr Use 32-bit pointers for accessing const/local/shared address spaces
+> -fdebug-compilation-dir=<value>
+> The compilation directory to embed in the debug info
+> -fdebug-macro Emit macro debug information
+> -fdelayed-template-parsing
+> Parse templated function definitions at the end of the translation unit
+> -fdelete-null-pointer-checks
+> Treat usage of null pointers as undefined behavior (default)
+> -fdevirtualize-speculatively
+> Enables speculative devirtualization optimization.
+> -fdiagnostics-absolute-paths
+> Print absolute paths in diagnostics
+> -fdiagnostics-color=<value>
+> When to use colors in diagnostics
+> -fdiagnostics-parseable-fixits
+> Print fix-its in machine parseable form
+> -fdriver-only Only run the driver.
+> -feliminate-unused-debug-types
+> Do not emit debug info for defined but unused types
+> -fexcess-precision=<value>
+> Allows control over excess precision on targets where native support for the precision types is not available. By default, excess precision is used to calculate intermediate results following the rules specified in ISO C99.
+> -fexperimental-library Control whether unstable and experimental library features are enabled. This option enables various library features that are either experimental (also known as TSes), or have been but are not stable yet in the selected Standard Library implementation. It is not recommended to use this option in production code, since neither ABI nor API stability are guaranteed. This is intended to provide a preview of features that will ship in the future for experimentation purposes
+> -fexperimental-sanitize-metadata-ignorelist=<value>
+> Disable sanitizer metadata for modules and functions that match the provided special case list
+> -fexperimental-sanitize-metadata=<value>
+> Specify the type of metadata to emit for binary analysis sanitizers
+> -ffile-compilation-dir=<value>
+> The compilation directory to embed in the debug info and coverage mapping.
+> -ffile-reproducible Use the target's platform-specific path separator character when expanding the __FILE__ macro
+> -ffixed-x10 Reserve the x10 register (AArch64/RISC-V only)
+> -ffixed-x11 Reserve the x11 register (AArch64/RISC-V only)
+> -ffixed-x12 Reserve the x12 register (AArch64/RISC-V only)
+> -ffixed-x13 Reserve the x13 register (AArch64/RISC-V only)
+> -ffixed-x14 Reserve the x14 register (AArch64/RISC-V only)
+> -ffixed-x15 Reserve the x15 register (AArch64/RISC-V only)
+> -ffixed-x16 Reserve the x16 register (AArch64/RISC-V only)
+> -ffixed-x17 Reserve the x17 register (AArch64/RISC-V only)
+> -ffixed-x18 Reserve the x18 register (AArch64/RISC-V only)
+> -ffixed-x19 Reserve the x19 register (AArch64/RISC-V only)
+> -ffixed-x1 Reserve the x1 register (AArch64/RISC-V only)
+> -ffixed-x20 Reserve the x20 register (AArch64/RISC-V only)
+> -ffixed-x21 Reserve the x21 register (AArch64/RISC-V only)
+> -ffixed-x22 Reserve the x22 register (AArch64/RISC-V only)
+> -ffixed-x23 Reserve the x23 register (AArch64/RISC-V only)
+> -ffixed-x24 Reserve the x24 register (AArch64/RISC-V only)
+> -ffixed-x25 Reserve the x25 register (AArch64/RISC-V only)
+> -ffixed-x26 Reserve the x26 register (AArch64/RISC-V only)
+> -ffixed-x27 Reserve the x27 register (AArch64/RISC-V only)
+> -ffixed-x28 Reserve the x28 register (AArch64/RISC-V only)
+> -ffixed-x29 Reserve the x29 register (AArch64/RISC-V only)
+> -ffixed-x2 Reserve the x2 register (AArch64/RISC-V only)
+> -ffixed-x30 Reserve the x30 register (AArch64/RISC-V only)
+> -ffixed-x31 Reserve the x31 register (AArch64/RISC-V only)
+> -ffixed-x3 Reserve the x3 register (AArch64/RISC-V only)
+> -ffixed-x4 Reserve the x4 register (AArch64/RISC-V only)
+> -ffixed-x5 Reserve the x5 register (AArch64/RISC-V only)
+> -ffixed-x6 Reserve the x6 register (AArch64/RISC-V only)
+> -ffixed-x7 Reserve the x7 register (AArch64/RISC-V only)
+> -ffixed-x8 Reserve the x8 register (AArch64/RISC-V only)
+> -ffixed-x9 Reserve the x9 register (AArch64/RISC-V only)
+> -fforce-emit-vtables Emits more virtual tables to improve devirtualization
+> -ffuchsia-api-level=<value>
+> Set Fuchsia API level
+> -fgnuc-version=<value> Sets various macros to claim compatibility with the given GCC version (default is 4.2.1)
+> -fgpu-allow-device-init Allow device side init function in HIP (experimental)
+> -fgpu-default-stream=<value>
+> Specify default stream. The default value is 'legacy'. (CUDA/HIP only)
+> -fgpu-defer-diag Defer host/device related diagnostic messages for CUDA/HIP
+> -fgpu-flush-denormals-to-zero
+> Flush denormal floating point values to zero in CUDA/HIP device mode.
+> -fgpu-rdc Generate relocatable device code, also known as separate compilation mode
+> -fgpu-sanitize Enable sanitizer for supported offloading devices
+> -fhip-emit-relocatable Compile HIP source to relocatable
+> -fhip-fp32-correctly-rounded-divide-sqrt
+> Specify that single precision floating-point divide and sqrt used in the program source are correctly rounded (HIP device compilation only)
+> -fhip-kernel-arg-name Specify that kernel argument names are preserved (HIP only)
+> -fhip-new-launch-api Use new kernel launching API for HIP
+> -fimplicit-module-maps Implicitly search the file system for module map files.
+> -finline-max-stacksize=<value>
+> Suppress inlining of functions whose stack size exceeds the given value
+> -fintegrated-cc1 Run cc1 in-process
+> -fintegrated-objemitter Use internal machine object code emitter.
+> -flto=<value> Set LTO mode
+> -flto Enable LTO in 'full' mode
+> -fmacro-backtrace-limit=<value>
+> Set the maximum number of entries to print in a macro expansion backtrace (0 = no limit)
+> -fmemory-profile-use=<pathname>
+> Use memory profile for profile-guided memory optimization
+> -fmerge-all-constants Allow merging of constants
+> -fmodule-file=[<name>=]<file>
+> Specify the mapping of module name to precompiled module file, or load a module file if name is omitted.
+> -fmodule-header=<kind> Build a C++20 Header Unit from a header that should be found in the user (fmodule-header=user) or system (fmodule-header=system) search path.
+> -fmodule-header Build a C++20 Header Unit from a header
+> -fmodule-map-file=<file>
+> Load this module map file
+> -fmodule-name=<name> Specify the name of the module to build
+> -fmodule-output=<value> Save intermediate module file results when compiling a standard C++ module unit.
+> -fmodule-output Save intermediate module file results when compiling a standard C++ module unit.
+> -fmodules-decluse Require declaration of modules used within a module
+> -fmodules-embed-all-files<value>
+> Embed the contents of all files read by this compilation into the produced module file.
+> -fmodules-ignore-macro=<value>
+> Ignore the definition of the given macro when building and loading modules
+> -fmodules-search-all Search even non-imported modules to resolve references
+> -fmodules-strict-decluse
+> Like -fmodules-decluse but requires all headers to be in modules
+> -fmodules Enable the 'modules' language feature
+> -fms-compatibility-version=<value>
+> Dot-separated value representing the Microsoft compiler version number to report in _MSC_VER (0 = don't define it (default))
+> -fms-compatibility Enable full Microsoft Visual C++ compatibility
+> -fms-define-stdc Define '__STDC__' to '1' in MSVC Compatibility mode
+> -fms-extensions Accept some non-standard constructs supported by the Microsoft compiler
+> -fms-hotpatch Ensure that all functions can be hotpatched at runtime
+> -fms-runtime-lib=<value>
+> Select Windows run-time library
+> -fms-secure-hotpatch-functions-file=<value>
+> Path to a file that contains a list of mangled names of functions that should be hot-patched for Windows Secure Hot-Patching
+> -fms-secure-hotpatch-functions-list=<value>
+> List of mangled symbol names of functions that should be hot-patched for Windows Secure Hot-Patching
+> -fmsc-version=<value> Microsoft compiler version number to report in _MSC_VER (0 = don't define it (default))
+> -fno-addrsig Don't emit an address-significance table
+> -fno-assume-unique-vtables
+> Disable optimizations based on vtable pointer identity
+> -fno-builtin-<value> Disable implicit builtin knowledge of a specific function
+> -fno-builtin Disable implicit builtin knowledge of functions
+> -fno-color-diagnostics Disable colors in diagnostics
+> -fno-complete-member-pointers
+> Do not require member pointer base types to be complete if they would be significant under the Microsoft ABI
+> -fno-coverage-mapping Disable code coverage analysis
+> -fno-coverage-mcdc Disable MC/DC coverage criteria
+> -fno-crash-diagnostics Disable auto-generation of preprocessed source files and a script for reproduction during a clang crash
+> -fno-debug-macro Do not emit macro debug information
+> -fno-delayed-template-parsing
+> Disable delayed template parsing
+> -fno-delete-null-pointer-checks
+> Do not treat usage of null pointers as undefined behavior
+> -fno-eliminate-unused-debug-types
+> Emit debug info for defined but unused types
+> -fno-experimental-sanitize-metadata=<value>
+> Disable emitting metadata for binary analysis sanitizers
+> -fno-file-reproducible Use the host's platform-specific path separator character when expanding the __FILE__ macro
+> -fno-gpu-allow-device-init
+> Don't allow device side init function in HIP (experimental)
+> -fno-gpu-defer-diag Don't defer host/device related diagnostic messages for CUDA/HIP
+> -fno-hip-emit-relocatable
+> Do not override toolchain to compile HIP source to relocatable
+> -fno-hip-fp32-correctly-rounded-divide-sqrt
+> Don't specify that single precision floating-point divide and sqrt used in the program source are correctly rounded (HIP device compilation only)
+> -fno-hip-kernel-arg-name
+> Don't specify that kernel argument names are preserved (HIP only)
+> -fno-hip-new-launch-api Don't use new kernel launching API for HIP
+> -fno-integrated-cc1 Spawn a separate process for each cc1
+> -fno-integrated-objemitter
+> Use external machine object code emitter.
+> -fno-knr-functions Disable support for K&R C function declarations
+> -fno-lto Disable LTO mode (default)
+> -fno-offload-lto Disable LTO mode (default) for offload compilation
+> -fno-offload-via-llvm Don't use LLVM/Offload as portable offloading runtime.
+> -fno-profile-generate Disable generation of profile instrumentation.
+> -fno-profile-instr-generate
+> Disable generation of profile instrumentation.
+> -fno-profile-instr-use Disable using instrumentation data for profile-guided optimization
+> -fno-pseudo-probe-for-profiling
+> Do not emit pseudo probes for sample profiling
+> -fno-rtlib-defaultlib On Windows, do not emit /defaultlib: directives to link compiler-rt libraries
+> -fno-sanitize-address-globals-dead-stripping
+> Disable linker dead stripping of globals in AddressSanitizer
+> -fno-sanitize-address-outline-instrumentation
+> Use default code inlining logic for the address sanitizer
+> -fno-sanitize-address-poison-custom-array-cookie
+> Disable poisoning array cookies when using custom operator new[] in AddressSanitizer
+> -fno-sanitize-address-use-after-scope
+> Disable use-after-scope detection in AddressSanitizer
+> -fno-sanitize-address-use-odr-indicator
+> Disable ODR indicator globals
+> -fno-sanitize-alloc-token-extended
+> Disable extended coverage to custom allocation functions
+> -fno-sanitize-alloc-token-fast-abi
+> Use the default AllocToken ABI
+> -fno-sanitize-annotate-debug-info=<value>
+> Do not allow compiler to annotate sanitizer instrumentation with extra debug info for the specified sanitizers
+> -fno-sanitize-annotate-debug-info
+> Do not allow compiler to annotate sanitizer instrumentation with extra debug info for any sanitizers
+> -fno-sanitize-cfi-canonical-jump-tables
+> Do not make the jump table addresses canonical in the symbol table
+> -fno-sanitize-cfi-cross-dso
+> Disable control flow integrity (CFI) checks for cross-DSO calls.
+> -fno-sanitize-coverage=<value>
+> Disable features of coverage instrumentation for Sanitizers
+> -fno-sanitize-debug-trap-reasons
+> Alias for -fsanitize-debug-trap-reasons=none
+> -fno-sanitize-handler-preserve-all-regs
+> Disable handlers with preserve_all calling convention
+> -fno-sanitize-hwaddress-experimental-aliasing
+> Disable aliasing mode in HWAddressSanitizer
+> -fno-sanitize-ignorelist
+> Don't use ignorelist file for sanitizers
+> -fno-sanitize-memory-param-retval
+> Disable detection of uninitialized parameters and return values
+> -fno-sanitize-memory-track-origins
+> Disable origins tracking in MemorySanitizer
+> -fno-sanitize-memory-use-after-dtor
+> Disable use-after-destroy detection in MemorySanitizer
+> -fno-sanitize-merge=<value>
+> Do not allow compiler to merge handlers for specified sanitizers
+> -fno-sanitize-merge Do not allow compiler to merge handlers for any sanitizers
+> -fno-sanitize-recover=<value>
+> Disable recovery for specified sanitizers
+> -fno-sanitize-stable-abi
+> Conventional ABI instrumentation for sanitizer runtime. Default: Conventional
+> -fno-sanitize-stats Disable sanitizer statistics gathering.
+> -fno-sanitize-thread-atomics
+> Disable atomic operations instrumentation in ThreadSanitizer
+> -fno-sanitize-thread-func-entry-exit
+> Disable function entry/exit instrumentation in ThreadSanitizer
+> -fno-sanitize-thread-memory-access
+> Disable memory access instrumentation in ThreadSanitizer
+> -fno-sanitize-trap=<value>
+> Disable trapping for specified sanitizers
+> -fno-sanitize-trap Disable trapping for all sanitizers
+> -fno-sanitize-type-outline-instrumentation
+> Use code inlining logic for the type sanitizer
+> -fno-standalone-debug Limit debug information produced to reduce size of debug binary
+> -fno-strict-aliasing Disable optimizations based on strict aliasing rules
+> -fno-sycl Disable SYCL C++ extensions
+> -fno-temp-file Directly create compilation output files. This may lead to incorrect incremental builds if the compiler crashes
+> -fno-verify-intermediate-code
+> Disable verification of LLVM IR
+> -fobjc-runtime=<value> Specify the target Objective-C runtime kind and version
+> -foffload-implicit-host-device-templates
+> Template functions or specializations without host, device and global attributes have implicit host device attributes (CUDA/HIP only)
+> -foffload-lto=<value> Set LTO mode for offload compilation
+> -foffload-lto Enable LTO in 'full' mode for offload compilation
+> -foffload-via-llvm Use LLVM/Offload as portable offloading runtime.
+> -fopenmp-target-jit Emit code that can be JIT compiled for OpenMP offloading. Implies -foffload-lto=full
+> -fpch-instantiate-templates
+> Instantiate templates already while building a PCH
+> -fprebuilt-module-path=<directory>
+> Specify the prebuilt module path
+> -fprofile-exclude-files=<value>
+> Instrument only functions from files where names don't match all the regexes separated by a semi-colon
+> -fprofile-filter-files=<value>
+> Instrument only functions from files where names match any regex separated by a semi-colon
+> -fprofile-generate-cold-function-coverage=<directory>
+> Generate instrumented code to collect coverage info for cold functions into <directory>/default.profraw (overridden by LLVM_PROFILE_FILE env var)
+> -fprofile-generate-cold-function-coverage
+> Generate instrumented code to collect coverage info for cold functions into default.profraw file (overridden by '=' form of option or LLVM_PROFILE_FILE env var)
+> -fprofile-generate=<directory>
+> Generate instrumented code to collect execution counts into <directory>/default.profraw (overridden by LLVM_PROFILE_FILE env var)
+> -fprofile-generate Generate instrumented code to collect execution counts into default.profraw (overridden by LLVM_PROFILE_FILE env var)
+> -fprofile-instr-generate=<file>
+> Generate instrumented code to collect execution counts into <file> (overridden by LLVM_PROFILE_FILE env var)
+> -fprofile-instr-generate
+> Generate instrumented code to collect execution counts into default.profraw file (overridden by '=' form of option or LLVM_PROFILE_FILE env var)
+> -fprofile-instr-use=<value>
+> Use instrumentation data for profile-guided optimization
+> -fprofile-list=<value> Filename defining the list of functions/files to instrument. The file uses the sanitizer special case list format.
+> -fprofile-remapping-file=<file>
+> Use the remappings described in <file> to match the profile data against names in the program
+> -fprofile-sample-use=<value>
+> Enable sample-based profile guided optimizations
+> -fprofile-update=<method>
+> Set update method of profile counters
+> -fprofile-use=<pathname>
+> Use instrumentation data for profile-guided optimization. If pathname is a directory, it reads from <pathname>/default.profdata. Otherwise, it reads from file <pathname>.
+> -fprotect-parens Determines whether the optimizer honors parentheses when floating-point expressions are evaluated
+> -fpseudo-probe-for-profiling
+> Emit pseudo probes for sample profiling
+> -frtlib-defaultlib On Windows, emit /defaultlib: directives to link compiler-rt libraries (default)
+> -fsanitize-address-destructor=<value>
+> Set the kind of module destructors emitted by AddressSanitizer instrumentation. These destructors are emitted to unregister instrumented global variables when code is unloaded (e.g. via `dlclose()`).
+> -fsanitize-address-field-padding=<value>
+> Level of field padding for AddressSanitizer
+> -fsanitize-address-globals-dead-stripping
+> Enable linker dead stripping of globals in AddressSanitizer
+> -fsanitize-address-outline-instrumentation
+> Always generate function calls for address sanitizer instrumentation
+> -fsanitize-address-poison-custom-array-cookie
+> Enable poisoning array cookies when using custom operator new[] in AddressSanitizer
+> -fsanitize-address-use-after-return=<mode>
+> Select the mode of detecting stack use-after-return in AddressSanitizer
+> -fsanitize-address-use-after-scope
+> Enable use-after-scope detection in AddressSanitizer
+> -fsanitize-address-use-odr-indicator
+> Enable ODR indicator globals to avoid false ODR violation reports in partially sanitized programs at the cost of an increase in binary size
+> -fsanitize-alloc-token-extended
+> Enable extended coverage to custom allocation functions
+> -fsanitize-alloc-token-fast-abi
+> Use the AllocToken fast ABI
+> -fsanitize-annotate-debug-info=<value>
+> Annotate sanitizer instrumentation with extra debug info for the specified sanitizers, if supported
+> -fsanitize-annotate-debug-info
+> Allow compiler to annotate sanitizer instrumentation with extra debug info for all sanitizers, where supported
+> -fsanitize-cfi-canonical-jump-tables
+> Make the jump table addresses canonical in the symbol table
+> -fsanitize-cfi-cross-dso
+> Enable control flow integrity (CFI) checks for cross-DSO calls.
+> -fsanitize-cfi-icall-experimental-normalize-integers
+> Normalize integers in CFI indirect call type signature checks
+> -fsanitize-cfi-icall-generalize-pointers
+> Generalize pointers in CFI indirect call type signature checks
+> -fsanitize-coverage-allowlist=<value>
+> Restrict sanitizer coverage instrumentation exclusively to modules and functions that match the provided special case list, except the blocked ones
+> -fsanitize-coverage-ignorelist=<value>
+> Disable sanitizer coverage instrumentation for modules and functions that match the provided special case list, even the allowed ones
+> -fsanitize-coverage-stack-depth-callback-min=<M>
+> Use callback for max stack depth tracing with minimum stack depth M
+> -fsanitize-coverage=<value>
+> Specify the type of coverage instrumentation for Sanitizers
+> -fsanitize-debug-trap-reasons=<value>
+> Set how trap reasons are emitted. `none` - Not emitted. This gives the smallest debug info; `basic` - Emit a fixed trap message per check type. This increases the debug info size but not as much as `detailed`; `detailed` - Emit a more detailed trap message. This increases the debug info size the most. Default is `detailed`.
+> -fsanitize-debug-trap-reasons
+> Alias for -fsanitize-debug-trap-reasons=detailed
+> -fsanitize-handler-preserve-all-regs
+> Enable handlers with preserve_all calling convention
+> -fsanitize-hwaddress-abi=<value>
+> Select the HWAddressSanitizer ABI to target (interceptor or platform, default interceptor). This option is currently unused.
+> -fsanitize-hwaddress-experimental-aliasing
+> Enable aliasing mode in HWAddressSanitizer
+> -fsanitize-ignorelist=<value>
+> Path to ignorelist file for sanitizers
+> -fsanitize-kcfi-arity Embed function arity information into the KCFI patchable function prefix
+> -fsanitize-kcfi-hash=<value>
+> Select hash algorithm for KCFI type IDs (xxHash64, FNV-1a)
+> -fsanitize-memory-param-retval
+> Enable detection of uninitialized parameters and return values
+> -fsanitize-memory-track-origins=<value>
+> Enable origins tracking in MemorySanitizer
+> -fsanitize-memory-track-origins
+> Enable origins tracking in MemorySanitizer
+> -fsanitize-memory-use-after-dtor
+> Enable use-after-destroy detection in MemorySanitizer
+> -fsanitize-memtag-mode=<value>
+> Set default MTE mode to 'sync' (default) or 'async'
+> -fsanitize-merge=<value>
+> Allow compiler to merge handlers for specified sanitizers
+> -fsanitize-merge Allow compiler to merge handlers for all sanitizers
+> -fsanitize-recover=<value>
+> Enable recovery for specified sanitizers
+> -fsanitize-skip-hot-cutoff=<value>
+> Exclude sanitization for the top hottest code responsible for the given fraction of PGO counters (0.0 [default] = skip none; 1.0 = skip all). Argument format: <sanitizer1>=<value1>,<sanitizer2>=<value2>,...
+> -fsanitize-stable-abi Stable ABI instrumentation for sanitizer runtime. Default: Conventional
+> -fsanitize-stats Enable sanitizer statistics gathering.
+> -fsanitize-system-ignorelist=<value>
+> Path to system ignorelist file for sanitizers
+> -fsanitize-thread-atomics
+> Enable atomic operations instrumentation in ThreadSanitizer (default)
+> -fsanitize-thread-func-entry-exit
+> Enable function entry/exit instrumentation in ThreadSanitizer (default)
+> -fsanitize-thread-memory-access
+> Enable memory access instrumentation in ThreadSanitizer (default)
+> -fsanitize-trap=<value> Enable trapping for specified sanitizers
+> -fsanitize-trap Enable trapping for all sanitizers
+> -fsanitize-type-outline-instrumentation
+> Always generate function calls for type sanitizer instrumentation
+> -fsanitize-undefined-ignore-overflow-pattern=<value>
+> Specify the overflow patterns to exclude from arithmetic sanitizer instrumentation
+> -fsanitize-undefined-strip-path-components=<number>
+> Strip (or keep only, if negative) a given number of path components when emitting check metadata.
+> -fsanitize=<check> Turn on runtime checks for various forms of undefined or suspicious behavior. See user manual for available checks
+> -fsplit-lto-unit Enables splitting of the LTO unit
+> -fstandalone-debug Emit full debug info for all types used by the program
+> -fstrict-aliasing Enable optimizations based on strict aliasing rules
+> -fswift-async-fp=<option>
+> Control emission of Swift async extended frame info
+> -fsycl-device-only Compile SYCL code for device only
+> -fsycl-host-only Compile SYCL code for host only. Has no effect on non-SYCL compilations
+> -fsycl Enable SYCL C++ extensions
+> -fsyntax-only Run the preprocessor, parser and semantic analysis stages
+> -fsystem-module Build this module as a system module. Only used with -emit-module
+> -ftemporal-profile Generate instrumented code to collect temporal information
+> -fthin-link-bitcode=<value>
+> Write minimized bitcode to <file> for the ThinLTO thin link only
+> -fthinlto-distributor=<path>
+> Path to the ThinLTO distributor process. If specified, ThinLTO backend compilations will be distributed by LLD
+> -fthinlto-index=<value> Perform ThinLTO importing using provided function summary index
+> -ftime-trace-granularity=<value>
+> Minimum time granularity (in microseconds) traced by time profiler
+> -ftime-trace-verbose<value>
+> Make time trace capture verbose event details (e.g. source filenames). This can increase the size of the output by 2-3 times
+> -ftime-trace=<value> Similar to -ftime-trace. Specify the JSON file or a directory which will contain the JSON file
+> -ftime-trace Turn on time profiler. Generates JSON file based on output filename.
+> -ftrivial-auto-var-init-max-size=<value>
+> Stop initializing trivial automatic stack variables if var size exceeds the specified number of instances (in bytes)
+> -ftrivial-auto-var-init-stop-after=<value>
+> Stop initializing trivial automatic stack variables after the specified number of instances
+> -ftrivial-auto-var-init=<value>
+> Initialize trivial automatic stack variables. Defaults to 'uninitialized'
+> -fuse-cuid=<value> Method to generate ID's for compilation units for single source offloading languages CUDA and HIP: 'hash' (ID's generated by hashing file path and command line options) | 'random' (ID's generated as random numbers) | 'none' (disabled). Default is 'hash'. This option will be overridden by option '-cuid=[ID]' if it is specified.
+> -fverify-intermediate-code
+> Enable verification of LLVM IR
+> -fvirtual-function-elimination
+> Enables dead virtual function elimination optimization. Requires -flto=full
+> -fwhole-program-vtables Enables whole-program vtable optimization. Requires -flto
+> -fwrapv-pointer Treat pointer overflow as two's complement
+> -fwrapv Treat signed integer overflow as two's complement
+> -gcodeview-command-line Emit compiler path and command line into CodeView debug information
+> -gcodeview-ghash Emit type record hashes in a .debug$H section
+> -gcodeview Generate CodeView debug information
+> -gdwarf Generate source-level debug information with the default DWARF version
+> -gen-reproducer=<value> Emit reproducer on (option: off, crash (default), error, always)
+> -gkey-instructions Enable Key Instructions, which reduces the jumpiness of debug stepping in optimized C/C++ code in some debuggers. DWARF only.
+> -gline-directives-only Emit debug line info directives only
+> -gline-tables-only Emit debug line number tables only
+> -gno-codeview-command-line
+> Don't emit compiler path and command line into CodeView debug information
+> -gno-inline-line-tables Don't emit inline line tables.
+> --gpu-bundle-output Bundle output files of HIP device compilation
+> --gpu-instrument-lib=<value>
+> Instrument device library for HIP, which is a LLVM bitcode containing __cyg_profile_func_enter and __cyg_profile_func_exit
+> --gpu-max-threads-per-block=<value>
+> Default max threads per block for kernel launch bounds for HIP
+> -gsplit-dwarf=<value> Set DWARF fission mode
+> -gstrict-dwarf Restrict DWARF features to those defined in the specified version, avoiding features from later versions.
+> -gstructor-decl-linkage-names
+> Attach linkage names to C++ constructor/destructor declarations in DWARF.
+> -G <size> Put objects of at most <size> bytes into small data section (MIPS / Hexagon)
+> -g Generate source-level debug information
+> --hip-device-lib=<value>
+> HIP device library
+> --hip-link Link clang-offload-bundler bundles for HIP
+> --hip-path=<value> HIP runtime installation path, used for finding HIP version and adding HIP include path.
+> --hip-version=<value> HIP version in the format of major.minor.patch
+> --hipspv-pass-plugin=<dsopath>
+> path to a pass plugin for HIP to SPIR-V passes.
+> --hipstdpar-interpose-alloc
+> Replace all memory allocation / deallocation calls with hipManagedMalloc / hipFree equivalents
+> --hipstdpar-path=<value>
+> HIP Standard Parallel Algorithm Acceleration library path, used for finding and implicitly including the library header
+> --hipstdpar-prim-path=<value>
+> rocPrim path, required by the HIP Standard Parallel Algorithm Acceleration library, used to implicitly include the rocPrim library
+> --hipstdpar-thrust-path=<value>
+> rocThrust path, required by the HIP Standard Parallel Algorithm Acceleration library, used to implicitly include the rocThrust library
+> --hipstdpar Enable HIP acceleration for standard parallel algorithms
+> -mabi=quadword-atomics Enable quadword atomics ABI on AIX (AIX PPC64 only). Uses lqarx/stqcx. instructions.
+> -maix-struct-return Return all structs in memory (PPC32 only)
+> -malign-branch-boundary=<value>
+> Specify the boundary's size to align branches
+> -malign-branch=<value> Specify types of branches to align
+> -malign-double Align doubles to two words in structs (x86 only)
+> -mamdgpu-expand-waitcnt-profiling
+> Expand s_waitcnt instructions to help PC-sampling profilers identify memory stalls. Instead of a single waitcnt(target), emits waitcnt(N-1), waitcnt(N-2), ..., waitcnt(target). (AMDGPU only)
+> -mamdgpu-ieee Sets the IEEE bit in the expected default floating point mode register. Floating point opcodes that support exception flag gathering quiet and propagate signaling NaN inputs per IEEE 754-2008. This option changes the ABI. (AMDGPU only)
+> -mamdgpu-precise-memory-op
+> Enable precise memory mode (AMDGPU only)
+> -mannotate-tablejump Enable annotate table jump instruction to correlate it with the jump table.
+> -mapx-features=<value> Enable features of APX
+> -mapx-inline-asm-use-gpr32
+> Enable use of GPR32 in inline assembly for APX
+> -march=<value> For a list of available architectures for the target use '-mcpu=help'
+> -marm64x<value> Link as a hybrid ARM64X image
+> -mbackchain Link stack frames through backchain on System Z
+> -mbranch-protection=<value>
+> Enforce targets of indirect branches and function returns
+> -mbranches-within-32B-boundaries
+> Align selected branches (fused, jcc, jmp) within 32-byte boundary
+> -mcf-branch-label-scheme=<value>
+> Select label scheme for branch control-flow architecture protection
+> -mcode-object-version=<value>
+> Specify code object ABI version. Defaults to 6. (AMDGPU only)
+> -mconstructor-aliases Enable emitting complete constructors and destructors as aliases when possible
+> -mcpu=<value> For a list of available CPUs for the target use '-mcpu=help'
+> -mcrc Allow use of CRC instructions (ARM/Mips only)
+> -mdaz-ftz Globally set the denormals-are-zero (DAZ) and flush-to-zero (FTZ) bits in the floating-point control register on program startup
+> -mdefault-visibility-export-mapping=<value>
+> Mapping between default visibility and export
+> -mdiv32 Use div.w[u] and mod.w[u] instructions with input not sign-extended.
+> -mdouble=<n Force double to be <n> bits
+> -meabi <value> Set EABI type. Default depends on triple)
+> -menable-experimental-extensions
+> Enable use of experimental RISC-V extensions.
+> -mfentry Insert calls to fentry at function entry (x86/SystemZ only)
+> -mfrecipe Enable frecipe.{s/d} and frsqrte.{s/d}
+> -mfunction-return=<value>
+> Replace returns with jumps to ``__x86_return_thunk`` (x86 only, error otherwise)
+> -mgeneral-regs-only Generate code which only uses the general purpose registers (AArch64/x86 only)
+> -mglobal-merge Enable merging of globals
+> -mguard=<value> Enable or disable Control Flow Guard checks and guard tables emission
+> -mharden-sls=<value> Select straight-line speculation hardening scope (ARM/AArch64/X86 only). <arg> must be: all, none, retbr(ARM/AArch64), blr(ARM/AArch64), comdat(ARM/AArch64), nocomdat(ARM/AArch64), return(X86), indirect-jmp(X86)
+> -miamcu Use Intel MCU ABI
+> -mignore-xcoff-visibility
+> Not emit the visibility attribute for asm in AIX OS or give all symbols 'unspecified' visibility in XCOFF object file
+> -mimplicit-float Generate implicit floating point or vector instructions
+> -mincremental-linker-compatible
+> (integrated-as) Emit an object file which can be used with an incremental linker
+> -mindirect-branch-cs-prefix
+> Add cs prefix to call and jmp to indirect thunk
+> -mios-version-min=<value>
+> Set iOS deployment target
+> -mlam-bh Enable amswap[_db].{b/h} and amadd[_db].{b/h}
+> -mlamcas Enable amcas[_db].{b/h/w/d}
+> -mlasx Enable Loongson Advanced SIMD Extension (LASX).
+> -mld-seq-sa Do not generate same-address load-load barrier instructions (dbar 0x700)
+> -mlink-builtin-bitcode-postopt
+> Link builtin bitcodes after the optimization pipeline
+> -mllvm=<arg> Alias for -mllvm
+> -mllvm <value> Additional arguments to forward to LLVM's option processing
+> -mlong-calls Generate branches with extended addressability, usually via indirect jumps.
+> -mlsx Enable Loongson SIMD Extension (LSX).
+> -mlvi-cfi Enable only control-flow mitigations for Load Value Injection (LVI)
+> -mlvi-hardening Enable all mitigations for Load Value Injection (LVI)
+> -mmacos-version-min=<value>
+> Set macOS deployment target
+> -mms-bitfields Set the default structure layout to be compatible with the Microsoft compiler standard
+> -mno-amdgpu-precise-memory-op
+> Disable precise memory mode (AMDGPU only)
+> -mno-annotate-tablejump Disable annotate table jump instruction to correlate it with the jump table.
+> -mno-apx-features=<value>
+> Disable features of APX
+> -mno-constructor-aliases
+> Disable emitting complete constructors and destructors as aliases when possible
+> -mno-daz-ftz Do not globally set the denormals-are-zero (DAZ) and flush-to-zero (FTZ) bits in the floating-point control register on program startup
+> -mno-div32 Do not use div.w[u] and mod.w[u] instructions with input not sign-extended.
+> -mno-frecipe Disable frecipe.{s/d} and frsqrte.{s/d}
+> -mno-gather Disable generation of gather instructions in auto-vectorization(x86 only)
+> -mno-global-merge Disable merging of globals
+> -mno-implicit-float Don't generate implicit floating point or vector instructions
+> -mno-incremental-linker-compatible
+> (integrated-as) Emit an object file which cannot be used with an incremental linker
+> -mno-lam-bh Disable amswap[_db].{b/h} and amadd[_db].{b/h}
+> -mno-lamcas Disable amcas[_db].{b/h/w/d}
+> -mno-lasx Disable Loongson Advanced SIMD Extension (LASX).
+> -mno-ld-seq-sa Generate same-address load-load barrier instructions (dbar 0x700)
+> -mno-long-calls Restore the default behaviour of not generating long calls
+> -mno-lsx Disable Loongson SIMD Extension (LSX).
+> -mno-lvi-cfi Disable control-flow mitigations for Load Value Injection (LVI)
+> -mno-lvi-hardening Disable mitigations for Load Value Injection (LVI)
+> -mno-ms-bitfields Do not set the default structure layout to be compatible with the Microsoft compiler standard
+> -mno-pic-data-is-text-relative
+> Don't assume data segments are relative to text segment
+> -mno-regnames Use only register numbers when writing assembly output
+> -mno-relax Disable linker relaxation
+> -mno-scalar-strict-align
+> Allow scalar memory accesses to be unaligned (RISC-V only)
+> -mno-scatter Disable generation of scatter instructions in auto-vectorization(x86 only)
+> -mno-scq Disable sc.q instruction.
+> -mno-seses Disable speculative execution side effect suppression (SESES)
+> -mno-stack-arg-probe Disable stack probes which are enabled by default
+> -mno-strict-align Allow memory accesses to be unaligned (AArch64/LoongArch/RISC-V only)
+> -mno-tls-direct-seg-refs
+> Disable direct TLS access through segment registers
+> -mno-tocdata=<value> Specifies a list of variables to be exempt from the TOC data transformation.
+> -mno-tocdata This is the default. TOC data transformation is not applied to any variables. Only variables specified explicitly in -mtocdata= will have the TOC data transformation.
+> -mno-unaligned-access Force all memory accesses to be aligned (AArch32/MIPSr6 only)
+> -mno-unaligned-symbols Expect external char-aligned symbols to be without ABI alignment (SystemZ only)
+> -mno-vector-strict-align
+> Allow vector memory accesses to be unaligned (RISC-V only)
+> -mno-wavefrontsize64 Specify wavefront size 32 mode (AMDGPU only)
+> -mnop-mcount Generate mcount/__fentry__ calls as nops. To activate they need to be patched in.
+> -momit-leaf-frame-pointer
+> Omit frame pointer setup for leaf functions
+> -mpacked-stack Use packed stack layout (SystemZ only).
+> -mpad-max-prefix-size=<value>
+> Specify maximum number of prefixes to use for padding
+> -mpic-data-is-text-relative
+> Assume data segments are relative to text segment
+> -mprefer-vector-width=<value>
+> Specifies preferred vector width for auto-vectorization. Defaults to 'none' which allows target specific decisions.
+> -mprintf-kind=<value> Specify the printf lowering scheme (AMDGPU only), allowed values are "hostcall"(printing happens during kernel execution, this scheme relies on hostcalls which require system to support pcie atomics) and "buffered"(printing happens after all kernel threads exit, this uses a printf buffer and does not rely on pcie atomic support)
+> -mqdsp6-compat Enable hexagon-qdsp6 backward compatibility
+> -mrecip=<value> Control use of approximate reciprocal and reciprocal square root instructions followed by <n> iterations of Newton-Raphson refinement. <value> = ( ['!'] ['vec-'] ('rcp'|'sqrt') [('h'|'s'|'d')] [':'<n>] ) | 'all' | 'default' | 'none'
+> -mrecip Equivalent to '-mrecip=all'
+> -mrecord-mcount Generate a __mcount_loc section entry for each __fentry__ call.
+> -mregnames Use full register names when writing assembly output
+> -mrelax-all (integrated-as) Relax all machine instructions
+> -mrelax Enable linker relaxation
+> -mreserve-frame-pointer-reg
+> Reserve the frame pointer register even if the function doesn't have a frame
+> -mrtd Make StdCall calling convention the default
+> -mrvv-vector-bits=<value>
+> Specify the size in bits of an RVV vector register
+> -msave-reg-params Save arguments passed by registers to ABI-defined stack positions
+> -mscalar-strict-align Force all scalar memory accesses to be aligned (RISC-V only)
+> -mscq Enable sc.q instruction.
+> -mseses Enable speculative execution side effect suppression (SESES). Includes LVI control flow integrity mitigations
+> -msign-return-address=<value>
+> Select return address signing scope
+> -msimd=<value> Select the SIMD extension(s) to be enabled in LoongArch either 'none', 'lsx', 'lasx'.
+> -mskip-rax-setup Skip setting up RAX register when passing variable arguments (x86 only)
+> -msmall-data-limit=<value>
+> Put global and static data smaller than the limit into a special section
+> -msoft-float Use software floating point
+> -msse2avx Specify that the assembler should encode SSE instructions with VEX prefix
+> -mstack-alignment=<value>
+> Set the stack alignment
+> -mstack-arg-probe Enable stack probes
+> -mstack-probe-size=<value>
+> Set the stack probe size
+> -mstack-protector-guard-offset=<value>
+> Use the given offset for addressing the stack-protector guard
+> -mstack-protector-guard-reg=<value>
+> Use the given reg for addressing the stack-protector guard
+> -mstack-protector-guard-symbol=<value>
+> Use the given symbol for addressing the stack-protector guard
+> -mstack-protector-guard=<value>
+> Use the given guard (global, tls) for addressing the stack-protector guard
+> -mstackrealign Force realign the stack at entry to every function
+> -mstrict-align Force all memory accesses to be aligned (AArch64/LoongArch/RISC-V only)
+> -msvr4-struct-return Return small structs in registers (PPC32 only)
+> -mtargetos=<value> Set the deployment target to be the specified OS and OS version
+> -mthread-model <value> The thread model to use. Defaults to 'posix')
+> -mtls-dialect=<value> Which thread-local storage dialect to use for dynamic accesses of TLS variables
+> -mtls-direct-seg-refs Enable direct TLS access through segment registers (default)
+> -mtls-size=<value> Specify bit size of immediate TLS offsets (AArch64 ELF only): 12 (for 4KB) | 24 (for 16MB, default) | 32 (for 4GB) | 48 (for 256TB, needs -mcmodel=large)
+> -mtocdata=<value> Specifies a list of variables to which the TOC data transformation will be applied.
+> -mtocdata All suitable variables will have the TOC data transformation applied
+> -mtune=<value> Only supported on AArch64, PowerPC, RISC-V, SPARC, SystemZ, and X86
+> -munaligned-access Allow memory accesses to be unaligned (AArch32/MIPSr6 only)
+> -munaligned-symbols Expect external char-aligned symbols to be without ABI alignment (SystemZ only)
+> -mvector-strict-align Force all vector memory accesses to be aligned (RISC-V only)
+> -mwavefrontsize64 Specify wavefront size 64 mode (AMDGPU only)
+> -mxcoff-roptr Place constant objects with relocatable address values in the RO data section and add -bforceimprw to the linker flags (AIX only)
+> -mzos-target=<value> Set the z/OS release of the runtime environment
+> --no-cuda-include-ptx=<value>
+> Do not include PTX for the following GPU architecture (e.g. sm_35) or 'all'. May be specified more than once.
+> --no-cuda-version-check Don't error out if the detected version of the CUDA install is too low for the requested CUDA gpu architecture.
+> --no-default-config Disable loading default configuration files
+> --no-gpu-bundle-output Do not bundle output files of HIP device compilation
+> -no-hip-rt Do not link against HIP runtime libraries
+> --no-offload-arch=<value>
+> Remove CUDA/HIP offloading device architecture (e.g. sm_35, gfx906) from the list of devices to compile for. 'all' resets the list to its default value.
+> --no-offload-new-driver Don't Use the new driver for offloading compilation.
+> --no-offloadlib Do not link device library for CUDA/HIP/SYCL device compilation
+> --no-wasm-opt Disable the wasm-opt optimizer
+> -nobuiltininc Disable builtin #include directories only
+> -nostdinc Disable both standard system #include directories and builtin #include directories
+> -object-file-name=<file>
+> Set the output <file> for debug infos
+> --offload-arch-tool=<value>
+> Tool used for detecting offloading architectures in the system.
+> --offload-arch=<value> Specify an offloading device architecture for CUDA, HIP, or OpenMP. (e.g. sm_35). If 'native' is used the compiler will detect locally installed architectures. For HIP offloading, the device architecture can be followed by target ID features delimited by a colon (e.g. gfx908:xnack+:sramecc-). May be specified more than once.
+> --offload-compress Compress offload device binaries (HIP only)
+> --offload-device-only Only compile for the offloading device.
+> --offload-host-device Compile for both the offloading host and device (default).
+> --offload-host-only Only compile for the offloading host.
+> --offload-jobs=<value> Specify the number of threads to use for device offloading tasks during compilation. Can be a positive integer or the string 'jobserver' to use the make-style jobserver from the environment.
+> --offload-new-driver Use the new driver for offloading compilation.
+> --offload-targets=<value>
+> Specify a list of target architectures to use for offloading.
+> --offloadlib Link device libraries for GPU device compilation
+> --precompile Only precompile the input
+> -print-diagnostic-options
+> Print all of Clang's warning options
+> -print-effective-triple Print the effective target triple
+> -print-enabled-extensions
+> Print the extensions enabled by the given target and -march/-mcpu options. (AArch64 and RISC-V only)
+> -print-file-name=<file> Print the full library path of <file>
+> -print-libgcc-file-name Print the library path for the currently used compiler runtime library ("libgcc.a" or "libclang_rt.builtins.*.a")
+> -print-library-module-manifest-path
+> Print the path for the C++ Standard library module manifest
+> -print-prog-name=<name> Print the full program path of <name>
+> -print-resource-dir Print the resource directory pathname
+> -print-rocm-search-dirs Print the paths used for finding ROCm installation
+> -print-runtime-dir Print the directory pathname containing Clang's runtime libraries
+> -print-search-dirs Print the paths used for finding libraries and programs
+> -print-supported-cpus Print supported cpu models for the given target (if target is not specified,it will print the supported cpus for the default target)
+> -print-supported-extensions
+> Print supported -march extensions (RISC-V, AArch64 and ARM only)
+> -print-target-triple Print the normalized target triple
+> -print-targets Print the registered targets
+> --ptxas-path=<value> Path to ptxas (used for compiling CUDA code)
+> -Qunused-arguments Don't emit warning for unused driver arguments
+> -regcall4 Set __regcall4 as a default calling convention to respect __regcall ABI v.4
+> -resource-dir <value> The directory which holds the compiler resource files
+> --rocm-device-lib-path=<value>
+> ROCm device library path. Alternative to rocm-path.
+> --rocm-path=<value> ROCm installation path, used for finding and automatically linking required bitcode libraries.
+> -rtlib=<value> Compiler runtime library to use
+> --start-no-unused-arguments
+> Don't emit warnings about unused arguments for the following arguments
+> -sycl-std=<value> SYCL language standard to compile for.
+> --target=<value> Generate code for the given target
+> --version Print version information
+> -vfsoverlay <value> Overlay the virtual filesystem described by file over the real file system. Additionally, pass this overlay file to the linker if it supports it
+> /volatile:iso Volatile loads and stores have standard semantics
+> /volatile:ms Volatile loads and stores have acquire and release semantics
+> -v Show commands to run and use verbose output
+> --warning-suppression-mappings=<value>
+> File containing diagnostic suppression mappings. See user manual for file format.
+> --wasm-opt Enable the wasm-opt optimizer (default)
+> -W<warning> Enable the specified warning
+> -Xclang=<arg> Alias for -Xclang
+> -Xclangas=<arg> Alias for -Xclangas
+> -Xclangas <arg> Pass <arg> to clang -cc1as
+> -Xclang <arg> Pass <arg> to clang -cc1
+> -Xcuda-ptxas <arg> Pass <arg> to the ptxas assembler
+> -Xflang <arg> Pass <arg> to the flang compiler
+> -Xlinker <arg> Pass <arg> to the linker
+> -Xthinlto-distributor=<arg>
+> Pass <arg> to the ThinLTO distributor process. Can be specified multiple times or with comma-separated values.
+> -x <language> Treat subsequent input files as having type <language>
+> ```
+
+#### The /clang: Option
+
+When clang-cl is run with a set of `/clang:<arg>` options, it will gather all
+of the `<arg>` arguments and process them as if they were passed to the clang
driver. This mechanism allows you to pass flags that are not exposed in the
clang-cl options or flags that have a different meaning when passed to the clang
-driver. Regardless of where they appear in the command line, the ``/clang:``
+driver. Regardless of where they appear in the command line, the `/clang:`
arguments are treated as if they were passed at the end of the clang-cl command
line.
-The /Zc:dllexportInlines- Option
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+#### The /Zc:dllexportInlines- Option
This causes the class-level `dllexport` and `dllimport` attributes to not apply
to inline member functions, as they otherwise would. For example, in the code
below `S::foo()` would normally be defined and exported by the DLL, but when
-using the ``/Zc:dllexportInlines-`` flag it is not:
+using the `/Zc:dllexportInlines-` flag it is not:
-.. code-block:: c
-
- struct __declspec(dllexport) S {
- void foo() {}
- }
+```c
+struct __declspec(dllexport) S {
+ void foo() {}
+}
+```
This has the benefit that the compiler doesn't need to emit a definition of
`S::foo()` in every translation unit where the declaration is included, as it
@@ -6026,12 +6210,12 @@ would otherwise do to ensure there's a definition in the DLL even if it's not
used there. If the declaration occurs in a header file that's widely used, this
can save significant compilation time and output size. It also reduces the
number of functions exported by the DLL similarly to what
-``-fvisibility-inlines-hidden`` does for shared objects on ELF and Mach-O.
+`-fvisibility-inlines-hidden` does for shared objects on ELF and Mach-O.
Since the function declaration comes with an inline definition, users of the
library can use that definition directly instead of importing it from the DLL.
Note that the Microsoft Visual C++ compiler does not support this option, and
-if code in a DLL is compiled with ``/Zc:dllexportInlines-``, the code using the
+if code in a DLL is compiled with `/Zc:dllexportInlines-`, the code using the
DLL must be compiled in the same way so that it doesn't attempt to dllimport
the inline member functions. The reverse scenario should generally work though:
a DLL compiled without this flag (such as a system library compiled with Visual
@@ -6039,7 +6223,7 @@ C++) can be referenced from code compiled using the flag, meaning that the
referencing code will use the inline definitions instead of importing them from
the DLL.
-Also note that like when using ``-fvisibility-inlines-hidden``, the address of
+Also note that like when using `-fvisibility-inlines-hidden`, the address of
`S::foo()` will be different inside and outside the DLL, breaking the C/C++
standard requirement that functions have a unique address.
@@ -6053,95 +6237,95 @@ that the same instance of the variable is used inside and outside the DLL.
Using this flag can cause problems when inline functions that would otherwise
be dllexported refer to internal symbols of a DLL. For example:
-.. code-block:: c
-
- void internal();
+```c
+void internal();
- struct __declspec(dllimport) S {
- void foo() { internal(); }
- }
+struct __declspec(dllimport) S {
+ void foo() { internal(); }
+}
+```
Normally, references to `S::foo()` would use the definition in the DLL from
which it was exported, and which presumably also has the definition of
-`internal()`. However, when using ``/Zc:dllexportInlines-``, the inline
+`internal()`. However, when using `/Zc:dllexportInlines-`, the inline
definition of `S::foo()` is used directly, resulting in a link error since
`internal()` is not available. Even worse, if there is an inline definition of
`internal()` containing a static local variable, we will now refer to a
different instance of that variable than in the DLL:
-.. code-block:: c
-
- inline int internal() { static int x; return x++; }
+```c
+inline int internal() { static int x; return x++; }
- struct __declspec(dllimport) S {
- int foo() { return internal(); }
- }
+struct __declspec(dllimport) S {
+ int foo() { return internal(); }
+}
+```
-This could lead to very subtle bugs. Using ``-fvisibility-inlines-hidden`` can
+This could lead to very subtle bugs. Using `-fvisibility-inlines-hidden` can
lead to the same issue. To avoid it in this case, make `S::foo()` or
`internal()` non-inline, or mark them `dllimport/dllexport` explicitly.
-Finding Clang runtime libraries
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+#### Finding Clang runtime libraries
clang-cl supports several features that require runtime library support:
-- Address Sanitizer (ASan): ``-fsanitize=address``
-- Undefined Behavior Sanitizer (UBSan): ``-fsanitize=undefined``
-- Code coverage: ``-fprofile-instr-generate -fcoverage-mapping``
-- Profile Guided Optimization (PGO): ``-fprofile-generate``
+- Address Sanitizer (ASan): `-fsanitize=address`
+- Undefined Behavior Sanitizer (UBSan): `-fsanitize=undefined`
+- Code coverage: `-fprofile-instr-generate -fcoverage-mapping`
+- Profile Guided Optimization (PGO): `-fprofile-generate`
- Certain math operations (int128 division) require the builtins library
In order to use these features, the user must link the right runtime libraries
into their program. These libraries are distributed alongside Clang in the
library resource directory. Clang searches for the resource directory by
searching relative to the Clang executable. For example, if LLVM is installed
-in ``C:\Program Files\LLVM``, then the profile runtime library will be located
+in `C:\Program Files\LLVM`, then the profile runtime library will be located
at the path
-``C:\Program Files\LLVM\lib\clang\11.0.0\lib\windows\clang_rt.profile-x86_64.lib``.
+`C:\Program Files\LLVM\lib\clang\11.0.0\lib\windows\clang_rt.profile-x86_64.lib`.
For UBSan, PGO, and coverage, Clang will emit object files that auto-link the
appropriate runtime library, but the user generally needs to help the linker
-(whether it is ``lld-link.exe`` or MSVC ``link.exe``) find the library resource
+(whether it is `lld-link.exe` or MSVC `link.exe`) find the library resource
directory. Using the example installation above, this would mean passing
-``/LIBPATH:C:\Program Files\LLVM\lib\clang\11.0.0\lib\windows`` to the linker.
-If the user links the program with the ``clang`` or ``clang-cl`` drivers, the
+`/LIBPATH:C:\Program Files\LLVM\lib\clang\11.0.0\lib\windows` to the linker.
+If the user links the program with the `clang` or `clang-cl` drivers, the
driver will pass this flag for them.
The auto-linking can be disabled with -fno-rtlib-defaultlib. If that flag is
used, pass the complete flag to required libraries as described for ASan below.
If the linker cannot find the appropriate library, it will emit an error like
-this::
+this:
- $ clang-cl -c -fsanitize=undefined t.cpp
+```
+$ clang-cl -c -fsanitize=undefined t.cpp
- $ lld-link t.obj -dll
- lld-link: error: could not open 'clang_rt.ubsan_standalone-x86_64.lib': no such file or directory
- lld-link: error: could not open 'clang_rt.ubsan_standalone_cxx-x86_64.lib': no such file or directory
+$ lld-link t.obj -dll
+lld-link: error: could not open 'clang_rt.ubsan_standalone-x86_64.lib': no such file or directory
+lld-link: error: could not open 'clang_rt.ubsan_standalone_cxx-x86_64.lib': no such file or directory
- $ link t.obj -dll -nologo
- LINK : fatal error LNK1104: cannot open file 'clang_rt.ubsan_standalone-x86_64.lib'
+$ link t.obj -dll -nologo
+LINK : fatal error LNK1104: cannot open file 'clang_rt.ubsan_standalone-x86_64.lib'
+```
-To fix the error, add the appropriate ``/libpath:`` flag to the link line.
+To fix the error, add the appropriate `/libpath:` flag to the link line.
For ASan, as of this writing, the user is also responsible for linking against
the correct ASan libraries.
-If the user is using the dynamic CRT (``/MD``), then they should add
-``clang_rt.asan_dynamic-x86_64.lib`` to the link line as a regular input. For
+If the user is using the dynamic CRT (`/MD`), then they should add
+`clang_rt.asan_dynamic-x86_64.lib` to the link line as a regular input. For
other architectures, replace x86_64 with the appropriate name here and below.
-If the user is using the static CRT (``/MT``), then different runtimes are used
+If the user is using the static CRT (`/MT`), then different runtimes are used
to produce DLLs and EXEs. To link a DLL, pass
-``clang_rt.asan_dll_thunk-x86_64.lib``. To link an EXE, pass
-``-wholearchive:clang_rt.asan-x86_64.lib``.
+`clang_rt.asan_dll_thunk-x86_64.lib`. To link an EXE, pass
+`-wholearchive:clang_rt.asan-x86_64.lib`.
-Windows System Headers and Library Lookup
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+#### Windows System Headers and Library Lookup
clang-cl uses a set of different approaches to locate the right system libraries
-to link against when building code. The Windows environment uses libraries from
+to link against when building code. The Windows environment uses libraries from
three distinct sources:
1. Windows SDK
@@ -6149,120 +6333,120 @@ three distinct sources:
3. Visual C++ Tools (VCRuntime)
The Windows SDK provides the import libraries and headers required to build
-programs against the Windows system packages. Underlying the Windows SDK is the
+programs against the Windows system packages. Underlying the Windows SDK is the
UCRT, the universal C runtime.
This difference is best illustrated by the various headers that one would find
-in the different categories. The WinSDK would contain headers such as
+in the different categories. The WinSDK would contain headers such as
`WinSock2.h` which is part of the Windows API surface, providing the Windows
-socketing interfaces for networking. UCRT provides the C library headers,
-including e.g. `stdio.h`. Finally, the Visual C++ tools provides the underlying
+socketing interfaces for networking. UCRT provides the C library headers,
+including e.g. `stdio.h`. Finally, the Visual C++ tools provides the underlying
Visual C++ Runtime headers such as `stdint.h` or `crtdefs.h`.
There are various controls that allow the user control over where clang-cl will
-locate these headers. The default behaviour for the Windows SDK and UCRT is as
+locate these headers. The default behaviour for the Windows SDK and UCRT is as
follows:
1. Consult the command line.
- Anything the user specifies is always given precedence. The following
- extensions are part of the clang-cl toolset:
-
- - `/winsysroot:`
-
- The `/winsysroot:` is used as an equivalent to `-sysroot` on Unix
- environments. It allows the control of an alternate location to be treated
- as a system root. When specified, it will be used as the root where the
- `Windows Kits` is located.
-
- - `/winsdkversion:`
- - `/winsdkdir:`
-
- If `/winsysroot:` is not specified, the `/winsdkdir:` argument is consulted
- as a location to identify where the Windows SDK is located. Contrary to
- `/winsysroot:`, `/winsdkdir:` is expected to be the complete path rather
- than a root to locate `Windows Kits`.
-
- The `/winsdkversion:` flag allows the user to specify a version identifier
- for the SDK to prefer. When this is specified, no additional validation is
- performed and this version is preferred. If the version is not specified,
- the highest detected version number will be used.
+ > Anything the user specifies is always given precedence. The following
+ > extensions are part of the clang-cl toolset:
+ >
+ > - `/winsysroot:`
+ >
+ > The `/winsysroot:` is used as an equivalent to `-sysroot` on Unix
+ > environments. It allows the control of an alternate location to be treated
+ > as a system root. When specified, it will be used as the root where the
+ > `Windows Kits` is located.
+ >
+ > - `/winsdkversion:`
+ > - `/winsdkdir:`
+ >
+ > If `/winsysroot:` is not specified, the `/winsdkdir:` argument is consulted
+ > as a location to identify where the Windows SDK is located. Contrary to
+ > `/winsysroot:`, `/winsdkdir:` is expected to be the complete path rather
+ > than a root to locate `Windows Kits`.
+ >
+ > The `/winsdkversion:` flag allows the user to specify a version identifier
+ > for the SDK to prefer. When this is specified, no additional validation is
+ > performed and this version is preferred. If the version is not specified,
+ > the highest detected version number will be used.
2. Consult the environment.
- TODO: This is not yet implemented.
-
- This will consult the environment variables:
-
- - `WindowsSdkDir`
- - `UCRTVersion`
+ > TODO: This is not yet implemented.
+ >
+ > This will consult the environment variables:
+ >
+ > - `WindowsSdkDir`
+ > - `UCRTVersion`
3. Fallback to the registry.
- If no arguments are used to indicate where the SDK is present, and the
- compiler is running on Windows, the registry is consulted to locate the
- installation.
+ > If no arguments are used to indicate where the SDK is present, and the
+ > compiler is running on Windows, the registry is consulted to locate the
+ > installation.
The Visual C++ Toolset has a slightly more elaborate mechanism for detection.
1. Consult the command line.
- - `/winsysroot:`
-
- The `/winsysroot:` is used as an equivalent to `-sysroot` on Unix
- environments. It allows the control of an alternate location to be treated
- as a system root. When specified, it will be used as the root where the
- `VC` directory is located.
-
- - `/vctoolsdir:`
- - `/vctoolsversion:`
-
- If `/winsysroot:` is not specified, the `/vctoolsdir:` argument is consulted
- as a location to identify where the Visual C++ Tools are located. If
- `/vctoolsversion:` is specified, that version is preferred, otherwise, the
- highest version detected is used.
+ > - `/winsysroot:`
+ >
+ > The `/winsysroot:` is used as an equivalent to `-sysroot` on Unix
+ > environments. It allows the control of an alternate location to be treated
+ > as a system root. When specified, it will be used as the root where the
+ > `VC` directory is located.
+ >
+ > - `/vctoolsdir:`
+ > - `/vctoolsversion:`
+ >
+ > If `/winsysroot:` is not specified, the `/vctoolsdir:` argument is consulted
+ > as a location to identify where the Visual C++ Tools are located. If
+ > `/vctoolsversion:` is specified, that version is preferred, otherwise, the
+ > highest version detected is used.
2. Consult the environment.
- - `/external:[VARIABLE]`
-
- This specifies a user identified environment variable which is treated as
- a path delimiter (`;`) separated list of paths to map into `-imsvc`
- arguments which are treated as `-isystem`.
-
- - `INCLUDE` and `EXTERNAL_INCLUDE`
-
- The path delimiter (`;`) separated list of paths will be mapped to
- `-imsvc` arguments which are treated as `-isystem`.
-
- - `LIB` (indirectly)
-
- The linker `link.exe` or `lld-link.exe` will honour the environment
- variable `LIB` which is a path delimiter (`;`) set of paths to consult for
- the import libraries to use when linking the final target.
-
- The following environment variables will be consulted and used to form paths
- to validate and load content from as appropriate:
-
- - `VCToolsInstallDir`
- - `VCINSTALLDIR`
- - `Path`
+ > - `/external:[VARIABLE]`
+ >
+ > This specifies a user identified environment variable which is treated as
+ > a path delimiter (`;`) separated list of paths to map into `-imsvc`
+ > arguments which are treated as `-isystem`.
+ >
+ > - `INCLUDE` and `EXTERNAL_INCLUDE`
+ >
+ > The path delimiter (`;`) separated list of paths will be mapped to
+ > `-imsvc` arguments which are treated as `-isystem`.
+ >
+ > - `LIB` (indirectly)
+ >
+ > The linker `link.exe` or `lld-link.exe` will honour the environment
+ > variable `LIB` which is a path delimiter (`;`) set of paths to consult for
+ > the import libraries to use when linking the final target.
+ >
+ > The following environment variables will be consulted and used to form paths
+ > to validate and load content from as appropriate:
+ >
+ > > - `VCToolsInstallDir`
+ > > - `VCINSTALLDIR`
+ > > - `Path`
3. Consult `ISetupConfiguration` [Windows Only]
- Assuming that the toolchain is built with `USE_MSVC_SETUP_API` defined and
- is running on Windows, the Visual Studio COM interface `ISetupConfiguration`
- will be used to locate the installation of the MSVC toolset.
+ > Assuming that the toolchain is built with `USE_MSVC_SETUP_API` defined and
+ > is running on Windows, the Visual Studio COM interface `ISetupConfiguration`
+ > will be used to locate the installation of the MSVC toolset.
4. Fallback to the registry [DEPRECATED]
- The registry information is used to help locate the installation as a final
- fallback. This is only possible for pre-VS2017 installations and is
- considered deprecated.
+ > The registry information is used to help locate the installation as a final
+ > fallback. This is only possible for pre-VS2017 installations and is
+ > considered deprecated.
-Restrictions and Limitations compared to Clang
-----------------------------------------------
+### Restrictions and Limitations compared to Clang
Strict aliasing (TBAA) is always off by default in clang-cl whereas in clang,
strict aliasing is turned on by default for all optimization levels. For more
-details, see :ref:`Strict aliasing <strict_aliasing>`.
+details, see {ref}`Strict aliasing <strict_aliasing>`.
+
>From 90bf6bffc9a7ffc828488d71cb682eafc1468233 Mon Sep 17 00:00:00 2001
From: Reid Kleckner <rkleckner at nvidia.com>
Date: Wed, 8 Jul 2026 18:56:57 +0000
Subject: [PATCH 3/5] [docs] Finish MyST migration for selected docs
---
clang/docs/HIPSupport.md | 3 +-
clang/docs/MisExpect.md | 25 +++-----
clang/docs/Modules.md | 9 +--
clang/docs/OpenCLSupport.md | 12 +++-
clang/docs/OpenMPSupport.md | 86 +++++++++++++++++++++++++-
clang/docs/OverflowBehaviorTypes.md | 3 +-
clang/docs/PointerAuthentication.md | 46 +++++++-------
clang/docs/SYCLSupport.md | 3 +-
clang/docs/SafeStack.md | 3 +-
clang/docs/SanitizerSpecialCaseList.md | 7 +--
clang/docs/SanitizerStats.md | 6 +-
clang/docs/ShadowCallStack.md | 3 +-
clang/docs/SourceBasedCodeCoverage.md | 3 +-
clang/docs/StandardCPlusPlusModules.md | 9 ++-
clang/docs/StructureProtection.md | 3 +-
clang/docs/ThinLTO.md | 3 +-
clang/docs/UsersManual.md | 38 ++++++++----
17 files changed, 174 insertions(+), 88 deletions(-)
diff --git a/clang/docs/HIPSupport.md b/clang/docs/HIPSupport.md
index e2b81227e7846..40abe87f2b14d 100644
--- a/clang/docs/HIPSupport.md
+++ b/clang/docs/HIPSupport.md
@@ -19,7 +19,7 @@
```
```{contents}
-:local: true
+:local:
```
# HIP Support
@@ -1126,4 +1126,3 @@ diverges from the traditional compilation flow:
None of the architecture specific {doc}`AMDGPU macros <AMDGPUSupport>` are
defined when targeting SPIR-V. An alternative, more flexible mechanism to enable
doing per target / per feature code selection will be added in the future.
-
diff --git a/clang/docs/MisExpect.md b/clang/docs/MisExpect.md
index 8a29223f8cf3c..aba6f349a9bec 100644
--- a/clang/docs/MisExpect.md
+++ b/clang/docs/MisExpect.md
@@ -42,27 +42,23 @@ MisExpect diagnostics are also available in the form of optimization remarks,
which can be serialized and processed through the `opt-viewer.py`
scripts in LLVM.
-```{eval-rst}
-.. option:: -Rpass=misexpect
-
- Enables optimization remarks for misexpect when profiling data conflicts with
- use of ``llvm.expect`` intrinsics.
+```{option} -Rpass=misexpect
+Enables optimization remarks for misexpect when profiling data conflicts with
+use of `llvm.expect` intrinsics.
```
-```{eval-rst}
-.. option:: -Wmisexpect
+```{option} -Wmisexpect
- Enables misexpect warnings when profiling data conflicts with use of
- ``llvm.expect`` intrinsics.
+Enables misexpect warnings when profiling data conflicts with use of
+`llvm.expect` intrinsics.
```
-```{eval-rst}
-.. option:: -fdiagnostic-misexpect-tolerance=N
+```{option} -fdiagnostic-misexpect-tolerance=N
- Relaxes misexpect checking to tolerate profiling values within N% of the
- expected branch weight. e.g., a value of ``N=5`` allows misexpect to check against
- ``0.95 * Threshold``
+Relaxes misexpect checking to tolerate profiling values within N% of the
+expected branch weight. e.g., a value of `N=5` allows misexpect to check against
+`0.95 * Threshold`
```
LLVM supports 4 types of profile formats: Frontend, IR, CS-IR, and
@@ -74,4 +70,3 @@ Sampling. MisExpect Diagnostics are compatible with all Profiling formats.
| IR | Profiling instrumentation added during by the LLVM backend |
| CS-IR | Context Sensitive IR based profiles |
| Sampling | Profiles collected through sampling with external tools, such as `perf` on Linux |
-
diff --git a/clang/docs/Modules.md b/clang/docs/Modules.md
index 3404157d677a2..2bc780dfccb45 100644
--- a/clang/docs/Modules.md
+++ b/clang/docs/Modules.md
@@ -1,7 +1,7 @@
# Modules
```{contents}
-:local: true
+:local:
```
## Introduction
@@ -96,7 +96,7 @@ To enable modules, pass the command-line flag `-fmodules`. This will make any mo
### Standard C++ Modules
:::{note}
-Modules are adopted into C++20 Standard. And its semantic and command line interface are very different from the Clang C++ modules. See [StandardCPlusPlusModules](StandardCPlusPlusModules.html) for details.
+Modules are adopted into C++20 Standard. And its semantic and command line interface are very different from the Clang C++ modules. See {doc}`StandardCPlusPlusModules` for details.
:::
### Objective-C Import declaration
@@ -1243,7 +1243,7 @@ The Clang source code provides additional information about modules:
: The `ModuleMap` class in this header describes the full module map, consisting of all of the module map files that have been parsed, and providing facilities for looking up module maps and mapping between modules and headers (in both directions).
-[PCHInternals]
+{doc}`PCHInternals`
: Information about the serialized AST format used for precompiled headers and modules. The actual implementation is in the `clangSerialization` library.
@@ -1254,6 +1254,3 @@ The Clang source code provides additional information about modules:
[^footnote-3]: The second instance is actually a new thread within the current process, not a separate process. However, the original compiler instance is blocked on the execution of this thread.
[^footnote-4]: The preprocessing context in which the modules are parsed is actually dependent on the command-line options provided to the compiler, including the language dialect and any `-D` options. However, the compiled modules for different command-line options are kept distinct, and any preprocessor directives that occur within the translation unit are ignored. See the section on the [Configuration macros declaration] for more information.
-
-[pchinternals]: PCHInternals.html
-
diff --git a/clang/docs/OpenCLSupport.md b/clang/docs/OpenCLSupport.md
index 87cf6df434af1..927ed1cc01edb 100644
--- a/clang/docs/OpenCLSupport.md
+++ b/clang/docs/OpenCLSupport.md
@@ -19,7 +19,7 @@
```
```{contents}
-:local: true
+:local:
```
# OpenCL Support
@@ -77,6 +77,7 @@ All the options in this section are frontend-only and therefore if used
with regular clang driver they require frontend forwarding, e.g. `-cc1`
or `-Xclang`.
+(opencl_finclude_default_header)=
(opencl-finclude-default-header)=
```{eval-rst}
@@ -121,6 +122,7 @@ declarations is to use mechanism enabled by {ref}`-fdeclare-opencl-builtins
<opencl_fdeclare_opencl_builtins>` flag that is available as an alternative
feature.
+(opencl_fdeclare_opencl_builtins)=
(opencl-fdeclare-opencl-builtins)=
```{eval-rst}
@@ -140,6 +142,7 @@ if full functionality is required.
> $ clang -Xclang -fdeclare-opencl-builtins test.cl
> ```
+(opencl_fake_address_space_map)=
(opencl-fake-address-space-map)=
```{eval-rst}
@@ -159,6 +162,7 @@ also {ref}`the section on the address space attribute <opencl_addrsp>`).
> $ clang -cc1 -ffake-address-space-map test.cl
> ```
+(opencl_builtins)=
(opencl-builtins)=
### OpenCL builtins
@@ -230,6 +234,7 @@ extensions. For all other targets the configuration has to be made explicitly.
Note that the target extension support performed by clang can be overridden
with {option}`-cl-ext` command-line flags.
+(opencl_ext_libs)=
(opencl-ext-libs)=
**Library functionality**
@@ -267,6 +272,7 @@ the use of types or functions. This functionality is not guaranteed to remain in
future releases. However, any future changes should not affect backward
compatibility.
+(opencl_addrsp)=
(opencl-addrsp)=
### Address spaces attribute
@@ -292,6 +298,7 @@ to keep it and only lower to reflect physical memory segments in the late
machine passes. The mapping between logical and target address spaces is
specified in the Clang's source code.
+(cxx_for_opencl_impl)=
(cxx-for-opencl-impl)=
## C++ for OpenCL Implementation Status
@@ -315,6 +322,7 @@ to view the full bug list.
- Support of [destructors with non-default address spaces](https://www.khronos.org/opencl/assets/CXX_for_OpenCL.html#_construction_initialization_and_destruction)
is incomplete (See: [D109609](https://reviews.llvm.org/D109609)).
+(opencl_300)=
(opencl-300)=
## OpenCL C 3.0 Usage
@@ -377,6 +385,7 @@ implementation status.
+------------------------------+-------------------------+-----------------------------------------+----------------------+--------------------------------------------------------------------------------------------------------------------------------+
```
+(opencl_experimenal)=
(opencl-experimenal)=
## Experimental features
@@ -434,4 +443,3 @@ in [Compiler Explorer](https://godbolt.org/z/5WbnTfb65).
More OpenCL specific C++ library implementations built on top of libcxx
are available in [libclcxx](https://github.com/KhronosGroup/libclcxx)
project.
-
diff --git a/clang/docs/OpenMPSupport.md b/clang/docs/OpenMPSupport.md
index 501da6ca5b413..7832a6eced499 100644
--- a/clang/docs/OpenMPSupport.md
+++ b/clang/docs/OpenMPSupport.md
@@ -19,7 +19,7 @@
```
```{contents}
-:local: true
+:local:
```
# OpenMP Support
@@ -32,7 +32,8 @@ Interface (OMPT) on x86, x86_64, AArch64, and PPC64 on Linux, Windows, and macOS
OMPT is also supported for NVIDIA and AMD GPUs.
For the list of supported features from OpenMP 5.0 and 5.1
-see [OpenMP implementation details] and [OpenMP 51 implementation details].
+see {ref}`OpenMP implementation details <openmp-implementation-details>` and
+{ref}`OpenMP 51 implementation details <openmp-51-implementation-details>`.
## General improvements
@@ -283,6 +284,86 @@ and their implementation status. Please post on the
information or if you want to help with the
implementation.
+| Feature | C/C++ Status | Fortran Status | Reviews |
+| ----------------------------------------------------------- | ------------------- | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| free-agent threads | {none}`unclaimed` | {none}`unclaimed` | |
+| threadset clause | {part}`partial` | {none}`unclaimed` | Parse/Sema/Codegen: <https://github.com/llvm/llvm-project/pull/13580> |
+| Recording of task graphs | {part}`in progress` | {part}`in progress` | clang: jtb20, flang: kparzysz |
+| Parallel inductions | {none}`unclaimed` | {none}`unclaimed` | |
+| init_complete for scan directive | {none}`unclaimed` | {none}`unclaimed` | |
+| loop interchange transformation | {good}`done` | {none}`unclaimed` | Clang (interchange): <https://github.com/llvm/llvm-project/pull/93022> Clang (permutation): <https://github.com/llvm/llvm-project/pull/92030> |
+| loop reverse transformation | {good}`done` | {none}`unclaimed` | <https://github.com/llvm/llvm-project/pull/92916> |
+| loop stripe transformation | {good}`done` | {none}`unclaimed` | <https://github.com/llvm/llvm-project/pull/119891> |
+| loop fusion transformation | {part}`in progress` | {good}`done` | <https://github.com/llvm/llvm-project/pull/139293> <https://github.com/llvm/llvm-project/pull/161213> <https://github.com/llvm/llvm-project/pull/168898> |
+| loop index set splitting transformation with count clause | {part}`in progress` | {none}`unclaimed` | @amitamd7 |
+| loop transformation apply clause | {none}`unclaimed` | {none}`unclaimed` | |
+| loop fuse transformation | {good}`done` | {none}`unclaimed` | |
+| workdistribute construct | | {none}`in progress` | @skc7, @mjklemm |
+| task_iteration | {none}`unclaimed` | {none}`unclaimed` | |
+| memscope clause for atomic and flush | {none}`unclaimed` | {none}`unclaimed` | |
+| transparent clause (hull tasks) | {part}`partial` | {none}`unclaimed` | Clang parsing/sema <https://github.com/llvm/llvm-project/pull/174646> |
+| rule-based compound directives | {part}`In Progress` | {part}`In Progress` | kparzysz Testing for Fortran missing |
+| C23, C++23 | {none}`unclaimed` | | |
+| Fortran 2023 | | {none}`unclaimed` | |
+| decl attribute for declarative directives | {none}`unclaimed` | {none}`unclaimed` | |
+| C attribute syntax | {none}`unclaimed` | | |
+| pure directives in DO CONCURRENT | | {none}`unclaimed` | |
+| Optional argument for all clauses | {part}`partial` | {part}`In Progress` | Parse/Sema (nowait): <https://github.com/llvm/llvm-project/pull/159628> |
+| Function references for locator list items | {none}`unclaimed` | {none}`unclaimed` | |
+| All clauses accept directive name modifier | {none}`unclaimed` | {none}`unclaimed` | |
+| Extensions to depobj construct | {none}`unclaimed` | {none}`unclaimed` | |
+| Extensions to atomic construct | {none}`unclaimed` | {none}`unclaimed` | |
+| Private reductions | {part}`mostly` | {none}`unclaimed` | Parse/Sema: <https://github.com/llvm/llvm-project/pull/129938> Codegen: <https://github.com/llvm/llvm-project/pull/134709> |
+| Self maps | {part}`partial` | {none}`unclaimed` | parsing/sema done: <https://github.com/llvm/llvm-project/pull/129888> |
+| Release map type for declare mapper | {none}`unclaimed` | {none}`unclaimed` | |
+| Extensions to interop construct | {none}`unclaimed` | {none}`unclaimed` | |
+| no_openmp_constructs | {good}`done` | {none}`unclaimed` | <https://github.com/llvm/llvm-project/pull/125933> |
+| safe_sync and progress with identifier and API | {none}`unclaimed` | {none}`unclaimed` | |
+| OpenMP directives in concurrent loop regions | {good}`done` | {none}`unclaimed` | <https://github.com/llvm/llvm-project/pull/125621> |
+| atomics constructs on concurrent loop regions | {good}`done` | {none}`unclaimed` | <https://github.com/llvm/llvm-project/pull/125621> |
+| Loop construct with DO CONCURRENT | | {part}`In Progress` | |
+| device_type clause for target construct | {none}`unclaimed` | {none}`unclaimed` | |
+| nowait for ancestor target directives | {none}`unclaimed` | {none}`unclaimed` | |
+| New API for devices' num_teams/thread_limit | {none}`unclaimed` | {none}`unclaimed` | |
+| Host and device environment variables | {part}`in progress` | {none}`unclaimed` | @amitamd7 |
+| num_threads ICV and clause accepts list | {none}`unclaimed` | {none}`unclaimed` | |
+| Numeric names for environment variables | {none}`unclaimed` | {none}`unclaimed` | |
+| Increment between places for OMP_PLACES | {none}`unclaimed` | {none}`unclaimed` | |
+| OMP_AVAILABLE_DEVICES envirable | {none}`unclaimed` | {none}`unclaimed` | (should wait for "Traits for default device envirable" being done) |
+| Traits for default device envirable | {part}`in progress` | {none}`unclaimed` | ro-i |
+| Optionally omit array length expression | {good}`done` | {none}`unclaimed` | (Parse) <https://github.com/llvm/llvm-project/pull/148048>, (Sema) <https://github.com/llvm/llvm-project/pull/152786> |
+| Canonical loop sequences | {part}`in progress` | {part}`in progress` | Clang: <https://github.com/llvm/llvm-project/pull/139293> |
+| Clarifications to Fortran map semantics | {none}`unclaimed` | {none}`unclaimed` | |
+| default clause at target construct | {good}`done` | {none}`unclaimed` | <https://github.com/llvm/llvm-project/pull/162910> |
+| ref count update use_device_{ptr, addr} | {none}`unclaimed` | {none}`unclaimed` | |
+| Clarifications to implicit reductions | {none}`unclaimed` | {none}`unclaimed` | |
+| ref modifier for map clauses | {part}`In Progress` | {none}`unclaimed` | |
+| map-type modifiers in arbitrary position | {good}`done` | {none}`unclaimed` | <https://github.com/llvm/llvm-project/pull/90499> |
+| Lift nesting restriction on concurrent loop | {good}`done` | {none}`unclaimed` | <https://github.com/llvm/llvm-project/pull/125621> |
+| priority clause for target constructs | {none}`unclaimed` | {none}`unclaimed` | |
+| changes to target_data construct | {none}`unclaimed` | {none}`unclaimed` | |
+| Non-const do_not_sync for nowait/nogroup | {none}`unclaimed` | {none}`unclaimed` | |
+| need_device_addr modifier for adjust_args clause | {part}`partial` | {none}`unclaimed` | Parsing/Sema: <https://github.com/llvm/llvm-project/pull/143442> <https://github.com/llvm/llvm-project/pull/149586> |
+| need_device_ptr modifier for adjust_args clause | {none}`unclaimed` | {none}`unclaimed` | |
+| Prescriptive num_threads | {good}`done` | {none}`unclaimed` | <https://github.com/llvm/llvm-project/pull/160659> <https://github.com/llvm/llvm-project/pull/146403> <https://github.com/llvm/llvm-project/pull/146404> <https://github.com/llvm/llvm-project/pull/146405> |
+| Message and severity clauses | {good}`done` | {none}`unclaimed` | <https://github.com/llvm/llvm-project/pull/146093> |
+| Local clause on declare target | {good}`done` | {none}`unclaimed` | clang Parse/Sema: <https://github.com/llvm/llvm-project/pull/186281> clang Codegen: <https://github.com/llvm/llvm-project/pull/196431> |
+| groupprivate directive | {part}`In Progress` | {part}`partial` | Flang: kparzysz, mjklemm Flang parser: <https://github.com/llvm/llvm-project/pull/153807> Flang sema: <https://github.com/llvm/llvm-project/pull/154779> Clang parse/sema: <https://github.com/llvm/llvm-project/pull/158134> |
+| variable-category on default clause | {good}`done` | {none}`unclaimed` | |
+| Changes to omp_target_is_accessible | {part}`In Progress` | {part}`In Progress` | |
+| defaultmap implicit-behavior 'storage' | {good}`done` | {none}`unclaimed` | <https://github.com/llvm/llvm-project/pull/158336> |
+| defaultmap implicit-behavior 'private' | {good}`done` | {none}`unclaimed` | <https://github.com/llvm/llvm-project/pull/158712> |
+| OMPT: ompt_get_buffer_limits entry point | {part}`partial` | {good}`N/A` | Definition: <https://github.com/llvm/llvm-project/pull/195829> |
+| OMPT: ompt_any_record_ompt_t for device tracing | {good}`done` | {good}`N/A` | <https://github.com/llvm/llvm-project/pull/195829> |
+| OMPT: ompt_target_data_transfer_rect(_async) & subvolume | {part}`partial` | {good}`N/A` | Enum: <https://github.com/llvm/llvm-project/pull/195829> |
+| OMPT: ompt_target_data_transfer(_async) | {part}`partial` | {good}`N/A` | Enum: <https://github.com/llvm/llvm-project/pull/195829> |
+| OMPT: ompt_target_data_memset(_async) | {part}`partial` | {good}`N/A` | Enum: <https://github.com/llvm/llvm-project/pull/195829> Callbacks: <https://github.com/llvm/llvm-project/pull/194168> |
+| OMPT: workdistribute work callback enum | {part}`partial` | {good}`N/A` | Enum: <https://github.com/llvm/llvm-project/pull/195829> |
+| OMPT: transparent task flag enum (importing/exporting) | {part}`partial` | {good}`N/A` | Enum: <https://github.com/llvm/llvm-project/pull/195829> |
+| OMPT: dependence type {out, inout}_all_memory | {part}`partial` | {good}`N/A` | Enum: <https://github.com/llvm/llvm-project/pull/195829> |
+| OMPT: removed master callback | {none}`unclaimed` | {good}`N/A` | |
+| OMPT: removed sync_region_barrier(_implicit) enum value | {none}`unclaimed` | {good}`N/A` | |
+
(openmp-6-0-deprecations)=
## OpenMP 6.0 Deprecations
@@ -330,4 +411,3 @@ considered for standardization. Please post on the
| device extension | Multi-dim 'num_teams' and 'thread_limit' clause on 'target teams ompx_bare' construct | {part}`partial` | #99732, #101407, #102715 |
[discourse forums (runtimes - openmp category)]: https://discourse.llvm.org/c/runtimes/openmp/35
-
diff --git a/clang/docs/OverflowBehaviorTypes.md b/clang/docs/OverflowBehaviorTypes.md
index 06a44841b11ec..3f539a5232975 100644
--- a/clang/docs/OverflowBehaviorTypes.md
+++ b/clang/docs/OverflowBehaviorTypes.md
@@ -1,7 +1,7 @@
# OverflowBehaviorTypes
```{contents}
-:local: true
+:local:
```
## Introduction
@@ -802,4 +802,3 @@ typedef float __attribute__((overflow_behavior(wrap))) wrapping_float;
typedef struct S { int i; } __attribute__((overflow_behavior(wrap))) S_t;
// error: 'overflow_behavior' attribute cannot be applied to non-integer type 'struct S'
```
-
diff --git a/clang/docs/PointerAuthentication.md b/clang/docs/PointerAuthentication.md
index ade185b238e69..39bb9612d380a 100644
--- a/clang/docs/PointerAuthentication.md
+++ b/clang/docs/PointerAuthentication.md
@@ -1,7 +1,7 @@
# Pointer Authentication
```{contents}
-:local: true
+:local:
```
## Introduction
@@ -156,7 +156,7 @@ Readers may find it helpful to know how these terms map to Armv8.3 PAuth:
simply corrupt the pointer so that later uses will likely trap. Unless the
"later use" follows immediately and cannot be recovered from (e.g. with a
signal handler), this does not provide adequate protection against
- [authentication oracles], so implementations must emit additional
+ {ref}`authentication oracles <authentication-oracles>`, so implementations must emit additional
instructions to force an immediate trap. This is unnecessary if the
processor provides the optional `FPAC` extension, which guarantees an
immediate trap.
@@ -400,9 +400,9 @@ currently cannot be an Objective-C pointer type, a C++ reference type, or a
block pointer type; these restrictions may be lifted in the future.
The current implementation in Clang is known to not provide adequate safety
-guarantees against the creation of [signing oracles] when assigning data
+guarantees against the creation of {ref}`signing oracles <signing-oracles>` when assigning data
pointers to `__ptrauth`-qualified gl-values. See the section on [safe
-derivation][safe derivation] for more information.
+derivation](#safe-derivation) for more information.
The qualifier's operands are as follows:
@@ -599,7 +599,8 @@ Produce a signed pointer for the given raw pointer without applying any
authentication or extra treatment. This operation is not required to have the
same behavior on a null pointer that the language implementation would.
-This is a treacherous operation that can easily result in [signing oracles].
+This is a treacherous operation that can easily result in
+{ref}`signing oracles <signing-oracles>`.
Programs should use it seldom and carefully.
(ptrauth-auth-and-resign)=
@@ -622,7 +623,7 @@ The code sequence produced for this operation must not be directly attackable.
However, if the discriminator values are not constant integers, their
computations may still be attackable. In the future, Clang should be enhanced
to guarantee non-attackability if these expressions are
-{ref}`safely-derived<Safe derivation>`.
+{ref}`safely-derived <safe-derivation>`.
#### `ptrauth_auth_with_pc_and_resign`
@@ -630,7 +631,7 @@ to guarantee non-attackability if these expressions are
ptrauth_auth_with_pc_and_resign(pointer, oldKey, oldDiscriminator, oldPC, newKey, newDiscriminator)
```
-Similar to {ref}`ptrauth_auth_and_resign`, but additionally requires that the
+Similar to {ref}`ptrauth_auth_and_resign <ptrauth-auth-and-resign>`, but additionally requires that the
original signing schema includes the address of the signing instruction (i.e.
uses `paciasppc` / `pacibsppc` instead of `paciasp` / `pacibsp`). This
authenticates `pointer` signed with `oldKey` and `oldDiscriminator` at
@@ -778,7 +779,7 @@ higher cost.
Pointer authentication works as follows. Every indirect branch in a program has
a purpose. For every purpose, the implementation chooses a
-{ref}`signing schema<Signing schemas>`. At some place where a pointer is known
+{ref}`signing schema <signing-schemas>`. At some place where a pointer is known
to be correct for its purpose, it is signed according to the purpose's schema.
At every place where the pointer is needed for its purpose, it is authenticated
according to the purpose's schema. If that authentication fails, the program is
@@ -886,7 +887,7 @@ harvested from an object with similar structure (e.g. a different implementation
of the same interface). Using address diversity will prevent such harvesting
entirely. However, care must be taken when sourcing the v-table pointer
originally; do not blindly sign a pointer that is not
-{ref}`safely derived<Safe derivation>`.
+{ref}`safely derived <safe-derivation>`.
(signing-oracles)=
@@ -905,7 +906,7 @@ treacherous patterns of code. Currently this includes:
- assigning values to `__ptrauth`-qualified l-values.
Care must be taken in these situations to ensure that the pointer being signed
-has been {ref}`safely derived<Safe derivation>` or is otherwise not possible to
+has been {ref}`safely derived <safe-derivation>` or is otherwise not possible to
attack. (In some cases, this may be challenging without compiler support.)
A diagnostic will be added in the future for implicitly dangerous patterns of
@@ -941,7 +942,7 @@ requires careful work throughout the system.
Any failure to halt the program on an authentication failure is likely to be
exploitable by attackers to create an
-{ref}`authentication oracle<Authentication oracles>`.
+{ref}`authentication oracle <authentication-oracles>`.
There are several different ways to introduce this problem:
@@ -979,8 +980,8 @@ There are several different ways to introduce this problem:
If code that is part of a pointer authentication operation is interleaved with
code that may itself be vulnerable to attacks, an attacker may be able to use
-this to create a {ref}`signing<Signing oracles>` or
-{ref}`authentication<Authentication oracles>` oracle.
+this to create a {ref}`signing <signing-oracles>` or
+{ref}`authentication <authentication-oracles>` oracle.
For example, suppose that the compiler is generating a call to a function and
passing two arguments: a signed constant pointer and a value derived from a
@@ -1132,10 +1133,10 @@ program's memory, that can substantially weaken the protections afforded by
pointer authentication.
- If an attacker can inject their own executable code, they can also certainly
- inject code that can be used as a {ref}`signing oracle<Signing Oracles>`.
+ inject code that can be used as a {ref}`signing oracle <signing-oracles>`.
The same is true if they can write to the instruction stream.
- If an attacker can remap read-only program data sections to be writable, then
- any use of {ref}`relative addresses` in global data becomes insecure.
+ any use of {ref}`relative addresses <relative-addresses>` in global data becomes insecure.
- On platforms that use them, if an attacker can remap the memory containing
the [global offset tables] as writable, then any unsigned pointers in those
tables are insecure.
@@ -1303,7 +1304,7 @@ but more importantly, it defines away the potential for several attacks:
attackers can search this pool for useful pointers that can be used in
[substitution attacks], whereas pointers that are only materialized directly
are not so easily available.
-- Similarly, attackers can use [access path attacks] to replace a pointer to a
+- Similarly, attackers can use {ref}`access path attacks <access-path-attacks>` to replace a pointer to a
signed pointer with a pointer to the GOT if the signing schema used within the
GOT happens to be the same as the original pointer. This kind of collision
becomes much less likely to be useful the fewer pointers are in the GOT in the
@@ -1330,7 +1331,7 @@ be taken to ensure that using the GOT does not introduce weaknesses.
substitution attacks, it's best if GOT entries can be signed with address
diversity. Using a good constant discriminator as well (perhaps derived from
the symbol name) can make it less useful to use a pointer to the GOT as the
- replacement in an {ref}`access path attack<Access path attacks>`.
+ replacement in an {ref}`access path attack <access-path-attacks>`.
In either case, the compiler must ensure that materializing the address of a GOT
entry as part of producing a signed pointer constant is not vulnerable to
@@ -1344,12 +1345,12 @@ necessary for them to define the pointer authentication semantics of the APIs
provided to perform such lookups. While the platform may choose to reply
unsigned pointers from such function and rely on the caller performing the
initial signing, doing so creates the opportunity for caller side errors that
-create {ref}`signing oracles<Signing Oracles>`.
+create {ref}`signing oracles <signing-oracles>`.
On arm64e the `dlsym` function is used to resolve a symbol at runtime. If the
resolved symbol is a function or other code pointer the returned pointer is
signed using the default function signing schema described in
-{ref}`C function pointers<C function abi>`. If the resolved symbol is not a code pointer it is
+{ref}`C function pointers <c-function-abi>`. If the resolved symbol is not a code pointer it is
returned as an unsigned pointer.
(c-function-abi)=
@@ -1469,7 +1470,7 @@ mode evalutes to.
Block pointers are data pointers which must interoperate with the ObjC `id` type
and therefore cannot be signed themselves. As blocks conform to the ObjC `id`
type, they contain an `isa` pointer signed as described
-{ref}`below<Objc isa and super>`.
+{ref}`below <objc-isa-and-super>`.
The invocation pointer in a block is signed with the `IA` key using address
diversity and a constant discriminator of 0. Using a uniform discriminator is
@@ -1523,7 +1524,7 @@ that store selectors, as in the common target-action design pattern. This
prevents attackers from overriding the selector to invoke an arbitrary different
method, which is a major attack vector in Objective-C. Since `SEL` values are
not normally passed around as signed pointers, there is a
-{ref}`signing oracle<Signing Oracles>` associated with the initialization of the
+{ref}`signing oracle <signing-oracles>` associated with the initialization of the
ivar, but the use of address and constant diversity limit the risks.
The implicit qualifier means that the type of the ivar does not match its
@@ -1554,7 +1555,7 @@ void f(SEL __ptrauth_objc_sel*);
```
or less safely, and introducing the possibility of an
-{ref}`signing or authentication oracle<Signing oracles>`, an unauthenticated
+{ref}`signing or authentication oracle <signing-oracles>`, an unauthenticated
temporary may be used as intermediate storage.
## Alternative implementations
@@ -1612,4 +1613,3 @@ with this idea:
`auth`-and-load instruction can perform the load and `auth` in parallel;
a processor which instead encrypted the pointer would be forced to perform
these operations serially.
-
diff --git a/clang/docs/SYCLSupport.md b/clang/docs/SYCLSupport.md
index f3506c8fcaa18..57ff207457979 100644
--- a/clang/docs/SYCLSupport.md
+++ b/clang/docs/SYCLSupport.md
@@ -1,7 +1,7 @@
# SYCL Compiler and Runtime architecture design
```{contents}
-:local: true
+:local:
```
## Introduction
@@ -114,4 +114,3 @@ space attributes for pointers:
```C++
//TODO: add support for __attribute__((opencl_global_host)) and __attribute__((opencl_global_device)).
```
-
diff --git a/clang/docs/SafeStack.md b/clang/docs/SafeStack.md
index f859a8cb5321c..f93464eea9993 100644
--- a/clang/docs/SafeStack.md
+++ b/clang/docs/SafeStack.md
@@ -1,7 +1,7 @@
# SafeStack
```{contents}
-:local: true
+:local:
```
## Introduction
@@ -206,4 +206,3 @@ in the function `SafeStack::createStackRestorePoints`.
Volodymyr Kuznetsov, Laszlo Szekeres, Mathias Payer, George Candea, R. Sekar, Dawn Song.
USENIX Symposium on Operating Systems Design and Implementation
([OSDI](https://www.usenix.org/conference/osdi14)), Broomfield, CO, October 2014
-
diff --git a/clang/docs/SanitizerSpecialCaseList.md b/clang/docs/SanitizerSpecialCaseList.md
index c9c866be05ade..989a73d15a886 100644
--- a/clang/docs/SanitizerSpecialCaseList.md
+++ b/clang/docs/SanitizerSpecialCaseList.md
@@ -1,7 +1,7 @@
# Sanitizer special case list
```{contents}
-:local: true
+:local:
```
## Introduction
@@ -169,8 +169,8 @@ and lines starting with "#" are ignored.
:::{note}
Prior to Clang 18, section names and entries described below use a variant of
-regex where `*` is translated to `.*`. Clang 18 (`D154014
-<https://reviews.llvm.org/D154014>`) switches to glob and plans to remove
+regex where `*` is translated to `.*`. Clang 18
+([D154014](https://reviews.llvm.org/D154014)) switches to glob and plans to remove
regex support in Clang 19.
For Clang 18, regex is supported if `#!special-case-list-v1` is the first
@@ -267,4 +267,3 @@ e.g. when patterns are picked in a way to ensure the prevailing one is ignored.
`mainfile` can be useful enabling a ubsan check for a large code base when
finding the direct stack frame triggering the failure for every failure is
difficult.
-
diff --git a/clang/docs/SanitizerStats.md b/clang/docs/SanitizerStats.md
index 5dc1cc34e83b4..12a1262c9fdf1 100644
--- a/clang/docs/SanitizerStats.md
+++ b/clang/docs/SanitizerStats.md
@@ -1,7 +1,7 @@
# SanitizerStats
```{contents}
-:local: true
+:local:
```
## Introduction
@@ -20,8 +20,8 @@ At run time, set the `SANITIZER_STATS_PATH` environment variable to direct
statistics output to a file. The file will be written on process exit.
The following substitutions will be applied to the environment variable:
-> - `%b` -- The executable basename.
-> - `%p` -- The process ID.
+- `%b` -- The executable basename.
+- `%p` -- The process ID.
You can also send the `SIGUSR2` signal to a process to make it write
sanitizer statistics immediately.
diff --git a/clang/docs/ShadowCallStack.md b/clang/docs/ShadowCallStack.md
index a9b4af4d72c3d..bcb6c480b4e8b 100644
--- a/clang/docs/ShadowCallStack.md
+++ b/clang/docs/ShadowCallStack.md
@@ -1,7 +1,7 @@
# ShadowCallStack
```{contents}
-:local: true
+:local:
```
## Introduction
@@ -208,4 +208,3 @@ ret
[return flow guard]: https://xlab.tencent.com/en/2016/11/02/return-flow-guard/
[will do this]: https://android-review.googlesource.com/c/platform/bionic/+/891622
[zicfiss]: https://github.com/riscv/riscv-cfi/blob/main/cfi_backward.adoc
-
diff --git a/clang/docs/SourceBasedCodeCoverage.md b/clang/docs/SourceBasedCodeCoverage.md
index 4853149711fee..aa1da1e4673ff 100644
--- a/clang/docs/SourceBasedCodeCoverage.md
+++ b/clang/docs/SourceBasedCodeCoverage.md
@@ -1,7 +1,7 @@
# Source-based Code Coverage
```{contents}
-:local: true
+:local:
```
## Introduction
@@ -503,4 +503,3 @@ branch region is generated to correspond to the implicit default case that is
generated by the compiler. The implicit branch region is tied to the line and
column number of the switch statement condition since no source code for the
implicit case exists.
-
diff --git a/clang/docs/StandardCPlusPlusModules.md b/clang/docs/StandardCPlusPlusModules.md
index 6997ec3ced24e..af1df6d5ed464 100644
--- a/clang/docs/StandardCPlusPlusModules.md
+++ b/clang/docs/StandardCPlusPlusModules.md
@@ -1,14 +1,14 @@
# Standard C++ Modules
```{contents}
-:local: true
+:local:
```
## Introduction
The term `module` is ambiguous, as it is used to mean multiple things in
Clang. For Clang users, a module may refer to an `Objective-C Module`,
-[Clang Module](Modules.html) (also called a `Clang Header Module`) or a
+{doc}`Clang Module <Modules>` (also called a `Clang Header Module`) or a
`C++20 Module` (or a `Standard C++ Module`). The implementation of all
these kinds of modules in Clang shares a lot of code, but from the perspective
of users their semantics and command line interfaces are very different. This
@@ -1510,7 +1510,7 @@ clang module map.
#### Clang Module Map Background
-Clang Module Map is a feature of Clang Header Modules. See [Clang Module](Modules.html)
+Clang Module Map is a feature of Clang Header Modules. See {doc}`Clang Module <Modules>`
for full introduction of Clang Header Modules. Here we would only introduce Clang Header
Modules to make this document self contained.
@@ -2048,7 +2048,7 @@ JSON file conforming to the specification described in
Only named modules are supported currently.
A compilation database is needed when using `clang-scan-deps`. See
-[JSON Compilation Database Format Specification](JSONCompilationDatabase.html)
+{doc}`JSON Compilation Database Format Specification <JSONCompilationDatabase>`
for more information about compilation databases. Note that the `output`
JSON attribute is necessary for `clang-scan-deps` to scan using the P1689
format. For example:
@@ -2438,4 +2438,3 @@ optimization opportunities.
We **wish** to support Clang modules and standard C++ modules at the same time,
but the mixing them together is not well used/tested yet. Please file new
GitHub issues as you find interoperability problems.
-
diff --git a/clang/docs/StructureProtection.md b/clang/docs/StructureProtection.md
index 8d541c0e7a206..9b0d79f7e39ba 100644
--- a/clang/docs/StructureProtection.md
+++ b/clang/docs/StructureProtection.md
@@ -1,7 +1,7 @@
# Structure Protection
```{contents}
-:local: true
+:local:
```
## Introduction
@@ -84,4 +84,3 @@ These symbols are named as follows:
`__pfp_ds_` followed by the ABI encoding of the type's RTTI object
symbol name followed by `.` followed by the name of the field.
-
diff --git a/clang/docs/ThinLTO.md b/clang/docs/ThinLTO.md
index 905874e1c538a..9580b02e2b61b 100644
--- a/clang/docs/ThinLTO.md
+++ b/clang/docs/ThinLTO.md
@@ -1,7 +1,7 @@
# ThinLTO
```{contents}
-:local: true
+:local:
```
## Introduction
@@ -278,4 +278,3 @@ See [DTLTO](https://lld.llvm.org/DTLTO.html) for more information.
- From LLVM project blog:
[ThinLTO: Scalable and Incremental LTO](http://blog.llvm.org/2016/06/thinlto-scalable-and-incremental-lto.html)
-
diff --git a/clang/docs/UsersManual.md b/clang/docs/UsersManual.md
index 8aaeefbf6b426..bf5057e0c8d77 100644
--- a/clang/docs/UsersManual.md
+++ b/clang/docs/UsersManual.md
@@ -1,11 +1,7 @@
# Clang Compiler User's Manual
-```{eval-rst}
-.. include:: <isonum.txt>
-```
-
```{contents}
-:local: true
+:local:
```
## Introduction
@@ -203,9 +199,10 @@ options like {option}`-c`, {option}`-g`, etc.
```{eval-rst}
.. option:: --warning-suppression-mappings=foo.txt
- :ref:`Suppress certain diagnostics for certain files. <warning_suppression_mappings>`
+ :doc:`Suppress certain diagnostics for certain files. <WarningSuppressionMappings>`
```
+(cl_diag_formatting)=
(cl-diag-formatting)=
#### Formatting of Diagnostics
@@ -217,6 +214,7 @@ but by a program that wants consistent and easily parsable output. For
these cases, Clang provides a wide range of options to control the exact
output format of the diagnostics that it generates.
+(opt_fshow-column)=
(opt-fshow-column)=
```{eval-rst}
@@ -242,6 +240,7 @@ output format of the diagnostics that it generates.
line; take care if your source contains multibyte characters.
```
+(opt_fshow-source-location)=
(opt-fshow-source-location)=
```{eval-rst}
@@ -264,6 +263,7 @@ output format of the diagnostics that it generates.
part.
```
+(opt_fcaret-diagnostics)=
(opt-fcaret-diagnostics)=
```{eval-rst}
@@ -351,6 +351,7 @@ output format of the diagnostics that it generates.
t.c +3:11: warning: conversion specifies type 'char *' but the argument has type 'int'
```
+(opt_fdiagnostics-show-option)=
(opt-fdiagnostics-show-option)=
```{eval-rst}
@@ -402,6 +403,7 @@ output format of the diagnostics that it generates.
of these, not hundreds or thousands of them.
```
+(opt_fsave-optimization-record)=
(opt-fsave-optimization-record)=
```{eval-rst}
@@ -501,6 +503,7 @@ output format of the diagnostics that it generates.
record.
```
+(opt_fdiagnostics-show-hotness)=
(opt-fdiagnostics-show-hotness)=
```{eval-rst}
@@ -543,6 +546,7 @@ output format of the diagnostics that it generates.
:ref:`-fdiagnostics-show-hotness <opt_fdiagnostics-show-hotness>`).
```
+(opt_fdiagnostics-fixit-info)=
(opt-fdiagnostics-fixit-info)=
```{eval-rst}
@@ -567,6 +571,7 @@ output format of the diagnostics that it generates.
confusing for machine parsing.
```
+(opt_fdiagnostics-print-source-range-info)=
(opt-fdiagnostics-print-source-range-info)=
```{eval-rst}
@@ -706,6 +711,7 @@ output format of the diagnostics that it generates.
```
+(cl_diag_warning_groups)=
(cl-diag-warning-groups)=
#### Individual Warning Groups
@@ -1276,6 +1282,7 @@ All diagnostics are mapped into one of these 6 classes:
- Error
- Fatal
+(diagnostics_categories)=
(diagnostics-categories)=
#### Diagnostic Categories
@@ -1296,6 +1303,7 @@ by running '`clang --print-diagnostic-categories`'.
TODO: -W flags, -pedantic, etc
+(pragma_GCC_diagnostic)=
(pragma-gcc-diagnostic)=
#### Controlling Diagnostics via Pragmas
@@ -1451,6 +1459,7 @@ include directives in the translation unit.
#include <stdatomic.h> // Clang CRT deprecation warnings are disabled.
```
+(diagnostics_enable_everything)=
(diagnostics-enable-everything)=
#### Enabling All Diagnostics
@@ -1505,8 +1514,8 @@ functionality.
While not strictly part of the compiler, the diagnostics from Clang's
[static analyzer](https://clang-analyzer.llvm.org) can also be
influenced by the user via changes to the source code. See the available
-[annotations](analyzer/user-docs/Annotations.html) and the analyzer's
-[FAQ page](analyzer/user-docs/FAQ.html#exclude-code) for more information.
+{doc}`annotations <analyzer/user-docs/Annotations>` and the analyzer's
+{ref}`FAQ page <exclude_code>` for more information.
(usersmanual-precompiled-headers)=
@@ -2208,6 +2217,7 @@ Code that just wants to use a specific rounding mode for specific floating point
operations can avoid most of the hazards of the dynamic floating point environment
by using `#pragma STDC FENV_ROUND` with a value other than `FE_DYNAMIC`.
+(crtfastmath.o)=
(crtfastmath-o)=
#### A note about `crtfastmath.o`
@@ -2830,6 +2840,7 @@ are listed below.
only has an effect on ELF targets.
```
+(funique_internal_linkage_names)=
(funique-internal-linkage-names)=
```{eval-rst}
@@ -2969,6 +2980,7 @@ are listed below.
``aligned`` attribute, this option is ignored.
```
+(strict_aliasing)=
(strict-aliasing)=
### Strict Aliasing
@@ -3511,7 +3523,7 @@ instrumentation:
compiled with the build ID linker option (`--build-id` for GNU ld or LLD,
`/build-id` for lld-link on Windows). Linux, Windows and AIX are supported.
- See [this](SourceBasedCodeCoverage.html#running-the-instrumented-program) section
+ See [this](SourceBasedCodeCoverage.md#running-the-instrumented-program) section
about the `%t`, and `%c` modifiers.
3. Combine profiles from multiple runs and convert the "raw" profile format to
@@ -4141,7 +4153,7 @@ features. You can "tune" the debug info for one of several different debuggers.
```{eval-rst}
.. option:: -ggdb, -glldb, -gsce, -gdbx
- Tune the debug info for the ``gdb``, ``lldb``, Sony PlayStation\ |reg|
+ Tune the debug info for the ``gdb``, ``lldb``, Sony PlayStation®
debugger, or ``dbx``, respectively. Each of these options implies **-g**.
(Therefore, if you want both **-gline-tables-only** and debugger tuning, the
tuning option must come first.)
@@ -4385,6 +4397,7 @@ bugs.
local_function(1);
```
+(c_ms)=
(c-ms)=
### Microsoft extensions
@@ -4591,6 +4604,7 @@ Some extra options are available to support special OpenCL features.
section on the OpenCL Header <opencl_header>`.
```
+(opencl_cl_ext)=
(opencl-cl-ext)=
```{eval-rst}
@@ -4683,6 +4697,7 @@ There is a set of concrete HW architectures that OpenCL can be compiled for.
however {option}`-cl-ext` flag can be used to toggle individual extensions and
features.
+(opencl_header)=
(opencl-header)=
### OpenCL Header
@@ -4835,6 +4850,7 @@ CFG that modify semantics of the original program.
`noduplicate` is kept for backwards compatibility only and it considered to be
deprecated for future uses.
+(cxx_for_opencl)=
(cxx-for-opencl)=
### C++ for OpenCL
@@ -4943,6 +4959,7 @@ However, all memory used for program scope objects should be released on
Limited experimental support of C++ standard libraries for OpenCL is
described in {doc}`OpenCLSupport` page.
+(target_features)=
(target-features)=
## Target-Specific Features and Limitations
@@ -6449,4 +6466,3 @@ The Visual C++ Toolset has a slightly more elaborate mechanism for detection.
Strict aliasing (TBAA) is always off by default in clang-cl whereas in clang,
strict aliasing is turned on by default for all optimization levels. For more
details, see {ref}`Strict aliasing <strict_aliasing>`.
-
>From 75b8210efa12dfacc03350f9a4b0f5d1fb2c51c3 Mon Sep 17 00:00:00 2001
From: Reid Kleckner <rkleckner at nvidia.com>
Date: Wed, 8 Jul 2026 22:05:56 +0000
Subject: [PATCH 4/5] Fix header links, update tables, reformat URLs
---
clang/docs/HIPSupport.md | 199 ++++----
clang/docs/MSVCCompatibility.md | 10 +-
clang/docs/Modules.md | 18 +-
clang/docs/OpenCLSupport.md | 93 ++--
clang/docs/OpenMPSupport.md | 649 +++++++++++++++----------
clang/docs/OverflowBehaviorTypes.md | 47 +-
clang/docs/PointerAuthentication.md | 52 +-
clang/docs/SYCLSupport.md | 25 +-
clang/docs/ShadowCallStack.md | 43 +-
clang/docs/StandardCPlusPlusModules.md | 2 +-
clang/docs/ThinLTO.md | 8 +-
clang/docs/UsersManual.md | 68 ++-
12 files changed, 639 insertions(+), 575 deletions(-)
diff --git a/clang/docs/HIPSupport.md b/clang/docs/HIPSupport.md
index 40abe87f2b14d..6d5290221e687 100644
--- a/clang/docs/HIPSupport.md
+++ b/clang/docs/HIPSupport.md
@@ -6,16 +6,13 @@
</style>
```
-```{eval-rst}
-.. role:: none
+```{role} none
```
-```{eval-rst}
-.. role:: part
+```{role} part
```
-```{eval-rst}
-.. role:: good
+```{role} good
```
```{contents}
@@ -116,26 +113,25 @@ if they follow the ROCm installation directory structure.
4. `ROCM_PATH` environment variable *(use with caution)*
5. Default automatic detection (relative to Clang or at the default ROCm installation location)
-```{eval-rst}
-.. list-table::
- :header-rows: 1
-
- * - Compiler Option
- - Environment Variable
- - Description
- - Default Value
- * - ``--rocm-path=<path>``
- - ``ROCM_PATH``
- - Specifies the ROCm installation path.
- - Automatic detection
- * - ``--hip-path=<path>``
- - ``HIP_PATH``
- - Specifies the HIP runtime installation path.
- - Determined by ROCm directory structure
- * - ``--hip-device-lib-path=<path>``
- - ``HIP_DEVICE_LIB_PATH``
- - Specifies the HIP device library installation path.
- - Determined by ROCm directory structure
+```{list-table}
+:header-rows: 1
+
+* - Compiler Option
+ - Environment Variable
+ - Description
+ - Default Value
+* - `--rocm-path=<path>`
+ - `ROCM_PATH`
+ - Specifies the ROCm installation path.
+ - Automatic detection
+* - `--hip-path=<path>`
+ - `HIP_PATH`
+ - Specifies the HIP runtime installation path.
+ - Determined by ROCm directory structure
+* - `--hip-device-lib-path=<path>`
+ - `HIP_DEVICE_LIB_PATH`
+ - Specifies the HIP device library installation path.
+ - Determined by ROCm directory structure
```
:::{note}
@@ -144,40 +140,44 @@ We recommend using the compiler options as the primary method for specifying the
## Predefined Macros
-```{eval-rst}
-.. list-table::
- :header-rows: 1
-
- * - Macro
- - Description
- * - ``__CLANG_RDC__``
- - Defined when Clang is compiling code in Relocatable Device Code (RDC) mode. RDC, enabled with the ``-fgpu-rdc`` compiler option, is necessary for linking device codes across translation units.
- * - ``__HIP__``
- - Defined when compiling with HIP language support, indicating that the code targets the HIP environment.
- * - ``__HIPCC__``
- - Alias to ``__HIP__``.
- * - ``__HIP_DEVICE_COMPILE__``
- - Defined during device code compilation in Clang's separate compilation process for the host and each offloading GPU architecture.
- * - ``__HIP_MEMORY_SCOPE_SINGLETHREAD``
- - Represents single-thread memory scope in HIP (value is 1).
- * - ``__HIP_MEMORY_SCOPE_WAVEFRONT``
- - Represents wavefront memory scope in HIP (value is 2).
- * - ``__HIP_MEMORY_SCOPE_WORKGROUP``
- - Represents workgroup memory scope in HIP (value is 3).
- * - ``__HIP_MEMORY_SCOPE_CLUSTER``
- - Represents cluster memory scope in HIP (value is 6).
- * - ``__HIP_MEMORY_SCOPE_AGENT``
- - Represents agent memory scope in HIP (value is 4).
- * - ``__HIP_MEMORY_SCOPE_SYSTEM``
- - Represents system-wide memory scope in HIP (value is 5).
- * - ``__HIP_NO_IMAGE_SUPPORT__``
- - Defined with a value of 1 when the target device lacks support for HIP image functions.
- * - ``__HIP_NO_IMAGE_SUPPORT``
- - Alias to ``__HIP_NO_IMAGE_SUPPORT__``. Deprecated.
- * - ``__HIP_API_PER_THREAD_DEFAULT_STREAM__``
- - Defined when the GPU default stream is set to per-thread mode.
- * - ``HIP_API_PER_THREAD_DEFAULT_STREAM``
- - Alias to ``__HIP_API_PER_THREAD_DEFAULT_STREAM__``. Deprecated.
+```{list-table}
+:header-rows: 1
+
+* - Macro
+ - Description
+* - `__CLANG_RDC__`
+ - Defined when Clang is compiling code in Relocatable Device Code (RDC)
+ mode. RDC, enabled with the `-fgpu-rdc` compiler option, is necessary for
+ linking device codes across translation units.
+* - `__HIP__`
+ - Defined when compiling with HIP language support, indicating that the code
+ targets the HIP environment.
+* - `__HIPCC__`
+ - Alias to `__HIP__`.
+* - `__HIP_DEVICE_COMPILE__`
+ - Defined during device code compilation in Clang's separate compilation
+ process for the host and each offloading GPU architecture.
+* - `__HIP_MEMORY_SCOPE_SINGLETHREAD`
+ - Represents single-thread memory scope in HIP (value is 1).
+* - `__HIP_MEMORY_SCOPE_WAVEFRONT`
+ - Represents wavefront memory scope in HIP (value is 2).
+* - `__HIP_MEMORY_SCOPE_WORKGROUP`
+ - Represents workgroup memory scope in HIP (value is 3).
+* - `__HIP_MEMORY_SCOPE_CLUSTER`
+ - Represents cluster memory scope in HIP (value is 6).
+* - `__HIP_MEMORY_SCOPE_AGENT`
+ - Represents agent memory scope in HIP (value is 4).
+* - `__HIP_MEMORY_SCOPE_SYSTEM`
+ - Represents system-wide memory scope in HIP (value is 5).
+* - `__HIP_NO_IMAGE_SUPPORT__`
+ - Defined with a value of 1 when the target device lacks support for HIP
+ image functions.
+* - `__HIP_NO_IMAGE_SUPPORT`
+ - Alias to `__HIP_NO_IMAGE_SUPPORT__`. Deprecated.
+* - `__HIP_API_PER_THREAD_DEFAULT_STREAM__`
+ - Defined when the GPU default stream is set to per-thread mode.
+* - `HIP_API_PER_THREAD_DEFAULT_STREAM`
+ - Alias to `__HIP_API_PER_THREAD_DEFAULT_STREAM__`. Deprecated.
```
Note that some architecture specific AMDGPU macros will have default values when
@@ -327,21 +327,10 @@ To facilitate differentiation between HIP and CUDA code, as well as between devi
Function pointers' support varies with the usage mode in Clang with HIP. The following table provides an overview of the support status across different use-cases and modes.
-```{eval-rst}
-.. list-table:: Function Pointers Support Overview
- :widths: 25 25 25
- :header-rows: 1
-
- * - Use Case
- - ``-fno-gpu-rdc`` Mode (default)
- - ``-fgpu-rdc`` Mode
- * - Defined and used in the same TU
- - Supported
- - Supported
- * - Defined in one TU and used in another TU
- - Not Supported
- - Supported
-```
+| Use Case | `-fno-gpu-rdc` Mode (default) | `-fgpu-rdc` Mode |
+| ---------------------------------------- | ----------------------------- | ---------------- |
+| Defined and used in the same TU | Supported | Supported |
+| Defined in one TU and used in another TU | Not Supported | Supported |
In the `-fno-gpu-rdc` mode, the compiler calculates the resource usage of kernels based only on functions present within the same TU. This mode does not support the use of function pointers defined in a different TU due to the possibility of incorrect resource usage calculations, leading to undefined behavior.
@@ -764,21 +753,19 @@ The forwarding header implements two pieces of functionality:
## Predefined Macros
-```{eval-rst}
-.. list-table::
- :header-rows: 1
-
- * - Macro
- - Description
- * - ``__HIPSTDPAR__``
- - Defined when Clang is compiling code in algorithm offload mode, enabled
- with the ``--hipstdpar`` compiler option.
- * - ``__HIPSTDPAR_INTERPOSE_ALLOC__`` / ``__HIPSTDPAR_INTERPOSE_ALLOC_V1__``
- - Defined only when compiling in algorithm offload mode, when the user
- enables interposition mode with the ``--hipstdpar-interpose-alloc``
- compiler option, indicating that all dynamic memory allocation /
- deallocation functions should be replaced with accelerator aware
- variants.
+```{list-table}
+:header-rows: 1
+
+* - Macro
+ - Description
+* - `__HIPSTDPAR__`
+ - Defined when Clang is compiling code in algorithm offload mode, enabled
+ with the `--hipstdpar` compiler option.
+* - `__HIPSTDPAR_INTERPOSE_ALLOC__` / `__HIPSTDPAR_INTERPOSE_ALLOC_V1__`
+ - Defined only when compiling in algorithm offload mode, when the user
+ enables interposition mode with the `--hipstdpar-interpose-alloc` compiler
+ option, indicating that all dynamic memory allocation / deallocation
+ functions should be replaced with accelerator aware variants.
```
## Restrictions
@@ -832,29 +819,13 @@ At the moment, C++ Standard Parallelism Offload is only available for AMD GPUs,
when the [ROCm](https://rocm.docs.amd.com/en/latest/) stack is used, on the
Linux operating system. Support is synthesised in the following table:
-```{eval-rst}
-.. list-table::
- :header-rows: 1
-
- * - `Processor <https://llvm.org/docs/AMDGPUUsage.html#amdgpu-processors>`_
- - HMM Mode
- - Interposition Mode
- * - GCN GFX9 (Vega)
- - YES
- - YES
- * - GCN GFX10.1 (RDNA 1)
- - *NO*
- - YES
- * - GCN GFX10.3 (RDNA 2)
- - *NO*
- - YES
- * - GCN GFX11 (RDNA 3)
- - *NO*
- - YES
- * - GCN GFX12 (RDNA 4)
- - *NO*
- - YES
-```
+| [Processor](https://llvm.org/docs/AMDGPUUsage.html#amdgpu-processors) | HMM Mode | Interposition Mode |
+| ---------------------------------------------------------------------- | -------- | ------------------ |
+| GCN GFX9 (Vega) | YES | YES |
+| GCN GFX10.1 (RDNA 1) | *NO* | YES |
+| GCN GFX10.3 (RDNA 2) | *NO* | YES |
+| GCN GFX11 (RDNA 3) | *NO* | YES |
+| GCN GFX12 (RDNA 4) | *NO* | YES |
The minimum Linux kernel version for running in HMM mode is 6.4.
@@ -1058,7 +1029,7 @@ consumed by `llvm-profdata` and `llvm-cov`.
Source-based device coverage relies on the AMDGPU profile runtime, so
the toolchain must be built with the same CMake configuration used for
HIP offload PGO. See the *Prerequisites* subsection under
-[Profile-Guided Optimization for Device Code].
+[Profile-Guided Optimization for Device Code](#profile-guided-optimization-for-device-code).
### Example
diff --git a/clang/docs/MSVCCompatibility.md b/clang/docs/MSVCCompatibility.md
index 86dd32f4a7267..e9b3f0d094df6 100644
--- a/clang/docs/MSVCCompatibility.md
+++ b/clang/docs/MSVCCompatibility.md
@@ -6,16 +6,13 @@
</style>
```
-```{eval-rst}
-.. role:: none
+```{role} none
```
-```{eval-rst}
-.. role:: partial
+```{role} partial
```
-```{eval-rst}
-.. role:: good
+```{role} good
```
# MSVC compatibility
@@ -273,4 +270,3 @@ In general the takeaway is `__m128` is a builtin type on clang while a class typ
[consistent with visual c++]: https://msdn.microsoft.com/en-us/library/wfa0edys.aspx
[frequently asked question]: https://clang.llvm.org/compatibility.html#dep_lookup
[pointer to a member of a virtual base class]: https://llvm.org/PR15713
-
diff --git a/clang/docs/Modules.md b/clang/docs/Modules.md
index 2bc780dfccb45..e4db0628de16d 100644
--- a/clang/docs/Modules.md
+++ b/clang/docs/Modules.md
@@ -91,7 +91,7 @@ Many programming languages have a module or package system, and because of the v
## Using Modules
-To enable modules, pass the command-line flag `-fmodules`. This will make any modules-enabled software libraries available as modules as well as introducing any modules-specific syntax. Additional [command-line parameters] are described in a separate section later.
+To enable modules, pass the command-line flag `-fmodules`. This will make any modules-enabled software libraries available as modules as well as introducing any modules-specific syntax. Additional [command-line parameters](#command-line-parameters) are described in a separate section later.
### Standard C++ Modules
@@ -121,7 +121,7 @@ Redundant import declarations are ignored, and one is free to import modules at
At present, there is no C or C++ syntax for import declarations. Clang
will track the modules proposal in the C++ committee. See the section
-[Includes as imports] to see how modules get imported today.
+[Includes as imports](#includes-as-imports) to see how modules get imported today.
### Includes as imports
@@ -154,10 +154,10 @@ directive.
The crucial link between modules and headers is described by a *module map*, which describes how a collection of existing headers maps on to the (logical) structure of a module. For example, one could imagine a module `std` covering the C standard library. Each of the C standard library headers (`<stdio.h>`, `<stdlib.h>`, `<math.h>`, etc.) would contribute to the `std` module, by placing their respective APIs into the corresponding submodule (`std.io`, `std.lib`, `std.math`, etc.). Having a list of the headers that are part of the `std` module allows the compiler to build the `std` module as a standalone entity, and having the mapping from header names to (sub)modules allows the automatic translation of `#include` directives to module imports.
-Module maps are specified as separate files (each named `module.modulemap`) alongside the headers they describe, which allows them to be added to existing software libraries without having to change the library headers themselves (in most cases [^footnote-2]). The actual [Module map language] is described in a later section.
+Module maps are specified as separate files (each named `module.modulemap`) alongside the headers they describe, which allows them to be added to existing software libraries without having to change the library headers themselves (in most cases [^footnote-2]). The actual [Module map language](#module-map-language) is described in a later section.
:::{note}
-To actually see any benefits from modules, one first has to introduce module maps for the underlying C standard library and the libraries and headers on which it depends. The section [Modularizing a Platform] describes the steps one must take to write these module maps.
+To actually see any benefits from modules, one first has to introduce module maps for the underlying C standard library and the libraries and headers on which it depends. The section [Modularizing a Platform](#modularizing-a-platform) describes the steps one must take to write these module maps.
:::
One can use module maps without modules to check the integrity of the use of header files. To do this, use the `-fimplicit-module-maps` option instead of the `-fmodules` option, or use `-fmodule-map-file=` option to explicitly specify the module map files to load.
@@ -523,7 +523,7 @@ The `framework` qualifier specifies that this module corresponds to a Darwin-sty
Name Symbolic link to the shared library for the framework
```
-The `system` attribute specifies that the module is a system module. When a system module is rebuilt, all of the module's headers will be considered system headers, which suppresses warnings. This is equivalent to placing `#pragma GCC system_header` in each of the module's headers. The form of attributes is described in the section [Attributes], below.
+The `system` attribute specifies that the module is a system module. When a system module is rebuilt, all of the module's headers will be considered system headers, which suppresses warnings. This is equivalent to placing `#pragma GCC system_header` in each of the module's headers. The form of attributes is described in the section [Attributes](#attributes), below.
The `extern_c` attribute specifies that the module contains C code that can be used from within C++. When such a module is built for use in C++ code, all of the module's headers will be treated as if they were contained within an implicit `extern "C"` block. An import for a module with this attribute can appear within an `extern "C"` block. No other restrictions are lifted, however: the module currently cannot be imported within an `extern "C"` block in a namespace.
@@ -769,7 +769,7 @@ The *string-literal* refers to a directory. When the module is built, all of the
:::{note}
Umbrella directory paths that use `..` to refer to directories outside of
the module directory are deprecated in implicitly discovered module maps.
-See the note in [Header declaration] for details.
+See the note in [Header declaration](#header-declaration) for details.
:::
An *umbrella-dir-declaration* shall not refer to the same directory as the location of an umbrella *header-declaration*. In other words, only a single kind of umbrella can be specified for a given directory.
@@ -1176,7 +1176,7 @@ When writing a private module as part of a *framework*, it's recommended that:
To get any benefit out of modules, one needs to introduce module maps for software libraries starting at the bottom of the stack. This typically means introducing a module map covering the operating system's headers and the C standard library headers (in `/usr/include`, for a Unix system).
-The module maps will be written using the [module map language], which provides the tools necessary to describe the mapping between headers and modules. Because the set of headers differs from one system to the next, the module map will likely have to be somewhat customized for, e.g., a particular distribution and version of the operating system. Moreover, the system headers themselves may require some modification, if they exhibit any anti-patterns that break modules. Such common patterns are described below.
+The module maps will be written using the [module map language](#module-map-language), which provides the tools necessary to describe the mapping between headers and modules. Because the set of headers differs from one system to the next, the module map will likely have to be somewhat customized for, e.g., a particular distribution and version of the operating system. Moreover, the system headers themselves may require some modification, if they exhibit any anti-patterns that break modules. Such common patterns are described below.
**Macro-guarded copy-and-pasted definitions**
@@ -1249,8 +1249,8 @@ The Clang source code provides additional information about modules:
[^footnote-1]: Automatic linking against the libraries of modules requires specific linker support, which is not widely available.
-[^footnote-2]: There are certain anti-patterns that occur in headers, particularly system headers, that cause problems for modules. The section [Modularizing a Platform] describes some of them.
+[^footnote-2]: There are certain anti-patterns that occur in headers, particularly system headers, that cause problems for modules. The section [Modularizing a Platform](#modularizing-a-platform) describes some of them.
[^footnote-3]: The second instance is actually a new thread within the current process, not a separate process. However, the original compiler instance is blocked on the execution of this thread.
-[^footnote-4]: The preprocessing context in which the modules are parsed is actually dependent on the command-line options provided to the compiler, including the language dialect and any `-D` options. However, the compiled modules for different command-line options are kept distinct, and any preprocessor directives that occur within the translation unit are ignored. See the section on the [Configuration macros declaration] for more information.
+[^footnote-4]: The preprocessing context in which the modules are parsed is actually dependent on the command-line options provided to the compiler, including the language dialect and any `-D` options. However, the compiled modules for different command-line options are kept distinct, and any preprocessor directives that occur within the translation unit are ignored. See the section on the [Configuration macros declaration](#configuration-macros-declaration) for more information.
diff --git a/clang/docs/OpenCLSupport.md b/clang/docs/OpenCLSupport.md
index 927ed1cc01edb..22014604c22c5 100644
--- a/clang/docs/OpenCLSupport.md
+++ b/clang/docs/OpenCLSupport.md
@@ -6,18 +6,6 @@
</style>
```
-```{eval-rst}
-.. role:: none
-```
-
-```{eval-rst}
-.. role:: part
-```
-
-```{eval-rst}
-.. role:: good
-```
-
```{contents}
:local:
```
@@ -345,45 +333,48 @@ user should specify both (extension and feature) in command-line flag:
The following table provides an overview of features in OpenCL C 3.0 and their
implementation status.
-```{eval-rst}
-+------------------------------+-------------------------+-----------------------------------------+----------------------+--------------------------------------------------------------------------------------------------------------------------------+
-| Category | Feature | Status | Reviews |
-+==============================+=========================+=========================================+======================+================================================================================================================================+
-| Command line interface | New value for ``-cl-std`` flag | :good:`done` | https://reviews.llvm.org/D88300 |
-+------------------------------+-------------------------+-----------------------------------------+----------------------+--------------------------------------------------------------------------------------------------------------------------------+
-| Predefined macros | New version macro | :good:`done` | https://reviews.llvm.org/D88300 |
-+------------------------------+-------------------------+-----------------------------------------+----------------------+--------------------------------------------------------------------------------------------------------------------------------+
-| Predefined macros | Feature macros | :good:`done` | https://reviews.llvm.org/D95776 |
-+------------------------------+-------------------------+-----------------------------------------+----------------------+--------------------------------------------------------------------------------------------------------------------------------+
-| Feature optionality | Generic address space | :good:`done` | https://reviews.llvm.org/D95778 and https://reviews.llvm.org/D103401 |
-+------------------------------+-------------------------+-----------------------------------------+----------------------+--------------------------------------------------------------------------------------------------------------------------------+
-| Feature optionality | Builtin function overloads with generic address space | :good:`done` | https://reviews.llvm.org/D105526, https://reviews.llvm.org/D107769 |
-+------------------------------+-------------------------+-----------------------------------------+----------------------+--------------------------------------------------------------------------------------------------------------------------------+
-| Feature optionality | Program scope variables in global memory | :good:`done` | https://reviews.llvm.org/D103191 |
-+------------------------------+-------------------------+-----------------------------------------+----------------------+--------------------------------------------------------------------------------------------------------------------------------+
-| Feature optionality | 3D image writes including builtin functions | :good:`done` | https://reviews.llvm.org/D106260 (frontend) |
-+------------------------------+-------------------------+-----------------------------------------+----------------------+--------------------------------------------------------------------------------------------------------------------------------+
-| Feature optionality | read_write images including builtin functions | :good:`done` | https://reviews.llvm.org/D104915 (frontend) and https://reviews.llvm.org/D107539, https://reviews.llvm.org/D117899 (functions) |
-+------------------------------+-------------------------+-----------------------------------------+----------------------+--------------------------------------------------------------------------------------------------------------------------------+
-| Feature optionality | C11 atomics memory scopes, ordering and builtin function | :good:`done` | https://reviews.llvm.org/D106111, https://reviews.llvm.org/D119420 |
-+------------------------------+-------------------------+-----------------------------------------+----------------------+--------------------------------------------------------------------------------------------------------------------------------+
-| Feature optionality | Blocks and Device-side kernel enqueue including builtin functions | :good:`done` | https://reviews.llvm.org/D115640, https://reviews.llvm.org/D118605 |
-+------------------------------+-------------------------+-----------------------------------------+----------------------+--------------------------------------------------------------------------------------------------------------------------------+
-| Feature optionality | Pipes including builtin functions | :good:`done` | https://reviews.llvm.org/D107154 (frontend) and https://reviews.llvm.org/D105858 (functions) |
-+------------------------------+-------------------------+-----------------------------------------+----------------------+--------------------------------------------------------------------------------------------------------------------------------+
-| Feature optionality | Work group collective builtin functions | :good:`done` | https://reviews.llvm.org/D105858 |
-+------------------------------+-------------------------+-----------------------------------------+----------------------+--------------------------------------------------------------------------------------------------------------------------------+
-| Feature optionality | Image types and builtin functions | :good:`done` | https://reviews.llvm.org/D103911 (frontend) and https://reviews.llvm.org/D107539 (functions) |
-+------------------------------+-------------------------+-----------------------------------------+----------------------+--------------------------------------------------------------------------------------------------------------------------------+
-| Feature optionality | Double precision floating point type | :good:`done` | https://reviews.llvm.org/D96524 |
-+------------------------------+-------------------------+-----------------------------------------+----------------------+--------------------------------------------------------------------------------------------------------------------------------+
-| New functionality | RGBA vector components | :good:`done` | https://reviews.llvm.org/D99969 |
-+------------------------------+-------------------------+-----------------------------------------+----------------------+--------------------------------------------------------------------------------------------------------------------------------+
-| New functionality | Subgroup functions | :good:`done` | https://reviews.llvm.org/D105858, https://reviews.llvm.org/D118999 |
-+------------------------------+-------------------------+-----------------------------------------+----------------------+--------------------------------------------------------------------------------------------------------------------------------+
-| New functionality | Atomic mem scopes: subgroup, all devices including functions | :good:`done` | https://reviews.llvm.org/D103241 |
-+------------------------------+-------------------------+-----------------------------------------+----------------------+--------------------------------------------------------------------------------------------------------------------------------+
-```
+| Category | Feature | Status | Reviews |
+| ---------------------- | ----------------------------------------------------------------- | ------------------------------ | ------------------------------------------------------------------------------------ |
+| Command line interface | New value for `-cl-std` flag | <span class="good">done</span> | [D88300][D88300] |
+| Predefined macros | New version macro | <span class="good">done</span> | [D88300][D88300] |
+| Predefined macros | Feature macros | <span class="good">done</span> | [D95776][D95776] |
+| Feature optionality | Generic address space | <span class="good">done</span> | [D95778][D95778] and [D103401][D103401] |
+| Feature optionality | Builtin function overloads with generic address space | <span class="good">done</span> | [D105526][D105526], [D107769][D107769] |
+| Feature optionality | Program scope variables in global memory | <span class="good">done</span> | [D103191][D103191] |
+| Feature optionality | 3D image writes including builtin functions | <span class="good">done</span> | [D106260][D106260] (frontend) |
+| Feature optionality | read_write images including builtin functions | <span class="good">done</span> | [D104915][D104915] (frontend) and [D107539][D107539], [D117899][D117899] (functions) |
+| Feature optionality | C11 atomics memory scopes, ordering and builtin function | <span class="good">done</span> | [D106111][D106111], [D119420][D119420] |
+| Feature optionality | Blocks and Device-side kernel enqueue including builtin functions | <span class="good">done</span> | [D115640][D115640], [D118605][D118605] |
+| Feature optionality | Pipes including builtin functions | <span class="good">done</span> | [D107154][D107154] (frontend) and [D105858][D105858] (functions) |
+| Feature optionality | Work group collective builtin functions | <span class="good">done</span> | [D105858][D105858] |
+| Feature optionality | Image types and builtin functions | <span class="good">done</span> | [D103911][D103911] (frontend) and [D107539][D107539] (functions) |
+| Feature optionality | Double precision floating point type | <span class="good">done</span> | [D96524][D96524] |
+| New functionality | RGBA vector components | <span class="good">done</span> | [D99969][D99969] |
+| New functionality | Subgroup functions | <span class="good">done</span> | [D105858][D105858], [D118999][D118999] |
+| New functionality | Atomic mem scopes: subgroup, all devices including functions | <span class="good">done</span> | [D103241][D103241] |
+
+[D88300]: https://reviews.llvm.org/D88300
+[D95776]: https://reviews.llvm.org/D95776
+[D95778]: https://reviews.llvm.org/D95778
+[D103401]: https://reviews.llvm.org/D103401
+[D105526]: https://reviews.llvm.org/D105526
+[D107769]: https://reviews.llvm.org/D107769
+[D103191]: https://reviews.llvm.org/D103191
+[D106260]: https://reviews.llvm.org/D106260
+[D104915]: https://reviews.llvm.org/D104915
+[D107539]: https://reviews.llvm.org/D107539
+[D117899]: https://reviews.llvm.org/D117899
+[D106111]: https://reviews.llvm.org/D106111
+[D119420]: https://reviews.llvm.org/D119420
+[D115640]: https://reviews.llvm.org/D115640
+[D118605]: https://reviews.llvm.org/D118605
+[D107154]: https://reviews.llvm.org/D107154
+[D105858]: https://reviews.llvm.org/D105858
+[D103911]: https://reviews.llvm.org/D103911
+[D96524]: https://reviews.llvm.org/D96524
+[D99969]: https://reviews.llvm.org/D99969
+[D118999]: https://reviews.llvm.org/D118999
+[D103241]: https://reviews.llvm.org/D103241
(opencl_experimenal)=
(opencl-experimenal)=
diff --git a/clang/docs/OpenMPSupport.md b/clang/docs/OpenMPSupport.md
index 7832a6eced499..56ddbbd8c5f12 100644
--- a/clang/docs/OpenMPSupport.md
+++ b/clang/docs/OpenMPSupport.md
@@ -6,16 +6,13 @@
</style>
```
-```{eval-rst}
-.. role:: none
+```{role} none
```
-```{eval-rst}
-.. role:: part
+```{role} part
```
-```{eval-rst}
-.. role:: good
+```{role} good
```
```{contents}
@@ -83,75 +80,75 @@ and their implementation status. Please post on the
information or if you want to help with the
implementation.
-| Category | Feature | Status | Reviews |
-| ----------------- | ------------------------------------------------------------ | ----------------------- | -------------------------------------------------------------------- |
-| loop | support != in the canonical loop form | {good}`done` | D54441 |
-| loop | #pragma omp loop (directive) | {part}`partial` | D145823 (combined forms) |
-| loop | #pragma omp loop bind | {part}`worked on` | D144634 (needs review) |
-| loop | collapse imperfectly nested loop | {good}`done` | |
-| loop | collapse non-rectangular nested loop | {good}`done` | |
-| loop | C++ range-base for loop | {good}`done` | |
-| loop | clause: if for SIMD directives | {good}`done` | |
-| loop | inclusive scan (matching C++17 PSTL) | {good}`done` | |
-| memory management | memory allocators | {good}`done` | r341687,r357929 |
-| memory management | allocate directive and allocate clause | {good}`done` | r355614,r335952 |
-| OMPD | OMPD interfaces | {good}`done` | <https://reviews.llvm.org/D99914> (Supports only HOST(CPU) and Linux |
-| OMPT | OMPT interfaces (callback support) | {good}`done` | |
-| thread affinity | thread affinity | {good}`done` | |
-| task | taskloop reduction | {good}`done` | |
-| task | task affinity | {part}`not upstream` | <https://github.com/jklinkenberg/openmp/tree/task-affinity> |
-| task | clause: depend on the taskwait construct | {good}`done` | D113540 (regular codegen only) |
-| task | depend objects and detachable tasks | {good}`done` | |
-| task | mutexinoutset dependence-type for tasks | {good}`done` | D53380,D57576 |
-| task | combined taskloop constructs | {good}`done` | |
-| task | master taskloop | {good}`done` | |
-| task | parallel master taskloop | {good}`done` | |
-| task | master taskloop simd | {good}`done` | |
-| task | parallel master taskloop simd | {good}`done` | |
-| SIMD | atomic and simd constructs inside SIMD code | {good}`done` | |
-| SIMD | SIMD nontemporal | {good}`done` | |
-| device | infer target functions from initializers | {part}`worked on` | |
-| device | infer target variables from initializers | {good}`done` | D146418 |
-| device | OMP_TARGET_OFFLOAD environment variable | {good}`done` | D50522 |
-| device | support full 'defaultmap' functionality | {good}`done` | D69204 |
-| device | device specific functions | {good}`done` | |
-| device | clause: device_type | {good}`done` | |
-| device | clause: extended device | {good}`done` | |
-| device | clause: uses_allocators clause | {good}`done` | <https://github.com/llvm/llvm-project/pull/157025> |
-| device | clause: in_reduction | {part}`worked on` | r308768 |
-| device | omp_get_device_num() | {good}`done` | D54342,D128347 |
-| device | structure mapping of references | {none}`unclaimed` | |
-| device | nested target declare | {good}`done` | D51378 |
-| device | implicitly map 'this' (this[:1]) | {good}`done` | D55982 |
-| device | allow access to the reference count (omp_target_is_present) | {good}`done` | |
-| device | requires directive | {good}`done` | |
-| device | clause: unified_shared_memory | {good}`done` | D52625,D52359 |
-| device | clause: unified_address | {part}`partial` | |
-| device | clause: reverse_offload | {part}`partial` | D52780,D155003 |
-| device | clause: atomic_default_mem_order | {good}`done` | D53513 |
-| device | clause: dynamic_allocators | {part}`unclaimed parts` | D53079 |
-| device | user-defined mappers | {good}`done` | D56326,D58638,D58523,D58074,D60972,D59474 |
-| device | map array-section with implicit mapper | {good}`done` | <https://github.com/llvm/llvm-project/pull/101101> |
-| device | mapping lambda expression | {good}`done` | D51107 |
-| device | clause: use_device_addr for target data | {good}`done` | |
-| device | support close modifier on map clause | {good}`done` | D55719,D55892 |
-| device | teams construct on the host device | {good}`done` | r371553 |
-| device | support non-contiguous array sections for target update | {good}`done` | <https://github.com/llvm/llvm-project/pull/144635> |
-| device | pointer attachment | {part}`being repaired` | @abhinavgaba (<https://github.com/llvm/llvm-project/pull/153683>) |
-| atomic | hints for the atomic construct | {good}`done` | D51233 |
-| base language | C11 support | {good}`done` | |
-| base language | C++11/14/17 support | {good}`done` | |
-| base language | lambda support | {good}`done` | |
-| misc | array shaping | {good}`done` | D74144 |
-| misc | library shutdown (omp_pause_resource[\_all]) | {good}`done` | D55078 |
-| misc | metadirectives | {part}`mostly done` | D91944, <https://github.com/llvm/llvm-project/pull/128640> |
-| misc | conditional modifier for lastprivate clause | {good}`done` | |
-| misc | iterator and multidependences | {good}`done` | |
-| misc | depobj directive and depobj dependency kind | {good}`done` | |
-| misc | user-defined function variants | {good}`done`. | D67294, D64095, D71847, D71830, D109635 |
-| misc | pointer/reference to pointer based array reductions | {good}`done` | |
-| misc | prevent new type definitions in clauses | {good}`done` | |
-| memory model | memory model update (seq_cst, acq_rel, release, acquire,...) | {good}`done` | |
+| Category | Feature | Status | Reviews |
+| ----------------- | ------------------------------------------------------------ | ----------------------- | ----------------------------------------------------------------------------------------------------- |
+| loop | support != in the canonical loop form | {good}`done` | [D54441][D54441] |
+| loop | #pragma omp loop (directive) | {part}`partial` | [D145823][D145823] (combined forms) |
+| loop | #pragma omp loop bind | {part}`worked on` | [D144634][D144634] (needs review) |
+| loop | collapse imperfectly nested loop | {good}`done` | |
+| loop | collapse non-rectangular nested loop | {good}`done` | |
+| loop | C++ range-base for loop | {good}`done` | |
+| loop | clause: if for SIMD directives | {good}`done` | |
+| loop | inclusive scan (matching C++17 PSTL) | {good}`done` | |
+| memory management | memory allocators | {good}`done` | r341687,r357929 |
+| memory management | allocate directive and allocate clause | {good}`done` | r355614,r335952 |
+| OMPD | OMPD interfaces | {good}`done` | [D99914][D99914] (Supports only HOST(CPU) and Linux |
+| OMPT | OMPT interfaces (callback support) | {good}`done` | |
+| thread affinity | thread affinity | {good}`done` | |
+| task | taskloop reduction | {good}`done` | |
+| task | task affinity | {part}`not upstream` | <https://github.com/jklinkenberg/openmp/tree/task-affinity> |
+| task | clause: depend on the taskwait construct | {good}`done` | [D113540][D113540] (regular codegen only) |
+| task | depend objects and detachable tasks | {good}`done` | |
+| task | mutexinoutset dependence-type for tasks | {good}`done` | [D53380][D53380],[D57576][D57576] |
+| task | combined taskloop constructs | {good}`done` | |
+| task | master taskloop | {good}`done` | |
+| task | parallel master taskloop | {good}`done` | |
+| task | master taskloop simd | {good}`done` | |
+| task | parallel master taskloop simd | {good}`done` | |
+| SIMD | atomic and simd constructs inside SIMD code | {good}`done` | |
+| SIMD | SIMD nontemporal | {good}`done` | |
+| device | infer target functions from initializers | {part}`worked on` | |
+| device | infer target variables from initializers | {good}`done` | [D146418][D146418] |
+| device | OMP_TARGET_OFFLOAD environment variable | {good}`done` | [D50522][D50522] |
+| device | support full 'defaultmap' functionality | {good}`done` | [D69204][D69204] |
+| device | device specific functions | {good}`done` | |
+| device | clause: device_type | {good}`done` | |
+| device | clause: extended device | {good}`done` | |
+| device | clause: uses_allocators clause | {good}`done` | [PR157025][PR157025] |
+| device | clause: in_reduction | {part}`worked on` | r308768 |
+| device | omp_get_device_num() | {good}`done` | [D54342][D54342],[D128347][D128347] |
+| device | structure mapping of references | {none}`unclaimed` | |
+| device | nested target declare | {good}`done` | [D51378][D51378] |
+| device | implicitly map 'this' (this[:1]) | {good}`done` | [D55982][D55982] |
+| device | allow access to the reference count (omp_target_is_present) | {good}`done` | |
+| device | requires directive | {good}`done` | |
+| device | clause: unified_shared_memory | {good}`done` | [D52625][D52625],[D52359][D52359] |
+| device | clause: unified_address | {part}`partial` | |
+| device | clause: reverse_offload | {part}`partial` | [D52780][D52780],[D155003][D155003] |
+| device | clause: atomic_default_mem_order | {good}`done` | [D53513][D53513] |
+| device | clause: dynamic_allocators | {part}`unclaimed parts` | [D53079][D53079] |
+| device | user-defined mappers | {good}`done` | [D56326][D56326],[D58638][D58638],[D58523][D58523],[D58074][D58074],[D60972][D60972],[D59474][D59474] |
+| device | map array-section with implicit mapper | {good}`done` | [PR101101][PR101101] |
+| device | mapping lambda expression | {good}`done` | [D51107][D51107] |
+| device | clause: use_device_addr for target data | {good}`done` | |
+| device | support close modifier on map clause | {good}`done` | [D55719][D55719],[D55892][D55892] |
+| device | teams construct on the host device | {good}`done` | r371553 |
+| device | support non-contiguous array sections for target update | {good}`done` | [PR144635][PR144635] |
+| device | pointer attachment | {part}`being repaired` | @abhinavgaba ([PR153683][PR153683]) |
+| atomic | hints for the atomic construct | {good}`done` | [D51233][D51233] |
+| base language | C11 support | {good}`done` | |
+| base language | C++11/14/17 support | {good}`done` | |
+| base language | lambda support | {good}`done` | |
+| misc | array shaping | {good}`done` | [D74144][D74144] |
+| misc | library shutdown (omp_pause_resource[\_all]) | {good}`done` | [D55078][D55078] |
+| misc | metadirectives | {part}`mostly done` | [D91944][D91944], [PR128640][PR128640] |
+| misc | conditional modifier for lastprivate clause | {good}`done` | |
+| misc | iterator and multidependences | {good}`done` | |
+| misc | depobj directive and depobj dependency kind | {good}`done` | |
+| misc | user-defined function variants | {good}`done`. | [D67294][D67294], [D64095][D64095], [D71847][D71847], [D71830][D71830], [D109635][D109635] |
+| misc | pointer/reference to pointer based array reductions | {good}`done` | |
+| misc | prevent new type definitions in clauses | {good}`done` | |
+| memory model | memory model update (seq_cst, acq_rel, release, acquire,...) | {good}`done` | |
(openmp-51-implementation-details)=
@@ -164,61 +161,61 @@ Please post on the
information or if you want to help with the
implementation.
-| Category | Feature | Status | Reviews |
-| ----------------- | ----------------------------------------------------------- | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| atomic | 'compare' clause on atomic construct | {good}`done` | D120290, D120007, D118632, D120200, D116261, D118547, D116637 |
-| atomic | 'fail' clause on atomic construct | {part}`worked on` | D123235 (in progress) |
-| base language | C++ attribute specifier syntax | {good}`done` | D105648 |
-| device | 'present' map type modifier | {good}`done` | D83061, D83062, D84422 |
-| device | 'present' motion modifier | {good}`done` | D84711, D84712 |
-| device | 'present' in defaultmap clause | {good}`done` | D92427 |
-| device | map clause reordering based on 'present' modifier | {none}`unclaimed` | |
-| device | device-specific environment variables | {none}`unclaimed` | |
-| device | omp_target_is_accessible routine | {good}`done` | <https://github.com/llvm/llvm-project/pull/138294> |
-| device | omp_get_mapped_ptr routine | {good}`done` | D141545 |
-| device | new async target memory copy routines | {good}`done` | D136103 |
-| device | thread_limit clause on target construct | {part}`partial` | D141540 (offload), D152054 (host, in progress) |
-| device | has_device_addr clause on target construct | {none}`unclaimed` | |
-| device | use_device_ptr/addr preserve host address when lookup fails | {good}`done` | <https://github.com/llvm/llvm-project/pull/174659> |
-| device | iterators in map clause or motion clauses | {good}`done` | <https://github.com/llvm/llvm-project/pull/159112> |
-| device | indirect clause on declare target directive | {part}`In Progress` | |
-| device | allow virtual functions calls for mapped object on device | {part}`partial` | |
-| device | interop construct | {part}`partial` | parsing/sema done: D98558, D98834, D98815 |
-| device | assorted routines for querying interoperable properties | {part}`partial` | D106674 |
-| loop | Loop tiling transformation | {good}`done` | D76342 |
-| loop | Loop unrolling transformation | {good}`done` | D99459 |
-| loop | 'reproducible'/'unconstrained' modifiers in 'order' clause | {part}`partial` | D127855 |
-| memory management | alignment for allocate directive and clause | {good}`done` | D115683 |
-| memory management | 'allocator' modifier for allocate clause | {good}`done` | <https://github.com/llvm/llvm-project/pull/114883> |
-| memory management | 'align' modifier for allocate clause | {good}`done` | <https://github.com/llvm/llvm-project/pull/121814> |
-| memory management | new memory management routines | {none}`unclaimed` | |
-| memory management | changes to omp_alloctrait_key enum | {none}`unclaimed` | |
-| memory model | seq_cst clause on flush construct | {good}`done` | <https://github.com/llvm/llvm-project/pull/114072> |
-| misc | 'omp_all_memory' keyword and use in 'depend' clause | {good}`done` | D125828, D126321 |
-| misc | error directive | {good}`done` | D139166 |
-| misc | scope construct | {good}`done` | D157933, <https://github.com/llvm/llvm-project/pull/109197> |
-| misc | routines for controlling and querying team regions | {part}`partial` | D95003 (libomp only) |
-| misc | omp_display_env routine | {good}`done` | D74956 |
-| misc | extended OMP_PLACES syntax | {none}`unclaimed` | |
-| misc | OMP_NUM_TEAMS and OMP_TEAMS_THREAD_LIMIT env vars | {good}`done` | D138769 |
-| misc | 'target_device' selector in context specifier | {part}`worked on` | |
-| misc | begin/end declare variant | {good}`done` | D71179 |
-| misc | dispatch construct and function variant argument adjustment | {part}`worked on` | D99537, D99679 |
-| misc | assumes directives | {part}`worked on` | |
-| misc | assume directive | {good}`done` | |
-| misc | nothing directive | {good}`done` | D123286 |
-| misc | masked construct and related combined constructs | {good}`done` | D99995, D100514, PR-121741(parallel_masked_taskloop) PR-121746(parallel_masked_task_loop_simd),PR-121914(masked_taskloop) PR-121916(masked_taskloop_simd) |
-| misc | default(firstprivate) & default(private) | {good}`done` | D75591 (firstprivate), D125912 (private) |
-| other | deprecating master construct | {none}`unclaimed` | |
-| OMPT | changes to ompt_scope_endpoint_t enum | {good}`done` | D90752 |
-| OMPT | new barrier types added to ompt_sync_region_t enum | {good}`done` | D90752 |
-| OMPT | async data transfers added to ompt_target_data_op_t enum | {good}`done` | D90752 |
-| OMPT | new barrier state values added to ompt_state_t enum | {good}`done` | D90752 |
-| OMPT | new 'emi' callbacks for external monitoring interfaces | {good}`done` | |
-| OMPT | device tracing interface | {part}`in progress` | jplehr |
-| task | 'strict' modifier for taskloop construct | {none}`unclaimed` | |
-| task | inoutset in depend clause | {good}`done` | D97085, D118383 |
-| task | nowait clause on taskwait | {part}`partial` | parsing/sema done: D131830, D141531 |
+| Category | Feature | Status | Reviews |
+| ----------------- | ----------------------------------------------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| atomic | 'compare' clause on atomic construct | {good}`done` | [D120290][D120290], [D120007][D120007], [D118632][D118632], [D120200][D120200], [D116261][D116261], [D118547][D118547], [D116637][D116637] |
+| atomic | 'fail' clause on atomic construct | {part}`worked on` | [D123235][D123235] (in progress) |
+| base language | C++ attribute specifier syntax | {good}`done` | [D105648][D105648] |
+| device | 'present' map type modifier | {good}`done` | [D83061][D83061], [D83062][D83062], [D84422][D84422] |
+| device | 'present' motion modifier | {good}`done` | [D84711][D84711], [D84712][D84712] |
+| device | 'present' in defaultmap clause | {good}`done` | [D92427][D92427] |
+| device | map clause reordering based on 'present' modifier | {none}`unclaimed` | |
+| device | device-specific environment variables | {none}`unclaimed` | |
+| device | omp_target_is_accessible routine | {good}`done` | [PR138294][PR138294] |
+| device | omp_get_mapped_ptr routine | {good}`done` | [D141545][D141545] |
+| device | new async target memory copy routines | {good}`done` | [D136103][D136103] |
+| device | thread_limit clause on target construct | {part}`partial` | [D141540][D141540] (offload), [D152054][D152054] (host, in progress) |
+| device | has_device_addr clause on target construct | {none}`unclaimed` | |
+| device | use_device_ptr/addr preserve host address when lookup fails | {good}`done` | [PR174659][PR174659] |
+| device | iterators in map clause or motion clauses | {good}`done` | [PR159112][PR159112] |
+| device | indirect clause on declare target directive | {part}`In Progress` | |
+| device | allow virtual functions calls for mapped object on device | {part}`partial` | |
+| device | interop construct | {part}`partial` | parsing/sema done: [D98558][D98558], [D98834][D98834], [D98815][D98815] |
+| device | assorted routines for querying interoperable properties | {part}`partial` | [D106674][D106674] |
+| loop | Loop tiling transformation | {good}`done` | [D76342][D76342] |
+| loop | Loop unrolling transformation | {good}`done` | [D99459][D99459] |
+| loop | 'reproducible'/'unconstrained' modifiers in 'order' clause | {part}`partial` | [D127855][D127855] |
+| memory management | alignment for allocate directive and clause | {good}`done` | [D115683][D115683] |
+| memory management | 'allocator' modifier for allocate clause | {good}`done` | [PR114883][PR114883] |
+| memory management | 'align' modifier for allocate clause | {good}`done` | [PR121814][PR121814] |
+| memory management | new memory management routines | {none}`unclaimed` | |
+| memory management | changes to omp_alloctrait_key enum | {none}`unclaimed` | |
+| memory model | seq_cst clause on flush construct | {good}`done` | [PR114072][PR114072] |
+| misc | 'omp_all_memory' keyword and use in 'depend' clause | {good}`done` | [D125828][D125828], [D126321][D126321] |
+| misc | error directive | {good}`done` | [D139166][D139166] |
+| misc | scope construct | {good}`done` | [D157933][D157933], [PR109197][PR109197] |
+| misc | routines for controlling and querying team regions | {part}`partial` | [D95003][D95003] (libomp only) |
+| misc | omp_display_env routine | {good}`done` | [D74956][D74956] |
+| misc | extended OMP_PLACES syntax | {none}`unclaimed` | |
+| misc | OMP_NUM_TEAMS and OMP_TEAMS_THREAD_LIMIT env vars | {good}`done` | [D138769][D138769] |
+| misc | 'target_device' selector in context specifier | {part}`worked on` | |
+| misc | begin/end declare variant | {good}`done` | [D71179][D71179] |
+| misc | dispatch construct and function variant argument adjustment | {part}`worked on` | [D99537][D99537], [D99679][D99679] |
+| misc | assumes directives | {part}`worked on` | |
+| misc | assume directive | {good}`done` | |
+| misc | nothing directive | {good}`done` | [D123286][D123286] |
+| misc | masked construct and related combined constructs | {good}`done` | [D99995][D99995], [D100514][D100514], [PR121741][PR121741] (parallel_masked_taskloop) [PR121746][PR121746] (parallel_masked_task_loop_simd), [PR121914][PR121914] (masked_taskloop) [PR121916][PR121916] (masked_taskloop_simd) |
+| misc | default(firstprivate) & default(private) | {good}`done` | [D75591][D75591] (firstprivate), [D125912][D125912] (private) |
+| other | deprecating master construct | {none}`unclaimed` | |
+| OMPT | changes to ompt_scope_endpoint_t enum | {good}`done` | [D90752][D90752] |
+| OMPT | new barrier types added to ompt_sync_region_t enum | {good}`done` | [D90752][D90752] |
+| OMPT | async data transfers added to ompt_target_data_op_t enum | {good}`done` | [D90752][D90752] |
+| OMPT | new barrier state values added to ompt_state_t enum | {good}`done` | [D90752][D90752] |
+| OMPT | new 'emi' callbacks for external monitoring interfaces | {good}`done` | |
+| OMPT | device tracing interface | {part}`in progress` | jplehr |
+| task | 'strict' modifier for taskloop construct | {none}`unclaimed` | |
+| task | inoutset in depend clause | {good}`done` | [D97085][D97085], [D118383][D118383] |
+| task | nowait clause on taskwait | {part}`partial` | parsing/sema done: [D131830][D131830], [D141531][D141531] |
(openmp-5-2-implementation-details)=
@@ -230,30 +227,30 @@ and their implementation status. Please post on the
information or if you want to help with the
implementation.
-| Feature | C/C++ Status | Fortran Status | Reviews |
-| ------------------------------------------------------- | ----------------- | ----------------- | ------------------- |
-| omp_in_explicit_task() | {none}`unclaimed` | {none}`unclaimed` | |
-| semantics of explicit_task_var and implicit_task_var | {none}`unclaimed` | {none}`unclaimed` | |
-| ompx sentinel for C/C++ directive extensions | {none}`unclaimed` | {none}`unclaimed` | |
-| ompx prefix for clause extensions | {none}`unclaimed` | {none}`unclaimed` | |
-| if clause on teams construct | {none}`unclaimed` | {none}`unclaimed` | |
-| step modifier added | {none}`unclaimed` | {none}`unclaimed` | |
-| declare mapper: Add iterator modifier on map clause | {none}`unclaimed` | {none}`unclaimed` | |
-| declare mapper: Add iterator modifier on map clause | {none}`unclaimed` | {none}`unclaimed` | |
-| memspace and traits modifiers to uses allocator i | {none}`unclaimed` | {none}`unclaimed` | |
-| Add otherwise clause to metadirectives | {none}`unclaimed` | {none}`unclaimed` | |
-| doacross clause with support for omp_cur_iteration | {none}`unclaimed` | {none}`unclaimed` | |
-| position of interop_type in init clause on iterop | {none}`unclaimed` | {none}`unclaimed` | |
-| implicit map type for target enter/exit data | {none}`unclaimed` | {none}`unclaimed` | |
-| work OMPT type for work-sharing loop constructs | {good}`done` | {good}`done` | PR-189347, PR-97429 |
-| extend ompt_dispatch_t for new enum values | {good}`done` | {good}`done` | D122107 |
-| allocate and firstprivate on scope directive | {none}`unclaimed` | {none}`unclaimed` | |
-| Change loop consistency for order clause | {none}`unclaimed` | {none}`unclaimed` | |
-| Add memspace and traits modifiers to uses_allocators | {none}`unclaimed` | {none}`unclaimed` | |
-| Keep original base pointer on map w/o matched candidate | {none}`unclaimed` | {none}`unclaimed` | |
-| Pure procedure support for certain directives | {none}`N/A` | {none}`unclaimed` | |
-| ALLOCATE statement support for allocators | {none}`N/A` | {none}`unclaimed` | |
-| dispatch construct extension to support end directive | {none}`N/A` | {none}`unclaimed` | |
+| Feature | C/C++ Status | Fortran Status | Reviews |
+| ------------------------------------------------------- | ----------------- | ----------------- | ---------------------------------------- |
+| omp_in_explicit_task() | {none}`unclaimed` | {none}`unclaimed` | |
+| semantics of explicit_task_var and implicit_task_var | {none}`unclaimed` | {none}`unclaimed` | |
+| ompx sentinel for C/C++ directive extensions | {none}`unclaimed` | {none}`unclaimed` | |
+| ompx prefix for clause extensions | {none}`unclaimed` | {none}`unclaimed` | |
+| if clause on teams construct | {none}`unclaimed` | {none}`unclaimed` | |
+| step modifier added | {none}`unclaimed` | {none}`unclaimed` | |
+| declare mapper: Add iterator modifier on map clause | {none}`unclaimed` | {none}`unclaimed` | |
+| declare mapper: Add iterator modifier on map clause | {none}`unclaimed` | {none}`unclaimed` | |
+| memspace and traits modifiers to uses allocator i | {none}`unclaimed` | {none}`unclaimed` | |
+| Add otherwise clause to metadirectives | {none}`unclaimed` | {none}`unclaimed` | |
+| doacross clause with support for omp_cur_iteration | {none}`unclaimed` | {none}`unclaimed` | |
+| position of interop_type in init clause on iterop | {none}`unclaimed` | {none}`unclaimed` | |
+| implicit map type for target enter/exit data | {none}`unclaimed` | {none}`unclaimed` | |
+| work OMPT type for work-sharing loop constructs | {good}`done` | {good}`done` | [PR189347][PR189347], [PR97429][PR97429] |
+| extend ompt_dispatch_t for new enum values | {good}`done` | {good}`done` | [D122107][D122107] |
+| allocate and firstprivate on scope directive | {none}`unclaimed` | {none}`unclaimed` | |
+| Change loop consistency for order clause | {none}`unclaimed` | {none}`unclaimed` | |
+| Add memspace and traits modifiers to uses_allocators | {none}`unclaimed` | {none}`unclaimed` | |
+| Keep original base pointer on map w/o matched candidate | {none}`unclaimed` | {none}`unclaimed` | |
+| Pure procedure support for certain directives | {none}`N/A` | {none}`unclaimed` | |
+| ALLOCATE statement support for allocators | {none}`N/A` | {none}`unclaimed` | |
+| dispatch construct extension to support end directive | {none}`N/A` | {none}`unclaimed` | |
(openmp-5-2-deprecations)=
@@ -284,85 +281,85 @@ and their implementation status. Please post on the
information or if you want to help with the
implementation.
-| Feature | C/C++ Status | Fortran Status | Reviews |
-| ----------------------------------------------------------- | ------------------- | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| free-agent threads | {none}`unclaimed` | {none}`unclaimed` | |
-| threadset clause | {part}`partial` | {none}`unclaimed` | Parse/Sema/Codegen: <https://github.com/llvm/llvm-project/pull/13580> |
-| Recording of task graphs | {part}`in progress` | {part}`in progress` | clang: jtb20, flang: kparzysz |
-| Parallel inductions | {none}`unclaimed` | {none}`unclaimed` | |
-| init_complete for scan directive | {none}`unclaimed` | {none}`unclaimed` | |
-| loop interchange transformation | {good}`done` | {none}`unclaimed` | Clang (interchange): <https://github.com/llvm/llvm-project/pull/93022> Clang (permutation): <https://github.com/llvm/llvm-project/pull/92030> |
-| loop reverse transformation | {good}`done` | {none}`unclaimed` | <https://github.com/llvm/llvm-project/pull/92916> |
-| loop stripe transformation | {good}`done` | {none}`unclaimed` | <https://github.com/llvm/llvm-project/pull/119891> |
-| loop fusion transformation | {part}`in progress` | {good}`done` | <https://github.com/llvm/llvm-project/pull/139293> <https://github.com/llvm/llvm-project/pull/161213> <https://github.com/llvm/llvm-project/pull/168898> |
-| loop index set splitting transformation with count clause | {part}`in progress` | {none}`unclaimed` | @amitamd7 |
-| loop transformation apply clause | {none}`unclaimed` | {none}`unclaimed` | |
-| loop fuse transformation | {good}`done` | {none}`unclaimed` | |
-| workdistribute construct | | {none}`in progress` | @skc7, @mjklemm |
-| task_iteration | {none}`unclaimed` | {none}`unclaimed` | |
-| memscope clause for atomic and flush | {none}`unclaimed` | {none}`unclaimed` | |
-| transparent clause (hull tasks) | {part}`partial` | {none}`unclaimed` | Clang parsing/sema <https://github.com/llvm/llvm-project/pull/174646> |
-| rule-based compound directives | {part}`In Progress` | {part}`In Progress` | kparzysz Testing for Fortran missing |
-| C23, C++23 | {none}`unclaimed` | | |
-| Fortran 2023 | | {none}`unclaimed` | |
-| decl attribute for declarative directives | {none}`unclaimed` | {none}`unclaimed` | |
-| C attribute syntax | {none}`unclaimed` | | |
-| pure directives in DO CONCURRENT | | {none}`unclaimed` | |
-| Optional argument for all clauses | {part}`partial` | {part}`In Progress` | Parse/Sema (nowait): <https://github.com/llvm/llvm-project/pull/159628> |
-| Function references for locator list items | {none}`unclaimed` | {none}`unclaimed` | |
-| All clauses accept directive name modifier | {none}`unclaimed` | {none}`unclaimed` | |
-| Extensions to depobj construct | {none}`unclaimed` | {none}`unclaimed` | |
-| Extensions to atomic construct | {none}`unclaimed` | {none}`unclaimed` | |
-| Private reductions | {part}`mostly` | {none}`unclaimed` | Parse/Sema: <https://github.com/llvm/llvm-project/pull/129938> Codegen: <https://github.com/llvm/llvm-project/pull/134709> |
-| Self maps | {part}`partial` | {none}`unclaimed` | parsing/sema done: <https://github.com/llvm/llvm-project/pull/129888> |
-| Release map type for declare mapper | {none}`unclaimed` | {none}`unclaimed` | |
-| Extensions to interop construct | {none}`unclaimed` | {none}`unclaimed` | |
-| no_openmp_constructs | {good}`done` | {none}`unclaimed` | <https://github.com/llvm/llvm-project/pull/125933> |
-| safe_sync and progress with identifier and API | {none}`unclaimed` | {none}`unclaimed` | |
-| OpenMP directives in concurrent loop regions | {good}`done` | {none}`unclaimed` | <https://github.com/llvm/llvm-project/pull/125621> |
-| atomics constructs on concurrent loop regions | {good}`done` | {none}`unclaimed` | <https://github.com/llvm/llvm-project/pull/125621> |
-| Loop construct with DO CONCURRENT | | {part}`In Progress` | |
-| device_type clause for target construct | {none}`unclaimed` | {none}`unclaimed` | |
-| nowait for ancestor target directives | {none}`unclaimed` | {none}`unclaimed` | |
-| New API for devices' num_teams/thread_limit | {none}`unclaimed` | {none}`unclaimed` | |
-| Host and device environment variables | {part}`in progress` | {none}`unclaimed` | @amitamd7 |
-| num_threads ICV and clause accepts list | {none}`unclaimed` | {none}`unclaimed` | |
-| Numeric names for environment variables | {none}`unclaimed` | {none}`unclaimed` | |
-| Increment between places for OMP_PLACES | {none}`unclaimed` | {none}`unclaimed` | |
-| OMP_AVAILABLE_DEVICES envirable | {none}`unclaimed` | {none}`unclaimed` | (should wait for "Traits for default device envirable" being done) |
-| Traits for default device envirable | {part}`in progress` | {none}`unclaimed` | ro-i |
-| Optionally omit array length expression | {good}`done` | {none}`unclaimed` | (Parse) <https://github.com/llvm/llvm-project/pull/148048>, (Sema) <https://github.com/llvm/llvm-project/pull/152786> |
-| Canonical loop sequences | {part}`in progress` | {part}`in progress` | Clang: <https://github.com/llvm/llvm-project/pull/139293> |
-| Clarifications to Fortran map semantics | {none}`unclaimed` | {none}`unclaimed` | |
-| default clause at target construct | {good}`done` | {none}`unclaimed` | <https://github.com/llvm/llvm-project/pull/162910> |
-| ref count update use_device_{ptr, addr} | {none}`unclaimed` | {none}`unclaimed` | |
-| Clarifications to implicit reductions | {none}`unclaimed` | {none}`unclaimed` | |
-| ref modifier for map clauses | {part}`In Progress` | {none}`unclaimed` | |
-| map-type modifiers in arbitrary position | {good}`done` | {none}`unclaimed` | <https://github.com/llvm/llvm-project/pull/90499> |
-| Lift nesting restriction on concurrent loop | {good}`done` | {none}`unclaimed` | <https://github.com/llvm/llvm-project/pull/125621> |
-| priority clause for target constructs | {none}`unclaimed` | {none}`unclaimed` | |
-| changes to target_data construct | {none}`unclaimed` | {none}`unclaimed` | |
-| Non-const do_not_sync for nowait/nogroup | {none}`unclaimed` | {none}`unclaimed` | |
-| need_device_addr modifier for adjust_args clause | {part}`partial` | {none}`unclaimed` | Parsing/Sema: <https://github.com/llvm/llvm-project/pull/143442> <https://github.com/llvm/llvm-project/pull/149586> |
-| need_device_ptr modifier for adjust_args clause | {none}`unclaimed` | {none}`unclaimed` | |
-| Prescriptive num_threads | {good}`done` | {none}`unclaimed` | <https://github.com/llvm/llvm-project/pull/160659> <https://github.com/llvm/llvm-project/pull/146403> <https://github.com/llvm/llvm-project/pull/146404> <https://github.com/llvm/llvm-project/pull/146405> |
-| Message and severity clauses | {good}`done` | {none}`unclaimed` | <https://github.com/llvm/llvm-project/pull/146093> |
-| Local clause on declare target | {good}`done` | {none}`unclaimed` | clang Parse/Sema: <https://github.com/llvm/llvm-project/pull/186281> clang Codegen: <https://github.com/llvm/llvm-project/pull/196431> |
-| groupprivate directive | {part}`In Progress` | {part}`partial` | Flang: kparzysz, mjklemm Flang parser: <https://github.com/llvm/llvm-project/pull/153807> Flang sema: <https://github.com/llvm/llvm-project/pull/154779> Clang parse/sema: <https://github.com/llvm/llvm-project/pull/158134> |
-| variable-category on default clause | {good}`done` | {none}`unclaimed` | |
-| Changes to omp_target_is_accessible | {part}`In Progress` | {part}`In Progress` | |
-| defaultmap implicit-behavior 'storage' | {good}`done` | {none}`unclaimed` | <https://github.com/llvm/llvm-project/pull/158336> |
-| defaultmap implicit-behavior 'private' | {good}`done` | {none}`unclaimed` | <https://github.com/llvm/llvm-project/pull/158712> |
-| OMPT: ompt_get_buffer_limits entry point | {part}`partial` | {good}`N/A` | Definition: <https://github.com/llvm/llvm-project/pull/195829> |
-| OMPT: ompt_any_record_ompt_t for device tracing | {good}`done` | {good}`N/A` | <https://github.com/llvm/llvm-project/pull/195829> |
-| OMPT: ompt_target_data_transfer_rect(_async) & subvolume | {part}`partial` | {good}`N/A` | Enum: <https://github.com/llvm/llvm-project/pull/195829> |
-| OMPT: ompt_target_data_transfer(_async) | {part}`partial` | {good}`N/A` | Enum: <https://github.com/llvm/llvm-project/pull/195829> |
-| OMPT: ompt_target_data_memset(_async) | {part}`partial` | {good}`N/A` | Enum: <https://github.com/llvm/llvm-project/pull/195829> Callbacks: <https://github.com/llvm/llvm-project/pull/194168> |
-| OMPT: workdistribute work callback enum | {part}`partial` | {good}`N/A` | Enum: <https://github.com/llvm/llvm-project/pull/195829> |
-| OMPT: transparent task flag enum (importing/exporting) | {part}`partial` | {good}`N/A` | Enum: <https://github.com/llvm/llvm-project/pull/195829> |
-| OMPT: dependence type {out, inout}_all_memory | {part}`partial` | {good}`N/A` | Enum: <https://github.com/llvm/llvm-project/pull/195829> |
-| OMPT: removed master callback | {none}`unclaimed` | {good}`N/A` | |
-| OMPT: removed sync_region_barrier(_implicit) enum value | {none}`unclaimed` | {good}`N/A` | |
+| Feature | C/C++ Status | Fortran Status | Reviews |
+| --------------------------------------------------------- | ------------------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| free-agent threads | {none}`unclaimed` | {none}`unclaimed` | |
+| threadset clause | {part}`partial` | {none}`unclaimed` | Parse/Sema/Codegen: [PR13580][PR13580] |
+| Recording of task graphs | {part}`in progress` | {part}`in progress` | clang: jtb20, flang: kparzysz |
+| Parallel inductions | {none}`unclaimed` | {none}`unclaimed` | |
+| init_complete for scan directive | {none}`unclaimed` | {none}`unclaimed` | |
+| loop interchange transformation | {good}`done` | {none}`unclaimed` | Clang (interchange): [PR93022][PR93022] Clang (permutation): [PR92030][PR92030] |
+| loop reverse transformation | {good}`done` | {none}`unclaimed` | [PR92916][PR92916] |
+| loop stripe transformation | {good}`done` | {none}`unclaimed` | [PR119891][PR119891] |
+| loop fusion transformation | {part}`in progress` | {good}`done` | [PR139293][PR139293] [PR161213][PR161213] [PR168898][PR168898] |
+| loop index set splitting transformation with count clause | {part}`in progress` | {none}`unclaimed` | @amitamd7 |
+| loop transformation apply clause | {none}`unclaimed` | {none}`unclaimed` | |
+| loop fuse transformation | {good}`done` | {none}`unclaimed` | |
+| workdistribute construct | | {none}`in progress` | @skc7, @mjklemm |
+| task_iteration | {none}`unclaimed` | {none}`unclaimed` | |
+| memscope clause for atomic and flush | {none}`unclaimed` | {none}`unclaimed` | |
+| transparent clause (hull tasks) | {part}`partial` | {none}`unclaimed` | Clang parsing/sema [PR174646][PR174646] |
+| rule-based compound directives | {part}`In Progress` | {part}`In Progress` | kparzysz Testing for Fortran missing |
+| C23, C++23 | {none}`unclaimed` | | |
+| Fortran 2023 | | {none}`unclaimed` | |
+| decl attribute for declarative directives | {none}`unclaimed` | {none}`unclaimed` | |
+| C attribute syntax | {none}`unclaimed` | | |
+| pure directives in DO CONCURRENT | | {none}`unclaimed` | |
+| Optional argument for all clauses | {part}`partial` | {part}`In Progress` | Parse/Sema (nowait): [PR159628][PR159628] |
+| Function references for locator list items | {none}`unclaimed` | {none}`unclaimed` | |
+| All clauses accept directive name modifier | {none}`unclaimed` | {none}`unclaimed` | |
+| Extensions to depobj construct | {none}`unclaimed` | {none}`unclaimed` | |
+| Extensions to atomic construct | {none}`unclaimed` | {none}`unclaimed` | |
+| Private reductions | {part}`mostly` | {none}`unclaimed` | Parse/Sema: [PR129938][PR129938] Codegen: [PR134709][PR134709] |
+| Self maps | {part}`partial` | {none}`unclaimed` | parsing/sema done: [PR129888][PR129888] |
+| Release map type for declare mapper | {none}`unclaimed` | {none}`unclaimed` | |
+| Extensions to interop construct | {none}`unclaimed` | {none}`unclaimed` | |
+| no_openmp_constructs | {good}`done` | {none}`unclaimed` | [PR125933][PR125933] |
+| safe_sync and progress with identifier and API | {none}`unclaimed` | {none}`unclaimed` | |
+| OpenMP directives in concurrent loop regions | {good}`done` | {none}`unclaimed` | [PR125621][PR125621] |
+| atomics constructs on concurrent loop regions | {good}`done` | {none}`unclaimed` | [PR125621][PR125621] |
+| Loop construct with DO CONCURRENT | | {part}`In Progress` | |
+| device_type clause for target construct | {none}`unclaimed` | {none}`unclaimed` | |
+| nowait for ancestor target directives | {none}`unclaimed` | {none}`unclaimed` | |
+| New API for devices' num_teams/thread_limit | {none}`unclaimed` | {none}`unclaimed` | |
+| Host and device environment variables | {part}`in progress` | {none}`unclaimed` | @amitamd7 |
+| num_threads ICV and clause accepts list | {none}`unclaimed` | {none}`unclaimed` | |
+| Numeric names for environment variables | {none}`unclaimed` | {none}`unclaimed` | |
+| Increment between places for OMP_PLACES | {none}`unclaimed` | {none}`unclaimed` | |
+| OMP_AVAILABLE_DEVICES envirable | {none}`unclaimed` | {none}`unclaimed` | (should wait for "Traits for default device envirable" being done) |
+| Traits for default device envirable | {part}`in progress` | {none}`unclaimed` | ro-i |
+| Optionally omit array length expression | {good}`done` | {none}`unclaimed` | (Parse) [PR148048][PR148048], (Sema) [PR152786][PR152786] |
+| Canonical loop sequences | {part}`in progress` | {part}`in progress` | Clang: [PR139293][PR139293] |
+| Clarifications to Fortran map semantics | {none}`unclaimed` | {none}`unclaimed` | |
+| default clause at target construct | {good}`done` | {none}`unclaimed` | [PR162910][PR162910] |
+| ref count update use_device_{ptr, addr} | {none}`unclaimed` | {none}`unclaimed` | |
+| Clarifications to implicit reductions | {none}`unclaimed` | {none}`unclaimed` | |
+| ref modifier for map clauses | {part}`In Progress` | {none}`unclaimed` | |
+| map-type modifiers in arbitrary position | {good}`done` | {none}`unclaimed` | [PR90499][PR90499] |
+| Lift nesting restriction on concurrent loop | {good}`done` | {none}`unclaimed` | [PR125621][PR125621] |
+| priority clause for target constructs | {none}`unclaimed` | {none}`unclaimed` | |
+| changes to target_data construct | {none}`unclaimed` | {none}`unclaimed` | |
+| Non-const do_not_sync for nowait/nogroup | {none}`unclaimed` | {none}`unclaimed` | |
+| need_device_addr modifier for adjust_args clause | {part}`partial` | {none}`unclaimed` | Parsing/Sema: [PR143442][PR143442] [PR149586][PR149586] |
+| need_device_ptr modifier for adjust_args clause | {none}`unclaimed` | {none}`unclaimed` | |
+| Prescriptive num_threads | {good}`done` | {none}`unclaimed` | [PR160659][PR160659] [PR146403][PR146403] [PR146404][PR146404] [PR146405][PR146405] |
+| Message and severity clauses | {good}`done` | {none}`unclaimed` | [PR146093][PR146093] |
+| Local clause on declare target | {good}`done` | {none}`unclaimed` | clang Parse/Sema: [PR186281][PR186281] clang Codegen: [PR196431][PR196431] |
+| groupprivate directive | {part}`In Progress` | {part}`partial` | Flang: kparzysz, mjklemm Flang parser: [PR153807][PR153807] Flang sema: [PR154779][PR154779] Clang parse/sema: [PR158134][PR158134] |
+| variable-category on default clause | {good}`done` | {none}`unclaimed` | |
+| Changes to omp_target_is_accessible | {part}`In Progress` | {part}`In Progress` | |
+| defaultmap implicit-behavior 'storage' | {good}`done` | {none}`unclaimed` | [PR158336][PR158336] |
+| defaultmap implicit-behavior 'private' | {good}`done` | {none}`unclaimed` | [PR158712][PR158712] |
+| OMPT: ompt_get_buffer_limits entry point | {part}`partial` | {good}`N/A` | Definition: [PR195829][PR195829] |
+| OMPT: ompt_any_record_ompt_t for device tracing | {good}`done` | {good}`N/A` | [PR195829][PR195829] |
+| OMPT: ompt_target_data_transfer_rect(_async) & subvolume | {part}`partial` | {good}`N/A` | Enum: [PR195829][PR195829] |
+| OMPT: ompt_target_data_transfer(_async) | {part}`partial` | {good}`N/A` | Enum: [PR195829][PR195829] |
+| OMPT: ompt_target_data_memset(_async) | {part}`partial` | {good}`N/A` | Enum: [PR195829][PR195829] Callbacks: [PR194168][PR194168] |
+| OMPT: workdistribute work callback enum | {part}`partial` | {good}`N/A` | Enum: [PR195829][PR195829] |
+| OMPT: transparent task flag enum (importing/exporting) | {part}`partial` | {good}`N/A` | Enum: [PR195829][PR195829] |
+| OMPT: dependence type {out, inout}_all_memory | {part}`partial` | {good}`N/A` | Enum: [PR195829][PR195829] |
+| OMPT: removed master callback | {none}`unclaimed` | {good}`N/A` | |
+| OMPT: removed sync_region_barrier(_implicit) enum value | {none}`unclaimed` | {good}`N/A` | |
(openmp-6-0-deprecations)=
@@ -384,15 +381,15 @@ Please post on the [Discourse forums (Runtimes - OpenMP category)] for more
information or if you want to help with the
implementation.
-| Feature | C/C++ Status | Fortran Status | Reviews |
-| --------------------------------------------------------------------- | ------------------- | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| dyn_groupprivate clause | {part}`partial` | {part}`In Progress` | C/C++: Host device support missing |
-| loop flatten transformation | {none}`unclaimed` | {none}`unclaimed` | |
-| loop grid/tile modifiers for sizes clause | {none}`unclaimed` | {none}`unclaimed` | |
-| attach map-type modifier | {part}`In Progress` | {none}`unclaimed` | C/C++: @abhinavgaba; RT: @abhinavgaba (<https://github.com/llvm/llvm-project/pull/149036>, <https://github.com/llvm/llvm-project/pull/158370>) |
-| need_device_ptr modifier for adjust_args clause | {part}`partial` | {none}`unclaimed` | Clang Parsing/Sema: <https://github.com/llvm/llvm-project/pull/168905> <https://github.com/llvm/llvm-project/pull/169558> |
-| fallback modifier for use_device_ptr clause | {good}`done` | {none}`unclaimed` | Clang: @abhinavgaba (<https://github.com/llvm/llvm-project/pull/170578>, <https://github.com/llvm/llvm-project/pull/173931>) RT: @abhinavgaba (<https://github.com/llvm/llvm-project/pull/169603>) |
-| dims clause with strict behavior (multidimensional teams and leagues) | {part}`In Progress` | {part}`In Progress` | C/C++: kevinsala Fortran: skc7, kparzysz, mjklemm |
+| Feature | C/C++ Status | Fortran Status | Reviews |
+| --------------------------------------------------------------------- | ------------------- | ------------------- | -------------------------------------------------------------------------------------------------------- |
+| dyn_groupprivate clause | {part}`partial` | {part}`In Progress` | C/C++: Host device support missing |
+| loop flatten transformation | {none}`unclaimed` | {none}`unclaimed` | |
+| loop grid/tile modifiers for sizes clause | {none}`unclaimed` | {none}`unclaimed` | |
+| attach map-type modifier | {part}`In Progress` | {none}`unclaimed` | C/C++: @abhinavgaba; RT: @abhinavgaba ([PR149036][PR149036], [PR158370][PR158370]) |
+| need_device_ptr modifier for adjust_args clause | {part}`partial` | {none}`unclaimed` | Clang Parsing/Sema: [PR168905][PR168905] [PR169558][PR169558] |
+| fallback modifier for use_device_ptr clause | {good}`done` | {none}`unclaimed` | Clang: @abhinavgaba ([PR170578][PR170578], [PR173931][PR173931]) RT: @abhinavgaba ([PR169603][PR169603]) |
+| dims clause with strict behavior (multidimensional teams and leagues) | {part}`In Progress` | {part}`In Progress` | C/C++: kevinsala Fortran: skc7, kparzysz, mjklemm |
## OpenMP Extensions
@@ -403,11 +400,167 @@ documentation are provided. As these extensions mature, they will be
considered for standardization. Please post on the
[Discourse forums (Runtimes - OpenMP category)] to provide feedback.
-| Category | Feature | Status | Reviews |
-| ---------------- | ----------------------------------------------------------------------------------------------------------------------- | ------------------ | ------------------------ |
-| atomic extension | ['atomic' strictly nested within 'teams'](https://openmp.llvm.org/docs/openacc/OpenMPExtensions.html#atomicWithinTeams) | {part}`prototyped` | D126323 |
-| device extension | ['ompx_hold' map type modifier](https://openmp.llvm.org/docs/openacc/OpenMPExtensions.html#ompx-hold) | {part}`prototyped` | D106509, D106510 |
-| device extension | ['ompx_bare' clause on 'target teams' construct](https://www.osti.gov/servlets/purl/2205717) | {part}`prototyped` | #66844, #70612 |
-| device extension | Multi-dim 'num_teams' and 'thread_limit' clause on 'target teams ompx_bare' construct | {part}`partial` | #99732, #101407, #102715 |
+| Category | Feature | Status | Reviews |
+| ---------------- | ----------------------------------------------------------------------------------------------------------------------- | ------------------ | -------------------------------------------------------------- |
+| atomic extension | ['atomic' strictly nested within 'teams'](https://openmp.llvm.org/docs/openacc/OpenMPExtensions.html#atomicWithinTeams) | {part}`prototyped` | [D126323][D126323] |
+| device extension | ['ompx_hold' map type modifier](https://openmp.llvm.org/docs/openacc/OpenMPExtensions.html#ompx-hold) | {part}`prototyped` | [D106509][D106509], [D106510][D106510] |
+| device extension | ['ompx_bare' clause on 'target teams' construct](https://www.osti.gov/servlets/purl/2205717) | {part}`prototyped` | [PR66844][PR66844], [PR70612][PR70612] |
+| device extension | Multi-dim 'num_teams' and 'thread_limit' clause on 'target teams ompx_bare' construct | {part}`partial` | [PR99732][PR99732], [PR101407][PR101407], [PR102715][PR102715] |
+
+
+[D50522]: https://reviews.llvm.org/D50522
+[D51107]: https://reviews.llvm.org/D51107
+[D51233]: https://reviews.llvm.org/D51233
+[D51378]: https://reviews.llvm.org/D51378
+[D52359]: https://reviews.llvm.org/D52359
+[D52625]: https://reviews.llvm.org/D52625
+[D52780]: https://reviews.llvm.org/D52780
+[D53079]: https://reviews.llvm.org/D53079
+[D53380]: https://reviews.llvm.org/D53380
+[D53513]: https://reviews.llvm.org/D53513
+[D54342]: https://reviews.llvm.org/D54342
+[D54441]: https://reviews.llvm.org/D54441
+[D55078]: https://reviews.llvm.org/D55078
+[D55719]: https://reviews.llvm.org/D55719
+[D55892]: https://reviews.llvm.org/D55892
+[D55982]: https://reviews.llvm.org/D55982
+[D56326]: https://reviews.llvm.org/D56326
+[D57576]: https://reviews.llvm.org/D57576
+[D58074]: https://reviews.llvm.org/D58074
+[D58523]: https://reviews.llvm.org/D58523
+[D58638]: https://reviews.llvm.org/D58638
+[D59474]: https://reviews.llvm.org/D59474
+[D60972]: https://reviews.llvm.org/D60972
+[D64095]: https://reviews.llvm.org/D64095
+[D67294]: https://reviews.llvm.org/D67294
+[D69204]: https://reviews.llvm.org/D69204
+[D71179]: https://reviews.llvm.org/D71179
+[D71830]: https://reviews.llvm.org/D71830
+[D71847]: https://reviews.llvm.org/D71847
+[D74144]: https://reviews.llvm.org/D74144
+[D74956]: https://reviews.llvm.org/D74956
+[D75591]: https://reviews.llvm.org/D75591
+[D76342]: https://reviews.llvm.org/D76342
+[D83061]: https://reviews.llvm.org/D83061
+[D83062]: https://reviews.llvm.org/D83062
+[D84422]: https://reviews.llvm.org/D84422
+[D84711]: https://reviews.llvm.org/D84711
+[D84712]: https://reviews.llvm.org/D84712
+[D90752]: https://reviews.llvm.org/D90752
+[D91944]: https://reviews.llvm.org/D91944
+[D92427]: https://reviews.llvm.org/D92427
+[D95003]: https://reviews.llvm.org/D95003
+[D97085]: https://reviews.llvm.org/D97085
+[D98558]: https://reviews.llvm.org/D98558
+[D98815]: https://reviews.llvm.org/D98815
+[D98834]: https://reviews.llvm.org/D98834
+[D99459]: https://reviews.llvm.org/D99459
+[D99537]: https://reviews.llvm.org/D99537
+[D99679]: https://reviews.llvm.org/D99679
+[D99914]: https://reviews.llvm.org/D99914
+[D99995]: https://reviews.llvm.org/D99995
+[D100514]: https://reviews.llvm.org/D100514
+[D105648]: https://reviews.llvm.org/D105648
+[D106509]: https://reviews.llvm.org/D106509
+[D106510]: https://reviews.llvm.org/D106510
+[D106674]: https://reviews.llvm.org/D106674
+[D109635]: https://reviews.llvm.org/D109635
+[D113540]: https://reviews.llvm.org/D113540
+[D115683]: https://reviews.llvm.org/D115683
+[D116261]: https://reviews.llvm.org/D116261
+[D116637]: https://reviews.llvm.org/D116637
+[D118383]: https://reviews.llvm.org/D118383
+[D118547]: https://reviews.llvm.org/D118547
+[D118632]: https://reviews.llvm.org/D118632
+[D120007]: https://reviews.llvm.org/D120007
+[D120200]: https://reviews.llvm.org/D120200
+[D120290]: https://reviews.llvm.org/D120290
+[D122107]: https://reviews.llvm.org/D122107
+[D123235]: https://reviews.llvm.org/D123235
+[D123286]: https://reviews.llvm.org/D123286
+[D125828]: https://reviews.llvm.org/D125828
+[D125912]: https://reviews.llvm.org/D125912
+[D126321]: https://reviews.llvm.org/D126321
+[D126323]: https://reviews.llvm.org/D126323
+[D127855]: https://reviews.llvm.org/D127855
+[D128347]: https://reviews.llvm.org/D128347
+[D131830]: https://reviews.llvm.org/D131830
+[D136103]: https://reviews.llvm.org/D136103
+[D138769]: https://reviews.llvm.org/D138769
+[D139166]: https://reviews.llvm.org/D139166
+[D141531]: https://reviews.llvm.org/D141531
+[D141540]: https://reviews.llvm.org/D141540
+[D141545]: https://reviews.llvm.org/D141545
+[D144634]: https://reviews.llvm.org/D144634
+[D145823]: https://reviews.llvm.org/D145823
+[D146418]: https://reviews.llvm.org/D146418
+[D152054]: https://reviews.llvm.org/D152054
+[D155003]: https://reviews.llvm.org/D155003
+[D157933]: https://reviews.llvm.org/D157933
+[PR66844]: https://github.com/llvm/llvm-project/pull/66844
+[PR70612]: https://github.com/llvm/llvm-project/pull/70612
+[PR13580]: https://github.com/llvm/llvm-project/pull/13580
+[PR90499]: https://github.com/llvm/llvm-project/pull/90499
+[PR92030]: https://github.com/llvm/llvm-project/pull/92030
+[PR92916]: https://github.com/llvm/llvm-project/pull/92916
+[PR93022]: https://github.com/llvm/llvm-project/pull/93022
+[PR97429]: https://github.com/llvm/llvm-project/pull/97429
+[PR99732]: https://github.com/llvm/llvm-project/pull/99732
+[PR101101]: https://github.com/llvm/llvm-project/pull/101101
+[PR101407]: https://github.com/llvm/llvm-project/pull/101407
+[PR102715]: https://github.com/llvm/llvm-project/pull/102715
+[PR109197]: https://github.com/llvm/llvm-project/pull/109197
+[PR114072]: https://github.com/llvm/llvm-project/pull/114072
+[PR114883]: https://github.com/llvm/llvm-project/pull/114883
+[PR119891]: https://github.com/llvm/llvm-project/pull/119891
+[PR121741]: https://github.com/llvm/llvm-project/pull/121741
+[PR121746]: https://github.com/llvm/llvm-project/pull/121746
+[PR121814]: https://github.com/llvm/llvm-project/pull/121814
+[PR121914]: https://github.com/llvm/llvm-project/pull/121914
+[PR121916]: https://github.com/llvm/llvm-project/pull/121916
+[PR125621]: https://github.com/llvm/llvm-project/pull/125621
+[PR125933]: https://github.com/llvm/llvm-project/pull/125933
+[PR128640]: https://github.com/llvm/llvm-project/pull/128640
+[PR129888]: https://github.com/llvm/llvm-project/pull/129888
+[PR129938]: https://github.com/llvm/llvm-project/pull/129938
+[PR134709]: https://github.com/llvm/llvm-project/pull/134709
+[PR138294]: https://github.com/llvm/llvm-project/pull/138294
+[PR139293]: https://github.com/llvm/llvm-project/pull/139293
+[PR143442]: https://github.com/llvm/llvm-project/pull/143442
+[PR144635]: https://github.com/llvm/llvm-project/pull/144635
+[PR146093]: https://github.com/llvm/llvm-project/pull/146093
+[PR146403]: https://github.com/llvm/llvm-project/pull/146403
+[PR146404]: https://github.com/llvm/llvm-project/pull/146404
+[PR146405]: https://github.com/llvm/llvm-project/pull/146405
+[PR148048]: https://github.com/llvm/llvm-project/pull/148048
+[PR149036]: https://github.com/llvm/llvm-project/pull/149036
+[PR149586]: https://github.com/llvm/llvm-project/pull/149586
+[PR152786]: https://github.com/llvm/llvm-project/pull/152786
+[PR153683]: https://github.com/llvm/llvm-project/pull/153683
+[PR153807]: https://github.com/llvm/llvm-project/pull/153807
+[PR154779]: https://github.com/llvm/llvm-project/pull/154779
+[PR157025]: https://github.com/llvm/llvm-project/pull/157025
+[PR158134]: https://github.com/llvm/llvm-project/pull/158134
+[PR158336]: https://github.com/llvm/llvm-project/pull/158336
+[PR158370]: https://github.com/llvm/llvm-project/pull/158370
+[PR158712]: https://github.com/llvm/llvm-project/pull/158712
+[PR159112]: https://github.com/llvm/llvm-project/pull/159112
+[PR159628]: https://github.com/llvm/llvm-project/pull/159628
+[PR160659]: https://github.com/llvm/llvm-project/pull/160659
+[PR161213]: https://github.com/llvm/llvm-project/pull/161213
+[PR162910]: https://github.com/llvm/llvm-project/pull/162910
+[PR168898]: https://github.com/llvm/llvm-project/pull/168898
+[PR168905]: https://github.com/llvm/llvm-project/pull/168905
+[PR169558]: https://github.com/llvm/llvm-project/pull/169558
+[PR169603]: https://github.com/llvm/llvm-project/pull/169603
+[PR170578]: https://github.com/llvm/llvm-project/pull/170578
+[PR173931]: https://github.com/llvm/llvm-project/pull/173931
+[PR174646]: https://github.com/llvm/llvm-project/pull/174646
+[PR174659]: https://github.com/llvm/llvm-project/pull/174659
+[PR186281]: https://github.com/llvm/llvm-project/pull/186281
+[PR189347]: https://github.com/llvm/llvm-project/pull/189347
+[PR194168]: https://github.com/llvm/llvm-project/pull/194168
+[PR195829]: https://github.com/llvm/llvm-project/pull/195829
+[PR196431]: https://github.com/llvm/llvm-project/pull/196431
[discourse forums (runtimes - openmp category)]: https://discourse.llvm.org/c/runtimes/openmp/35
diff --git a/clang/docs/OverflowBehaviorTypes.md b/clang/docs/OverflowBehaviorTypes.md
index 3f539a5232975..0429e6593c883 100644
--- a/clang/docs/OverflowBehaviorTypes.md
+++ b/clang/docs/OverflowBehaviorTypes.md
@@ -151,20 +151,11 @@ variety of scenarios is detailed below.
auto result = a + b; // result is __ob_trap int (C promotes u16->int, dominance gives trap)
```
-```{eval-rst}
-.. list-table:: Promotion Rules Summary
- :widths: 30 70
- :header-rows: 1
-
- * - Operation Type
- - Result Type
- * - OBT + Standard Integer
- - Standard C conversion result with OBT qualifier applied
- * - Same Kind OBTs (both ``wrap`` or both ``trap``)
- - Standard C conversion result with common overflow behavior
- * - Different Kind OBTs (``wrap`` + ``trap``)
- - Standard C conversion result with ``trap`` behavior (dominance)
-```
+| Operation Type | Result Type |
+| ------------------------------------------- | --------------------------------------------------------------- |
+| OBT + Standard Integer | Standard C conversion result with OBT qualifier applied |
+| Same Kind OBTs (both `wrap` or both `trap`) | Standard C conversion result with common overflow behavior |
+| Different Kind OBTs (`wrap` + `trap`) | Standard C conversion result with `trap` behavior (dominance) |
**Overflow Behavior Dominance Rules:**
@@ -431,30 +422,10 @@ The `overflow_behavior` attribute interacts with sanitizers, `-ftrapv`,
`-fwrapv`, and Sanitizer Special Case Lists (SSCL) by wholly overriding these
global flags. The following table summarizes the interactions:
-```{eval-rst}
-.. list-table:: Overflow Behavior Precedence
- :widths: 15 15 15 15 20 15
- :header-rows: 1
-
- * - Behavior
- - Default(No Flags)
- - -ftrapv
- - -fwrapv
- - Sanitizers
- - SSCL
- * - ``overflow_behavior(wrap)``
- - Wraps
- - Wraps
- - Wraps
- - No report, Wraps
- - Overrides SSCL
- * - ``overflow_behavior(trap)``
- - Traps
- - Traps
- - Traps
- - Reports
- - Overrides SSCL
-```
+| Behavior | Default(No Flags) | -ftrapv | -fwrapv | Sanitizers | SSCL |
+| ------------------------- | ----------------- | ------- | ------- | ---------------- | -------------- |
+| `overflow_behavior(wrap)` | Wraps | Wraps | Wraps | No report, Wraps | Overrides SSCL |
+| `overflow_behavior(trap)` | Traps | Traps | Traps | Reports | Overrides SSCL |
It is important to note the distinction between signed and unsigned types. For
unsigned integers, which wrap on overflow by default, `overflow_behavior(trap)`
diff --git a/clang/docs/PointerAuthentication.md b/clang/docs/PointerAuthentication.md
index 39bb9612d380a..fde6d00915369 100644
--- a/clang/docs/PointerAuthentication.md
+++ b/clang/docs/PointerAuthentication.md
@@ -64,7 +64,7 @@ particular name is consistent throughout a process.
A **discriminator** is an arbitrary value used to **diversify** signed pointers
so that one validly-signed pointer cannot simply be copied over another.
A discriminator is simply opaque data of some implementation-defined size that
-is included in the signature as a salt (see [Discriminators] for details.)
+is included in the signature as a salt (see [Discriminators](#discriminators) for details.)
Nearly all aspects of pointer authentication use just these two primary
operations:
@@ -112,7 +112,7 @@ clarity of description. They are not suitable either as high-level
interfaces or as primitives in a compiler IR because they expose raw
pointers. Raw pointers require special attention in the language
implementation to avoid the accidental creation of exploitable code
-sequences; see the section on [Attackable code sequences].
+sequences; see the section on [Attackable code sequences](#attackable-code-sequences).
:::
The following details are all implementation-defined:
@@ -125,7 +125,7 @@ The following details are all implementation-defined:
While the use of the terms "sign" and "signed pointer" suggest the use of
a cryptographic signature, other implementations may be possible. See
-[Alternative implementations] for an exploration of implementation options.
+[Alternative implementations](#alternative-implementations) for an exploration of implementation options.
:::{admonition} Implementation example: Armv8.3
Readers may find it helpful to know how these terms map to Armv8.3 PAuth:
@@ -229,7 +229,7 @@ authenticating code to agree about the **signing schema** for the pointer:
- the abstract signing key with which the pointer should be signed and
- an algorithm for computing the discriminator.
-As described in the section above on [Discriminators], in most situations, the
+As described in the section above on [Discriminators](#discriminators), in most situations, the
discriminator is produced by taking a constant discriminator and optionally
blending it with the storage address of the pointer. In these situations, the
signing schema breaks down even more simply:
@@ -242,7 +242,7 @@ It is important that the signing schema be independently derived at all signing
and authentication sites. Preferably, the schema should be hard-coded
everywhere it is needed, but at the very least, it must not be derived by
inspecting information stored along with the pointer. See the section on
-[Attacks on pointer authentication] for more information.
+[Attacks on pointer authentication](#attacks-on-pointer-authentication) for more information.
## Language features
@@ -283,7 +283,7 @@ when the branch is performed. This includes:
global offset table (GOT) used to implement direct calls to functions defined
outside of the current shared object.
-For more information about this, see the [Language ABI] section.
+For more information about this, see the [Language ABI](#language-abi) section.
However, some aspects of the implementation are observable by the programmer or
otherwise require special notice.
@@ -292,10 +292,10 @@ otherwise require special notice.
The current implementation in Clang does not sign pointers to ordinary data by
default. For a partial explanation of the reasoning behind this, see the
-[Theory of Operation] section.
+[Theory of operation](#theory-of-operation) section.
A specific data pointer which is more security-sensitive than most can be
-signed using the [\_\_ptrauth qualifier][__ptrauth qualifier] or using the `<ptrauth.h>`
+signed using the [`__ptrauth` qualifier](#ptrauth-qualifier) or using the `<ptrauth.h>`
intrinsics.
#### C function pointers
@@ -303,10 +303,10 @@ intrinsics.
The C standard imposes restrictions on the representation and semantics of
function pointer types which make it difficult to achieve satisfactory
signature diversity in the default language rules. See [Attacks on pointer
-authentication][attacks on pointer authentication] for more information about signature diversity. Programmers
+authentication](#attacks-on-pointer-authentication) for more information about signature diversity. Programmers
should strongly consider using the `__ptrauth` qualifier to improve the
protections for important function pointers, such as the components of of
-a hand-rolled "v-table"; see the section on the [\_\_ptrauth qualifier][__ptrauth qualifier] for
+a hand-rolled "v-table"; see the section on the [`__ptrauth` qualifier](#ptrauth-qualifier) for
details.
The value of a pointer to a C function includes a signature, even when the
@@ -348,7 +348,7 @@ These tools must be updated to correctly account for pointer authentication,
either by stripping signatures (if security is not important for the tool, e.g.
if it is capturing a stack trace during a crash) or properly authenticating
them. More information about how these values are signed is available in the
-[Language ABI] section.
+[Language ABI](#language-abi) section.
#### C++ virtual functions
@@ -412,7 +412,7 @@ The qualifier's operands are as follows:
a constant expression with one of these two values
- `discriminator` - a constant discriminator; must be a constant expression
-See [Discriminators] for more information about discriminators.
+See [Discriminators](#discriminators) for more information about discriminators.
Currently the operands must be constant-evaluable even within templates. In the
future this restriction may be lifted to allow value-dependent expressions as
@@ -432,7 +432,7 @@ a discriminator determined as follows:
`&x`; otherwise
- if `address` is 1 and `discriminator` is non-zero, then the discriminator
is `ptrauth_blend_discriminator(&x, discriminator)`; see
- [ptrauth_blend_discriminator].
+ [`ptrauth_blend_discriminator`](#ptrauth-blend-discriminator).
##### Non-triviality from address diversity
@@ -1042,7 +1042,7 @@ The implementation can avoid this by obeying two basic rules:
##### Register clobbering
-As a refinement of the section on [Attackable code sequences], if the attacker
+As a refinement of the section on [Attackable code sequences](#attackable-code-sequences), if the attacker
has the ability to modify arbitrary *register* state at arbitrary points in the
program, then special care must be taken.
@@ -1071,7 +1071,7 @@ success in doing exactly that. Even ignoring that, though, we should aim to
protect against lucky attackers just as much as good ones.)
To protect against this, saved register state must be at least partially signed
-(using something like [ptrauth_sign_generic_data]). This is required for
+(using something like [`ptrauth_sign_generic_data`](#ptrauth-sign-generic-data)). This is required for
correctness anyway because saved thread states include security-critical
registers such as SP, FP, PC, and LR (where applicable). Ideally, this
signature would cover all the registers, but since saving and restoring
@@ -1101,7 +1101,7 @@ it does take extra considerations to make it secure:
- Relative addresses must only be stored in read-only memory. A writable
relative address can be overwritten to point nearly anywhere, making it
inherently insecure; this danger can only be compensated for with techniques
- for protecting arbitrary data like [ptrauth_sign_generic_data].
+ for protecting arbitrary data like [`ptrauth_sign_generic_data`](#ptrauth-sign-generic-data).
- Relative addresses must only be accessed through signed pointers with adequate
diversity. If an attacker can perform an `access path attack` to replace the
pointer through which the relative address is accessed, they can easily cause
@@ -1138,7 +1138,7 @@ pointer authentication.
- If an attacker can remap read-only program data sections to be writable, then
any use of {ref}`relative addresses <relative-addresses>` in global data becomes insecure.
- On platforms that use them, if an attacker can remap the memory containing
- the [global offset tables] as writable, then any unsigned pointers in those
+ the [global offset tables](#global-offset-tables) as writable, then any unsigned pointers in those
tables are insecure.
Remapping memory in this way often requires the attacker to have already
@@ -1277,7 +1277,7 @@ the result reduced by modulo to the range of non-zero discriminators (i.e.
### Return addresses
The kernel must ensure that attackers cannot replace LR due to an asynchronous
-exception; see [Register clobbering]. If this is done by generally protecting
+exception; see [Register clobbering](#register-clobbering). If this is done by generally protecting
LR, then functions which don't spill LR to the stack can avoid signing it
entirely. Otherwise, the return address must be signed; on arm64e it is signed
with the `IB` key using the stack pointer on entry as the discriminator.
@@ -1299,10 +1299,10 @@ but more importantly, it defines away the potential for several attacks:
- Attackers cannot change instructions, so there is no way to cause this code
sequence to materialize a different pointer, whereas an access via the GOT
always has *at minimum* a probabilistic chance to be the target of successful
- [substitution attacks].
+ [substitution attacks](#substitution-attacks).
- The GOT is a dense pool of fixed pointers at a fixed offset relative to code;
attackers can search this pool for useful pointers that can be used in
- [substitution attacks], whereas pointers that are only materialized directly
+ [substitution attacks](#substitution-attacks), whereas pointers that are only materialized directly
are not so easily available.
- Similarly, attackers can use {ref}`access path attacks <access-path-attacks>` to replace a pointer to a
signed pointer with a pointer to the GOT if the signing schema used within the
@@ -1312,7 +1312,7 @@ but more importantly, it defines away the potential for several attacks:
If this can be done for a symbol, then the compiler need only ensure that it
materializes the signed pointer using registers that are safe against
-[register clobbering].
+[register clobbering](#register-clobbering).
However, many symbols can only be accessed via the GOT, e.g. because they
resolve to definitions outside of the current image. In this case, care must
@@ -1324,7 +1324,7 @@ be taken to ensure that using the GOT does not introduce weaknesses.
and access-path attacks above. Storing raw pointers in this way is usually
extremely unsafe, but for the special case of an immutable GOT entry it's fine
because the GOT is always accessed via an address that is directly
- materialized in code and thus provably unattackable. (But see [Remapping].)
+ materialized in code and thus provably unattackable. (But see [Remapping](#remapping).)
- Otherwise, GOT entries which are used for producing a signed pointer constant
must be signed. The signing schema used in the GOT need not match the target
signing schema for the signed constant. To counteract the threats of
@@ -1335,7 +1335,7 @@ be taken to ensure that using the GOT does not introduce weaknesses.
In either case, the compiler must ensure that materializing the address of a GOT
entry as part of producing a signed pointer constant is not vulnerable to
-[register clobbering]. If the linker also generates code for this, e.g. for
+[register clobbering](#register-clobbering). If the linker also generates code for this, e.g. for
call stubs, this generated code must take the same precautions.
### Dynamic symbol lookup
@@ -1382,7 +1382,7 @@ function pointers back and forth, or only does so through
By default the pointer to a C++ virtual table is currently signed with the
`DA` key, address diversity, and a constant discriminator equal to the string
-hash (see [ptrauth_string_discriminator]) of the mangled v-table identifier
+hash (see [`ptrauth_string_discriminator`](#ptrauth-string-discriminator)) of the mangled v-table identifier
of the primary base class for the v-table. To support existing code or ABI
constraints it is possible to use the `ptrauth_vtable_pointer` attribute to
override the schema used for the v-table pointer of the base type of
@@ -1391,7 +1391,7 @@ key, address diversity mode, and any extra constant discriminator to be used.
Virtual functions in a C++ virtual table are signed with the `IA` key, address
diversity, and a constant discriminator equal to the string hash (see
-[ptrauth_string_discriminator]) of the mangled name of the function which
+[`ptrauth_string_discriminator`](#ptrauth-string-discriminator)) of the mangled name of the function which
originally gave rise to the v-table slot.
### C++ dynamic_cast
@@ -1423,7 +1423,7 @@ and no additional diversity.
A member function pointer is signed with the `IA` key, no address diversity,
and a constant discriminator equal to the string hash
-(see [ptrauth_string_discriminator]) of the member pointer type. Address
+(see [`ptrauth_string_discriminator`](#ptrauth-string-discriminator)) of the member pointer type. Address
diversity is not permitted by C++ for member function pointers because they must
be trivially-copyable types.
diff --git a/clang/docs/SYCLSupport.md b/clang/docs/SYCLSupport.md
index 57ff207457979..4271c8e12cdfa 100644
--- a/clang/docs/SYCLSupport.md
+++ b/clang/docs/SYCLSupport.md
@@ -92,24 +92,13 @@ data with the address space attribute or not.
To utilize clang's existing functionality, we reuse the following OpenCL address
space attributes for pointers:
-```{eval-rst}
-.. list-table::
- :header-rows: 1
-
- * - Address space attribute
- - SYCL address_space enumeration
- * - ``__attribute__((opencl_global))``
- - global_space, constant_space
- * - ``__attribute__((opencl_global_device))``
- - global_space
- * - ``__attribute__((opencl_global_host))``
- - global_space
- * - ``__attribute__((opencl_local))``
- - local_space
- * - ``__attribute__((opencl_private))``
- - private_space
-
-```
+| Address space attribute | SYCL address_space enumeration |
+| ----------------------------------------------- | ------------------------------ |
+| `__attribute__((opencl_global))` | global_space, constant_space |
+| `__attribute__((opencl_global_device))` | global_space |
+| `__attribute__((opencl_global_host))` | global_space |
+| `__attribute__((opencl_local))` | local_space |
+| `__attribute__((opencl_private))` | private_space |
```C++
//TODO: add support for __attribute__((opencl_global_host)) and __attribute__((opencl_global_device)).
diff --git a/clang/docs/ShadowCallStack.md b/clang/docs/ShadowCallStack.md
index bcb6c480b4e8b..62bfaa83040ea 100644
--- a/clang/docs/ShadowCallStack.md
+++ b/clang/docs/ShadowCallStack.md
@@ -15,11 +15,11 @@ in the function epilog. The return address is also stored on the regular stack
for compatibility with unwinders, but is otherwise unused.
The aarch64 implementation is considered production ready, and
-an [implementation of the runtime] has been added to Android's libc
+an [implementation of the runtime][scs-runtime] has been added to Android's libc
(bionic). An x86_64 implementation was evaluated using Chromium and was found
to have critical performance and security deficiencies--it was removed in
LLVM 9.0. Details on the x86_64 implementation can be found in the
-[Clang 7.0.1 documentation].
+[Clang 7.0.1 documentation][clang-701-doc].
### Comparison
@@ -29,12 +29,12 @@ schemes, like {doc}`SafeStack`, that mirror the entire stack and trade-off
consuming more memory for shorter function prologs and epilogs with fewer
memory accesses.
-[Return Flow Guard] is a pure software implementation of shadow call stacks
+[Return Flow Guard][rfg] is a pure software implementation of shadow call stacks
on x86_64. Like the previous implementation of ShadowCallStack on x86_64, it is
inherently racy due to the architecture's use of the stack for calls and
returns.
-Intel [Control-flow Enforcement Technology] (CET) is a proposed hardware
+Intel [Control-flow Enforcement Technology][cet] (CET) is a proposed hardware
extension that would add native support to use a shadow stack to store/check
return addresses at call/return time. Being a hardware implementation, it
would not suffer from race conditions and would not incur the overhead of
@@ -49,7 +49,7 @@ and destruction would need to be intercepted by the application.
The instrumentation makes use of the platform register `x18` on AArch64,
`x3` (`gp`) on RISC-V with software shadow stack and `ssp` on RISC-V with
-hardware shadow stack, which needs [Zicfiss] and `-fcf-protection=return`.
+hardware shadow stack, which needs [Zicfiss][zicfiss] and `-fcf-protection=return`.
Users can choose between the software and hardware based shadow stack
implementation on RISC-V backend by passing `-fsanitize=shadow-call-stack`
or `Zicfiss` with `-fcf-protection=return`.
@@ -61,7 +61,7 @@ reserves `SCSReg` (currently Android, Darwin, Fuchsia and Windows) or be
compiled with a flag to reserve that register (e.g., `-ffixed-x18`). If
absolutely necessary, code compiled without reserving the register may be run on
the same thread as code that uses ShadowCallStack by saving the register value
-temporarily on the stack ([example in Android]) but this should be done with
+temporarily on the stack ([example in Android][android-example]) but this should be done with
care since it risks leaking the shadow call stack address.
Because it requires a dedicated register, the ShadowCallStack feature is
@@ -90,7 +90,8 @@ call stack, meaning that references to the shadow call stack do not have
to be stored in memory. This makes it possible to implement a runtime that
avoids exposing the address of the shadow call stack to attackers that can
read arbitrary memory. However, attackers could still try to exploit side
-channels exposed by the operating system [[1]] [[2]] or processor [[3]]
+channels exposed by the operating system [[1]][scs-cartography] [[2]][safestack-bypass]
+or processor [[3]][anc]
to discover the address of the shadow call stack.
Unless care is taken when allocating the shadow call stack, it may be
@@ -100,8 +101,8 @@ difficult. One way to do this is to allocate a large guard region without
read/write permissions, randomly select a small region within it to be
used as the address of the shadow call stack and mark only that region as
read/write. This also mitigates somewhat against processor side channels.
-The intent is that the Android runtime [will do this], but the platform will
-first need to be [changed] to avoid using `setrlimit(RLIMIT_AS)` to limit
+The intent is that the Android runtime [will do this][android-will-do-this], but the platform will
+first need to be [changed][android-changed] to avoid using `setrlimit(RLIMIT_AS)` to limit
memory allocations in certain processes, as this also limits the number of
guard regions that can be allocated.
@@ -120,7 +121,7 @@ the address of the start of the guard region is already somewhat guessable.
One way in which the address of the shadow call stack could leak is in the
`jmp_buf` data structure used by `setjmp` and `longjmp`. The Android
-runtime [avoids this] by only storing the low bits of `SCSReg` in the
+runtime [avoids this][android-avoids-this] by only storing the low bits of `SCSReg` in the
`jmp_buf`, which requires the address of the shadow call stack to be
aligned to its size.
@@ -196,15 +197,15 @@ ldr x30, [x18, #-8]!
ret
```
-[[1]]: https://eyalitkin.wordpress.com/2017/09/01/cartography-lighting-up-the-shadows/
-[[2]]: https://www.blackhat.com/docs/eu-16/materials/eu-16-Goktas-Bypassing-Clangs-SafeStack.pdf
-[[3]]: https://www.vusec.net/projects/anc/
-[avoids this]: https://android.googlesource.com/platform/bionic/+/808d176e7e0dd727c7f929622ec017f6e065c582/libc/arch-arm64/bionic/setjmp.S#49
-[changed]: https://android-review.googlesource.com/c/platform/frameworks/av/+/837745
-[clang 7.0.1 documentation]: https://releases.llvm.org/7.0.1/tools/clang/docs/ShadowCallStack.html
-[control-flow enforcement technology]: https://software.intel.com/sites/default/files/managed/4d/2a/control-flow-enforcement-technology-preview.pdf
-[example in android]: https://android-review.googlesource.com/c/platform/frameworks/base/+/803717
-[implementation of the runtime]: https://android.googlesource.com/platform/bionic/+/808d176e7e0dd727c7f929622ec017f6e065c582/libc/bionic/pthread_create.cpp#128
-[return flow guard]: https://xlab.tencent.com/en/2016/11/02/return-flow-guard/
-[will do this]: https://android-review.googlesource.com/c/platform/bionic/+/891622
+[android-avoids-this]: https://android.googlesource.com/platform/bionic/+/808d176e7e0dd727c7f929622ec017f6e065c582/libc/arch-arm64/bionic/setjmp.S#49
+[android-changed]: https://android-review.googlesource.com/c/platform/frameworks/av/+/837745
+[android-example]: https://android-review.googlesource.com/c/platform/frameworks/base/+/803717
+[android-will-do-this]: https://android-review.googlesource.com/c/platform/bionic/+/891622
+[anc]: https://www.vusec.net/projects/anc/
+[cet]: https://software.intel.com/sites/default/files/managed/4d/2a/control-flow-enforcement-technology-preview.pdf
+[clang-701-doc]: https://releases.llvm.org/7.0.1/tools/clang/docs/ShadowCallStack.html
+[rfg]: https://xlab.tencent.com/en/2016/11/02/return-flow-guard/
+[safestack-bypass]: https://www.blackhat.com/docs/eu-16/materials/eu-16-Goktas-Bypassing-Clangs-SafeStack.pdf
+[scs-cartography]: https://eyalitkin.wordpress.com/2017/09/01/cartography-lighting-up-the-shadows/
+[scs-runtime]: https://android.googlesource.com/platform/bionic/+/808d176e7e0dd727c7f929622ec017f6e065c582/libc/bionic/pthread_create.cpp#128
[zicfiss]: https://github.com/riscv/riscv-cfi/blob/main/cfi_backward.adoc
diff --git a/clang/docs/StandardCPlusPlusModules.md b/clang/docs/StandardCPlusPlusModules.md
index af1df6d5ed464..e9a1c332fe8a2 100644
--- a/clang/docs/StandardCPlusPlusModules.md
+++ b/clang/docs/StandardCPlusPlusModules.md
@@ -390,7 +390,7 @@ are added to the archive instead.
`clang-cl` supports the same options as `clang++` for modules as detailed above;
there is no need to prefix these options with `/clang:`. Note that `cl.exe`
-`options to emit/consume IFC files <https://devblogs.microsoft.com/cppblog/using-cpp-modules-in-msvc-from-the-command-line-part-1/>` are *not* supported.
+[options to emit/consume IFC files](https://devblogs.microsoft.com/cppblog/using-cpp-modules-in-msvc-from-the-command-line-part-1/) are *not* supported.
The resulting precompiled modules are also not compatible for use with `cl.exe`.
We recommend that build system authors use the above-mentioned `clang++` options with `clang-cl` to build modules.
diff --git a/clang/docs/ThinLTO.md b/clang/docs/ThinLTO.md
index 9580b02e2b61b..104492377ffea 100644
--- a/clang/docs/ThinLTO.md
+++ b/clang/docs/ThinLTO.md
@@ -22,7 +22,7 @@ whole-program analysis is then performed on the combined summary index.
However, all transformations, including function importing, occur
later when the modules are optimized in fully parallel backends.
-By default, [linkers] that support ThinLTO are set up to launch
+By default, [linkers](#linkers) that support ThinLTO are set up to launch
the ThinLTO backends in threads. So the usage model is not affected
as the distinction between the fast serial thin link step and the backends
is transparent to the user.
@@ -198,8 +198,8 @@ Possible key-value pairs are:
To [bootstrap clang/LLVM](https://llvm.org/docs/AdvancedBuilds.html#bootstrap-builds)
with ThinLTO, follow these steps:
-1. The host [compiler] must be a version of clang that supports ThinLTO.
-2. The host [linker] must support ThinLTO (and in the case of gold, must be
+1. The host [compiler](#compiler) must be a version of clang that supports ThinLTO.
+2. The host [linker](#linker) must support ThinLTO (and in the case of gold, must be
[configured with plugins enabled](https://llvm.org/docs/GoldPlugin.html)).
3. Use the following additional [CMake variables](https://llvm.org/docs/CMake.html#options-and-variables)
when configuring the bootstrap compiler build:
@@ -220,7 +220,7 @@ with ThinLTO, follow these steps:
> - `-DCMAKE_AR=/path/to/host/llvm-ar.exe`
1. To use additional linker arguments for controlling the backend
- [parallelism] or enabling [incremental] builds of the bootstrap compiler,
+ [parallelism](#parallelism) or enabling [incremental](#incremental) builds of the bootstrap compiler,
after configuring the build, modify the resulting CMakeCache.txt file in the
build directory. Specify any additional linker options after
`CMAKE_EXE_LINKER_FLAGS:STRING=`. Note the configure may fail if
diff --git a/clang/docs/UsersManual.md b/clang/docs/UsersManual.md
index bf5057e0c8d77..756f2784dc076 100644
--- a/clang/docs/UsersManual.md
+++ b/clang/docs/UsersManual.md
@@ -1638,48 +1638,40 @@ Clang provides a number of ways to control floating point behavior, including
with command line options and source pragmas. This section
describes the various floating point semantic modes and the corresponding options.
-```{eval-rst}
-.. csv-table:: Floating Point Semantic Modes
- :header: "Mode", "Values"
- :widths: 15, 30, 30
-
- "ffp-exception-behavior", "{ignore, strict, maytrap}",
- "fenv_access", "{off, on}", "(none)"
- "frounding-math", "{dynamic, tonearest, downward, upward, towardzero}"
- "ffp-contract", "{on, off, fast, fast-honor-pragmas}"
- "fdenormal-fp-math", "{IEEE, PreserveSign, PositiveZero}"
- "fdenormal-fp-math-fp32", "{IEEE, PreserveSign, PositiveZero}"
- "fmath-errno", "{on, off}"
- "fhonor-nans", "{on, off}"
- "fhonor-infinities", "{on, off}"
- "fsigned-zeros", "{on, off}"
- "freciprocal-math", "{on, off}"
- "fallow-approximate-fns", "{on, off}"
- "fassociative-math", "{on, off}"
- "fcomplex-arithmetic", "{basic, improved, full, promoted}"
-```
+| Mode | Values | |
+| ----------------------- | -------------------------------------------------- | ------ |
+| ffp-exception-behavior | {ignore, strict, maytrap} | |
+| fenv_access | {off, on} | (none) |
+| frounding-math | {dynamic, tonearest, downward, upward, towardzero} | |
+| ffp-contract | {on, off, fast, fast-honor-pragmas} | |
+| fdenormal-fp-math | {IEEE, PreserveSign, PositiveZero} | |
+| fdenormal-fp-math-fp32 | {IEEE, PreserveSign, PositiveZero} | |
+| fmath-errno | {on, off} | |
+| fhonor-nans | {on, off} | |
+| fhonor-infinities | {on, off} | |
+| fsigned-zeros | {on, off} | |
+| freciprocal-math | {on, off} | |
+| fallow-approximate-fns | {on, off} | |
+| fassociative-math | {on, off} | |
+| fcomplex-arithmetic | {basic, improved, full, promoted} | |
This table describes the option settings that correspond to the three
floating point semantic models: precise (the default), strict, and fast.
-```{eval-rst}
-.. csv-table:: Floating Point Models
- :header: "Mode", "Precise", "Strict", "Fast", "Aggressive"
- :widths: 25, 25, 25, 25, 25
-
- "except_behavior", "ignore", "strict", "ignore", "ignore"
- "fenv_access", "off", "on", "off", "off"
- "rounding_mode", "tonearest", "dynamic", "tonearest", "tonearest"
- "contract", "on", "off", "fast", "fast"
- "support_math_errno", "on", "on", "off", "off"
- "no_honor_nans", "off", "off", "off", "on"
- "no_honor_infinities", "off", "off", "off", "on"
- "no_signed_zeros", "off", "off", "on", "on"
- "allow_reciprocal", "off", "off", "on", "on"
- "allow_approximate_fns", "off", "off", "on", "on"
- "allow_reassociation", "off", "off", "on", "on"
- "complex_arithmetic", "full", "full", "promoted", "basic"
-```
+| Mode | Precise | Strict | Fast | Aggressive |
+| --------------------- | --------- | ------- | --------- | ---------- |
+| except_behavior | ignore | strict | ignore | ignore |
+| fenv_access | off | on | off | off |
+| rounding_mode | tonearest | dynamic | tonearest | tonearest |
+| contract | on | off | fast | fast |
+| support_math_errno | on | on | off | off |
+| no_honor_nans | off | off | off | on |
+| no_honor_infinities | off | off | off | on |
+| no_signed_zeros | off | off | on | on |
+| allow_reciprocal | off | off | on | on |
+| allow_approximate_fns | off | off | on | on |
+| allow_reassociation | off | off | on | on |
+| complex_arithmetic | full | full | promoted | basic |
The `-ffp-model` option does not modify the `fdenormal-fp-math`
setting, but it does have an impact on whether `crtfastmath.o` is
>From 7f99bab30aba1698a4d91d32addb4c394260fdb4 Mon Sep 17 00:00:00 2001
From: Reid Kleckner <rkleckner at nvidia.com>
Date: Thu, 9 Jul 2026 08:06:24 -0700
Subject: [PATCH 5/5] Apply suggestion from @llvm-beanz
Co-authored-by: Chris B <chris.bieneman at me.com>
---
clang/docs/HLSL/HLSLDocs.md | 3 +--
1 file changed, 1 insertion(+), 2 deletions(-)
diff --git a/clang/docs/HLSL/HLSLDocs.md b/clang/docs/HLSL/HLSLDocs.md
index 18a088e9f5639..8b72ef88ee0c0 100644
--- a/clang/docs/HLSL/HLSLDocs.md
+++ b/clang/docs/HLSL/HLSLDocs.md
@@ -1,5 +1,4 @@
-```{title} Clang HLSL Documentation
-```
+# Clang HLSL Documentation
```{toctree}
:maxdepth: 1
More information about the llvm-branch-commits
mailing list