[llvm] [Docs][AMDGPU] Explain completion of async operations (PR #212756)

[Sameer Sahasrabuddhe via llvm-commits]

https://github.com/ssahasra updated https://github.com/llvm/llvm-project/pull/212756

>From 8a2c9ab1af2840688e9e16e51513d4d87a645534 Mon Sep 17 00:00:00 2001
From: Sameer Sahasrabuddhe <sameer.sahasrabuddhe at amd.com>
Date: Wed, 29 Jul 2026 17:52:21 +0530
Subject: [PATCH 1/2] [Docs][AMDGPU] Explain completion of async operations

This improves the somewhat hand-wavey "memory model" currently described for
async operations. While this version is also not complete, it prepares for the
more complete memory model being written down.
---
 llvm/docs/AMDGPUAsyncOperations.md | 39 +++++++++++++++++++-----------
 1 file changed, 25 insertions(+), 14 deletions(-)

diff --git a/llvm/docs/AMDGPUAsyncOperations.md b/llvm/docs/AMDGPUAsyncOperations.md
index 08db935a60dd2..a41cd33523d85 100644
--- a/llvm/docs/AMDGPUAsyncOperations.md
+++ b/llvm/docs/AMDGPUAsyncOperations.md
@@ -14,11 +14,14 @@ internally by the compiler. A thread that initiates one or more async operations
 ## Asyncmarks
 
 An *asyncmark* created by a thread can be used to track async operations
-initiated by that thread. The abstract machine maintains a sequence of
-asyncmarks during the execution of a function body, which excludes any
-asyncmarks produced by calls to other functions encountered in the currently
-executing function. The state of this sequence at each program point in the
-function is called the *current sequence*.
+initiated by that thread.
+
+### Current Sequence
+
+The abstract machine maintains a sequence of asyncmarks during the execution of
+a function body, which excludes any asyncmarks produced by calls to other
+functions encountered in the currently executing function. The state of this
+sequence at each program point in the function is called the *current sequence*.
 
 ### `@llvm.amdgcn.asyncmark()`
 
@@ -29,9 +32,7 @@ Produces an asyncmark and appends it to the current sequence.
 Ensures that the length of the current sequence is at most `N` by removing
 asyncmarks from the start of the sequence if it is more than `N`.
 
-(amdgpu-asyncmark-memory-model)=
-
-## Memory Model
+### Completion
 
 An `asyncmark()` operation `X` that produces an asyncmark `M` is
 *completed-at* a `wait.asyncmark()` operation `Y` in the same function body
@@ -41,13 +42,23 @@ if:
 - `M` is not in the current sequence at any operation `Z` that immediately
   follows `Y` in *program-order*.
 
-Each dynamic instance `I` of an async *instruction* initiates a corresponding
-async *operation* `A` such that `I` *happens-before* `A`. Then `A`
-*happens-before* a `wait.asyncmark()` operation `Y` if there exists an
-`asyncmark()` operation `X` such that:
+## Completion of Async Operations
+
+An async operation executes outside the thread that initiated it, i.e., it is
+not related in *program-order* with any other operations from that thread. But
+the thread can use an asyncmark to ensure that the async operation is
+*completed-at* some later operation.
+
+An async operation `A` *initiated-by* an instruction `I` is *completed-at* some
+`wait.asyncmark()` operation `Y` if there exists an `asyncmark()` operation `X`
+such that:
+  - `I` is *program-ordered* before `X`, and
+  - `X` is *completed-at* `Y`.
+
+### happens-before
 
-- `I` is *program-ordered* before `X`, and
-- `X` is *completed-at* `Y`.
+If an async operation `A` is *completed-at* a `wait.asyncmark()` operation `Y`,
+then `A` *happens-before* `Y`.
 
 ## Examples
 

>From f0375dab11aa369d85b2ec90d628de68eb404dcf Mon Sep 17 00:00:00 2001
From: Sameer Sahasrabuddhe <sameer.sahasrabuddhe at amd.com>
Date: Thu, 30 Jul 2026 13:56:49 +0530
Subject: [PATCH 2/2] (temporarily) restore happens-before

---
 llvm/docs/AMDGPUAsyncOperations.md | 13 ++++++++-----
 1 file changed, 8 insertions(+), 5 deletions(-)

diff --git a/llvm/docs/AMDGPUAsyncOperations.md b/llvm/docs/AMDGPUAsyncOperations.md
index a41cd33523d85..4dc01148fe781 100644
--- a/llvm/docs/AMDGPUAsyncOperations.md
+++ b/llvm/docs/AMDGPUAsyncOperations.md
@@ -32,7 +32,7 @@ Produces an asyncmark and appends it to the current sequence.
 Ensures that the length of the current sequence is at most `N` by removing
 asyncmarks from the start of the sequence if it is more than `N`.
 
-### Completion
+### Completion of Asyncmarks
 
 An `asyncmark()` operation `X` that produces an asyncmark `M` is
 *completed-at* a `wait.asyncmark()` operation `Y` in the same function body
@@ -52,13 +52,16 @@ the thread can use an asyncmark to ensure that the async operation is
 An async operation `A` *initiated-by* an instruction `I` is *completed-at* some
 `wait.asyncmark()` operation `Y` if there exists an `asyncmark()` operation `X`
 such that:
-  - `I` is *program-ordered* before `X`, and
-  - `X` is *completed-at* `Y`.
+- `I` is *program-ordered* before `X`, and
+- `X` is *completed-at* `Y`.
 
 ### happens-before
 
-If an async operation `A` is *completed-at* a `wait.asyncmark()` operation `Y`,
-then `A` *happens-before* `Y`.
+When an instruction `I` initiates an async operation `A`, `I` *happens-before*
+`A`.
+
+If `A` is *completed-at* a `wait.asyncmark()` operation `Y`, then `A`
+*happens-before* `Y`.
 
 ## Examples