[clang] Add clang atomic control options and attribute (PR #114841)

[Yaxun Liu via cfe-commits]

================
@@ -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)]]
----------------
yxsamliu wrote:

The ``[[clang::atomic]]`` attribute affects only the code generation of atomic
instructions within the annotated compound statement. Clang attaches
target-specific metadata to those atomic instructions in the emitted LLVM IR
to guide backend lowering. This metadata is fixed at the clang code generation
phase and is not modified by later LLVM passes (such as function inlining).

For example, consider:

.. code-block:: cpp
  inline void func() {
    [[clang::atomic(no_remote_memory)]] {
      // Atomic instructions lowered with metadata.
    }
  }

  void foo() {
    [[clang::atomic(!no_remote_memory)]] {
      func(); // Inlined by LLVM, but the metadata from 'func()' remains unchanged.
    }
  }

Similarly, when used within an operator `<=>`, the attribute only affects the
atomic instructions inside the annotated compound statement. It does not alter
the semantics of the generated comparison or equality operators.

will update the documentation about this, also about the function body


https://github.com/llvm/llvm-project/pull/114841