Add clang atomic control options and attribute

Add option and statement attribute for controlling emitting of target-specific
metadata to atomicrmw instructions in IR.

The RFC for this attribute and option is
https://discourse.llvm.org/t/rfc-add-clang-atomic-control-options-and-pragmas/80641,
Originally a pragma was proposed, then it was changed to clang attribute.

This attribute allows users to specify one, two, or all three options and must be applied
to a compound statement. The attribute can also be nested, with inner attributes
overriding the options specified by outer attributes or the target's default
options. These options will then determine the target-specific metadata added to atomic
instructions in the IR.

In addition to the attribute, a new compiler option is introduced:
-fatomic=no_remote_memory:{on|off},no_fine_grained_memory:{on|off},ignore_denormal_mode{on|off}.
This compiler option allows users to override the target's default options through the
Clang driver and front end.

In terms of implementation, the atomic attribute is represented in the AST by the
existing AttributedStmt, with minimal changes to AST and Sema.

During code generation in Clang, the CodeGenModule maintains the current atomic options,
which are used to emit the relevant metadata for atomic instructions. RAII is used
to manage the saving and restoring of atomic options when entering
and exiting nested AttributedStmt.

Author: yxsamliu

clang/docs/LanguageExtensions.rst

@@ -5404,6 +5404,115 @@ third argument, can only occur at file scope.
     a = b[i] * c[i] + e;
   }
 
+Extensions for controlling atomic code generation
+=================================================
+
+The ``[[clang::atomic]]`` statement attribute enables users to control how
+atomic operations are lowered in LLVM IR by conveying additional metadata to
+the backend. The primary goal is to allow users to specify certain options,
+like ignoring floating-point denormal modes, or restricting which memory
+regions can be used, without affecting the correctness of code that does not
+rely on these behaviors.
+
+In LLVM, lowering of atomic operations (e.g., ``atomicrmw``) can differ based on
+the target's capabilities. Some backends support native atomic instructions
+only for certain operation types or alignments, or only in specific memory
+regions. Likewise, floating-point atomic instructions may or may not respect
+IEEE denormal requirements. When the user is unconcerned about denormal-mode
+compliance (for performance reasons) or knows that certain atomic operations
+will not function in a particular memory space, extra hints are needed to
+tell the backend how to proceed.
+
+A classic example is an architecture where floating-point atomic add does not
+fully conform to IEEE denormal-mode handling. If the user does not mind ignoring
+that aspect, they would prefer to still emit a faster hardware atomic
+instruction, rather than a fallback or CAS loop. Conversely, on certain GPUs
+(e.g., AMDGPU), memory accessed via PCIe may only support a subset of atomic
+operations (e.g., integer add, exchange, or compare-and-swap). To ensure correct
+and efficient lowering, the compiler must know whether the user wants to prevent 
+the use of these instructions.
+
+Because this is metadata for atomic instructions and can be dropped if the
+backend does not support it, it does not affect correctness (the program's 
+behavior remains correct if the metadata is ignored), but it can significantly
+improve performance or guide code generation in the cases that matter.
+
+The attribute may be applied only to a compound statement and looks like:
+
+.. code-block:: c++
+
+   [[clang::atomic(no_remote_memory, !no_fine_grained_memory, ignore_denormal_mode)]]
+   {
+       // Atomic instructions in this block carry extra metadata reflecting
+       // these user-specified options.
+   }
+
+You can provide one or more of these options, each optionally prefixed with
+``!`` to negate that option. The currently supported options are:
+
+``no_remote_memory``
+   Indicates that atomic operations in this block can assume the accessed memory
+   is not remote memory (relevant for certain GPU memory spaces, like those
+   accessed via PCIe). The prefix ``!`` disables this if a broader scope or
+   command-line had it on.
+
+``no_fine_grained_memory``
+   Suggests that no fine-grained memory regions are accessed by atomic
+   operations. On some GPUs, this can assure certain atomic instructions
+   to work, instead of falling back to CAS loops.
+
+``ignore_denormal_mode``
+   Allows the backend to ignore floating-point denormals for atomic instructions
+   (like 32-bit ``fadd``). This often improves performance on architectures that
+   do not handle denormals efficiently.
+
+Any unspecified option is inherited from the global defaults, which can be set
+by a compiler flag (described below) or the target's built-in defaults.
+
+.. code-block:: c++
+
+   // Suppose we globally set: -fatomic=no_remote_memory:on,no_fine_grained_memory:off
+   // (meaning we do not allow remote memory usage but do allow fine-grained memory)
+
+   void example() {
+       // Locally override the "no_remote_memory" setting to *off* for this block,
+       // but turn on "no_fine_grained_memory".
+       [[clang::atomic(!no_remote_memory, no_fine_grained_memory)]] {
+           // This compound statement's atomic ops behave differently than outside:
+           //   - no_remote_memory is disabled here
+           //   - no_fine_grained_memory is enabled
+           //   - ignore_denormal_mode remains unchanged from global default
+           // ...
+       }
+   }
+
+A new compiler option, ``-fatomic=<key>:<value>[,<key2>:<value2>...]``, can
+globally override the target's defaults for these atomic-lowering options.
+For instance:
+
+.. code-block:: console
+
+   $ clang -fatomic=no_remote_memory:on,ignore_denormal_mode:on file.cpp
+
+Each key can be one of:
+``no_remote_memory``, ``no_fine_grained_memory``, or ``ignore_denormal_mode``.
+Each value can be ``on``, ``off``, ``yes``, ``no``, ``true``, ``false``, ``1``,
+or ``0`` (case-insensitive). Unrecognized options or invalid formats produce an
+error. Code using the ``[[clang::atomic]]`` attribute then selectively overrides
+the command-line defaults on a per-block basis.
+
+Internally, this attribute attaches "atomic options" information to the compound
+statement in the AST, using an approach analogous to how Clang tracks
+floating-point pragmas. During IR emission, Clang checks these options and
+attaches target-specific metadata (e.g., ``amdgpu.no.remote.memory``) to atomic
+instructions, guiding the backend's lowering process.
+
+Although current usage focuses on AMDGPU, the mechanism is general. Other
+backends can ignore or implement their own responses to these flags if desired.
+If a target does not understand or enforce these hints, the IR remains valid,
+and the resulting program is still correct (although potentially less optimized
+for that user's needs).
+
 Specifying an attribute for multiple declarations (#pragma clang attribute)
 ===========================================================================
 

clang/docs/ReleaseNotes.rst

@@ -110,6 +110,12 @@ Removed Compiler Flags
 Attribute Changes in Clang
 --------------------------
 
+- Introduced a new statement attribute ``[[clang::atomic]]`` that enables
+  fine-grained control over atomic code generation on a per-statement basis.
+  Supported options include ``no_remote_memory``, ``no_fine_grained_memory``,
+  and ``ignore_denormal_mode``, particularly relevant for AMDGPU targets,
+  where they map to corresponding IR metadata.
+
 Improvements to Clang's diagnostics
 -----------------------------------
 

clang/include/clang/Basic/AtomicOptions.def

@@ -0,0 +1,19 @@
+//===--- AtomicOptions.def - Atomic Options database -------------*- C++ -*-===//
+//
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+// This file defines the Atomic language options. Users of this file
+// must define the OPTION macro to make use of this information.
+#ifndef OPTION
+#  error Define the OPTION macro to handle atomic language options
+#endif
+
+// Format: OPTION(NAME, STR, TYPE, WIDTH, PREVIOUS)
+OPTION(NoRemoteMemory, "no_remote_memory", bool, 1, First)
+OPTION(NoFineGrainedMemory, "no_fine_grained_memory", bool, 1, NoRemoteMemory)
+OPTION(IgnoreDenormalMode, "ignore_denormal_mode", bool, 1, NoFineGrainedMemory)
+
+#undef OPTION

clang/include/clang/Basic/Attr.td

@@ -4972,3 +4972,16 @@ def NoTrivialAutoVarInit: InheritableAttr {
   let Documentation = [NoTrivialAutoVarInitDocs];
   let SimpleHandler = 1;
 }
+
+def Atomic : StmtAttr {
+  let Spellings = [Clang<"atomic">];
+  let Args = [VariadicStringArgument<"Options">];
+  let Subjects = SubjectList<[CompoundStmt], ErrorDiag, "compound statements">;
+  let HasCustomParsing = 1;
+  let Documentation = [AtomicDocs];
+  let AdditionalMembers = [{
+    AtomicOptionsOverride AOO;
+    AtomicOptionsOverride getAtomicOptionsOverride() const { return AOO; }
+    void setAtomicOptionsOverride(AtomicOptionsOverride A) { AOO = A; }
+  }];
+}

clang/include/clang/Basic/AttrDocs.td

@@ -8068,6 +8068,21 @@ for details.
   }];
 }
 
+def AtomicDocs : Documentation {
+  let Category = DocCatStmt;
+  let Content = [{
+The ``atomic`` attribute can be applied to *compound statements* to override or
+further specify the default atomic code-generation behavior, especially on
+targets such as AMDGPU. You can annotate compound statements with options
+to modify how atomic instructions inside that statement are emitted at the IR
+level.
+
+For details, see the documentation for `@available
+<http://clang.llvm.org/docs/LanguageExtensions.html#extensions-for-controlling-atomic-code-generation>`_
+
+  }];
+}
+
 def ClangRandomizeLayoutDocs : Documentation {
   let Category = DocCatDecl;
   let Heading = "randomize_layout, no_randomize_layout";

clang/include/clang/Basic/DiagnosticDriverKinds.td

@@ -305,6 +305,16 @@ def err_drv_invalid_int_value : Error<"invalid integral value '%1' in '%0'">;
 def err_drv_invalid_value_with_suggestion : Error<
     "invalid value '%1' in '%0', expected one of: %2">;
 def err_drv_alignment_not_power_of_two : Error<"alignment is not a power of 2 in '%0'">;
+
+def err_drv_invalid_atomic_option : Error<
+  "invalid argument '%0' to '-fatomic='; %select{"
+  "must be a comma-separated list of key:value pairs|"
+  "key '%2' is not allowed; allowed keys are 'no_fine_grained_memory', "
+  "'no_remote_memory', 'ignore_denormal_mode'|"
+  "value '%3' is invalid; must be boolean (true/false, 1/0, yes/no, on/off)|"
+  "duplicate key '%2'"
+  "}1">;
+
 def err_drv_invalid_remap_file : Error<
     "invalid option '%0' not of the form <from-file>;<to-file>">;
 def err_drv_invalid_gcc_install_dir : Error<"'%0' does not contain a GCC installation">;

clang/include/clang/Basic/DiagnosticSemaKinds.td

@@ -3294,6 +3294,8 @@ def err_invalid_branch_protection_spec : Error<
   "invalid or misplaced branch protection specification '%0'">;
 def warn_unsupported_branch_protection_spec : Warning<
   "unsupported branch protection specification '%0'">, InGroup<BranchProtection>;
+def err_attribute_invalid_atomic_argument : Error<
+  "invalid argument '%0' to atomic attribute; valid options are: 'no_remote_memory', 'no_fine_grained_memory', 'ignore_denormal_mode' (optionally prefixed with '!')">;
 
 def warn_unsupported_target_attribute
     : Warning<"%select{unsupported|duplicate|unknown}0%select{| CPU|"

clang/include/clang/Basic/Features.def

@@ -312,6 +312,8 @@ EXTENSION(datasizeof, LangOpts.CPlusPlus)
 
 FEATURE(cxx_abi_relative_vtable, LangOpts.CPlusPlus && LangOpts.RelativeCXXABIVTables)
 
+FEATURE(atomic_attributes, true)
+
 // CUDA/HIP Features
 FEATURE(cuda_noinline_keyword, LangOpts.CUDA)
 EXTENSION(cuda_implicit_host_device_templates, LangOpts.CUDA && LangOpts.OffloadImplicitHostDeviceTemplates)