[llvm] AMDGPU: Preliminary documentation for named barriers (PR #165502)

[Pierre van Houtryve via llvm-commits]

================
@@ -1179,6 +1179,53 @@ is conservatively correct for OpenCL.
                              other operations within the same address space.
      ======================= ===================================================
 
+Target Types
+------------
+
+The AMDGPU backend implements some target extension types.
+
+.. _amdgpu-types-named-barriers:
+
+Named Barriers
+~~~~~~~~~~~~~~
+
+Named barriers are represented as memory objects of type
+``target("amdgcn.named.barrier", 0)``. They are allocated as global variables
+in the LDS address space. They do not occupy regular LDS memory, but their
+lifetime and allocation granularity matches that of global variables in LDS.
+
+The following types built from named barriers are supported in global variables,
+defined recursively:
+
+* a standalone ``target("amdgcn.named.barrier", 0)``
+* an array of supported types
+* a struct containing a single element of supported type
+
+.. code-block:: llvm
+
+      @bar = addrspace(3) global target("amdgcn.named.barrier", 0) undef
+      @foo = addrspace(3) global [2 x target("amdgcn.named.barrier", 0)] undef
+      @baz = addrspace(3) global { target("amdgcn.named.barrier", 0) } undef
+
+Barrier types may not be used in ``alloca``.
+
+The integral representation of a pointer to a valid named barrier is in the
----------------
Pierre-vh wrote:

Ah, I see why you wrote that. The lowering as implemented right now encodes the barrier ID as a pointer value through absolute_address. IMO that's terrible.
I strongly recommend we do not enshrine that hack anywhere in the documentation and keep it as an implementation detail of how the codegen passes communicate.

We should just say the address is not relevant because it is eventually replaced by some "implementation-dependent  unique identifier" used to access the barrier state. Keep it as vague as possible so we have freedom of implementation: the id can be a pointer, an integer, a random dynamically assigned ID, etc.


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