[llvm] [AMDGPU] A Vulkan-style memory model weaker than the LLVM model (PR #191246)

[Pierre van Houtryve via llvm-commits]

================
@@ -0,0 +1,406 @@
+.. _amdgpu-memmodel:
+
+=====================
+ AMDGPU Memory Model
+=====================
+
+.. contents::
+   :local:
+
+Introduction
+============
+
+The :ref:`LLVM memory model<memmodel>` provides broad guarantees that are
+sufficient to implement inter-thread communication via memory. But in most
+communication patterns, not all memory accesses performed by a thread need to be
+exposed to other threads. Even when they do need to be exposed, not all threads
+may need to observe these memory accesses. This document describes the *AMDGPU
+memory model* that allows the user to control how the side-effects of memory
+accesses are propagated across threads. The programmer expresses this using
+**new intrinsics and metadata** as described below, and the implementation can
+then choose a more efficient mechanism to complete them, such as the cache
+policy bits in an AMDGPU device.
+
+The AMDGPU memory model allows executions that are not allowed by the LLVM
+memory model. At the same time, a simple mapping can be used to implement these
+new intrinsics and metadata using operations defined in the default LLVM memory
+model. Thus, **there exists a safe-by-default implementation** that produces
+executions that are valid in both models.
+
+Terminology
+===========
+
+Memory Accesses
+  Operations that read or write locations in memory are termed as *memory
+  accesses*. Typical examples are ``load``, ``store`` and atomic instructions,
+  as well as many intrinsics.
+
+Synchronization Operations
+  Synchronization operations control how the side-effects of memory accesses are
+  propagated in the system. Typical examples are atomic operations (including
+  fences) with at least ``release`` or ``acquire`` ordering.
+
+.. _amdgpu-scopes:
+
+Scopes
+======
+
+A *scope* describes sets of memory accesses and synchronization operations in a
+multi-threaded execution environment. Each such set is called an *instance* of
+that scope, or a *scope instance* for short.
+
+- Each memory access or synchronization operation belongs to at most one
+  instance of every scope defined by the target.
----------------
Pierre-vh wrote:

Above you use `*scope instance*`, I'd suggest using the same italic notation everywhere in the spec for consistency. Right now the use of bold/italic feels a bit ad-hoc.
I'd strongly recommend using one convention and sticking to it across the document. e.g. I like:

- code backticks for symbols/names, like "let `X` ..."
- italic for keywords and concepts that have a precise definition somewhere else in the document
- bold used for emphasis as-needed, e.g. to insist on a contradiction, like "`A` is **not** part of `B`"

It's fine if you prefer a different notation, like using italic only once on the first use of a term. Now that I think about it perhaps it should be written down as a quick hidden note at the top of the document, so future edits can remain consistent ? (in a [comment](https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#comments))

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