[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:

This paragraph doesn't feel right. I think we should say absolutely nothing about the pointer value and not commit to anything in that regard. We can just say it is only valid to form a pointer to a value of type `amdgcn.named.barrier` by taking the address of a global value of that type, and modifying those pointers in any way (pointer arithmetic for example) is undefined behavior.

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