[llvm] [AMDGPU] Improve the description of asyncmark semantics (PR #202579)

[Fabian Ritter via llvm-commits]

================
@@ -220,30 +217,96 @@ correctness. But inlining such a call may result in redundant waits.
 .. code-block:: c++
 
    void foo() {
-     asyncmark(); // A
+     ...
+     asyncmark();       // X
+     ...                // no wait.asyncmark()
    }
 
    void bar() {
-     asyncmark(); // B
-     asyncmark(); // C
+     asyncmark();       // B
+     asyncmark();       // C
      foo();
-     wait.asyncmark(1);
+     wait.asyncmark(1); // D
+   }
+
+Before inlining, it is unspecified whether ``X`` is *completed-at* ``D``, while
+``C`` is **not** *completed-at* ``D``. The programmer can only rely on ``B``
+being *completed-at* ``D``.
+
+.. code-block:: c++
+
+   void bar() {
+     asyncmark();       // B
+     asyncmark();       // C
+     asyncmark();       // X
+     wait.asyncmark(1); // D
    }
 
-Before inlining, the ``wait.asyncmark`` waits for asyncmark B to be completed.
+After inlining, ``C`` is also *completed-at* ``D`` and ``X`` is **not**
+*completed-at* ``D``.
+
+Conversely, a ``wait.asyncmark`` call inside a callee cannot be used to track
+asyncmarks inserted by the caller, since this ``wait.asyncmark`` can only
+observe the current sequence of the callee.
 
 .. code-block:: c++
 
    void foo() {
+     ...                // no asyncmark()
+     wait.asyncmark(0); // Y
+     ...
    }
 
    void bar() {
-     asyncmark(); // B
-     asyncmark(); // C
-     asyncmark(); // A from call to foo()
-     wait.asyncmark(1);
+     asyncmark();       // B
+     asyncmark();       // C
+     foo();
+     wait.asyncmark(1); // D
+   }
+
+In the above example, it is unspecified whether ``B`` and ``C`` in ``bar()`` are
+*completed-at* ``Y``, because they are not included in the sequence that can be
+examined at ``Y``.
+
+.. code-block:: c++
+
+   void bar() {
+     asyncmark();       // B
+     asyncmark();       // C
+     wait.asyncmark(0); // Y
----------------
ritter-x2a wrote:

Also `...` lines from `foo` here?

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