[clang] [Clang][Docs] Add documentation for the address_space attribute (PR #181924)

[via cfe-commits]

llvmbot wrote:


<!--LLVM PR SUMMARY COMMENT-->

@llvm/pr-subscribers-clang

Author: Reid Kleckner (rnk)

<details>
<summary>Changes</summary>

Someone asked for docs on Discourse:
https://discourse.llvm.org/t/what-are-the-precise-semantics-of-the-address-space-attribute/89752

I was going to respond, and then I decided to respond in the form of a
PR, since I have a doc building environment set up.

I used an LLM, but I ended up rewriting most of the text.


---
Full diff: https://github.com/llvm/llvm-project/pull/181924.diff


2 Files Affected:

- (modified) clang/include/clang/Basic/Attr.td (+1-1) 
- (modified) clang/include/clang/Basic/AttrDocs.td (+34) 


``````````diff
diff --git a/clang/include/clang/Basic/Attr.td b/clang/include/clang/Basic/Attr.td
index 2621d178d99e8..584182fc2b5db 100644
--- a/clang/include/clang/Basic/Attr.td
+++ b/clang/include/clang/Basic/Attr.td
@@ -852,7 +852,7 @@ def AbiTag : Attr {
 def AddressSpace : TypeAttr {
   let Spellings = [Clang<"address_space">];
   let Args = [IntArgument<"AddressSpace">];
-  let Documentation = [Undocumented];
+  let Documentation = [AddressSpaceDocs];
 }
 
 def Alias : Attr {
diff --git a/clang/include/clang/Basic/AttrDocs.td b/clang/include/clang/Basic/AttrDocs.td
index f91fe2c7b0259..0e3aaee543d21 100644
--- a/clang/include/clang/Basic/AttrDocs.td
+++ b/clang/include/clang/Basic/AttrDocs.td
@@ -193,6 +193,40 @@ TLS models are mutually exclusive.
   }];
 }
 
+def AddressSpaceDocs : Documentation {
+  let Category = DocCatType;
+  let Heading = "address_space";
+  let Content = [{
+.. Note:: This attribute is mainly intended to be used by target headers
+  provided by the toolchain. End users should prefer the documented annotations
+  for their platform, such as the `OpenCL address spaces`_, ``__global__``,
+  ``__local__``, or something else.
+
+The ``address_space`` attribute allows you to specify the address space for a
+pointer or reference type. It takes a single, non-negative integer constant
+expression identifying the address space. For example:
+
+.. code-block:: c
+
+  int * __attribute__((address_space(1))) ptr;
+
+  void foo(__attribute__((address_space(2))) float *buf);
+
+The meaning of each value is defined by the target; multiple address spaces are
+used in environments such as OpenCL, CUDA, HIP, and other GPU programming
+models to distinguish global, local, constant, and private memory. See for
+example the address spaces defined in the `NVPTX Usage Guide`_ and the `AMDGPU
+Usage Guide`_
+
+.. _`NVPTX Usage Guide`: https://llvm.org/docs/NVPTXUsage.html#address-spaces
+.. _`AMDGPU Usage Guide`: https://llvm.org/docs/AMDGPUUsage.html#address-spaces
+
+Only one address space qualifier may be applied to a given pointer or reference
+type. Where address spaces are allowed (e.g., variables, parameters, return
+types) and what values are valid depends on the target and language mode.
+  }];
+}
+
 def DLLExportDocs : Documentation {
   let Category = DocCatVariable;
   let Content = [{

``````````

</details>


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