[Mlir-commits] [mlir] [mlir] Document GPU dialect layering to capture discussions from a PR (PR #95812)

[Krzysztof Drewniak]

================
@@ -12,8 +12,36 @@ manipulations to launch a GPU kernel and provide a simple path towards GPU
 execution from MLIR. It may be targeted, for example, by DSLs using MLIR. The
 dialect uses `gpu` as its canonical prefix.
 
+This dialect also abstracts away primitives commonly available in GPU code, such
+as with `gpu.thread_id` (an operation that returns the ID of threads within
+a thread block/workgroup along a given dimension). While the compilation
+pipelines documented below expect such code to live inside a `gpu.module` and
+`gpu.func`, these intrinsic wrappers may be used outside of this context.
+
+Intrinsic-wrapping operations should not expect that they have a parent of type
+`gpu.func`. However, operations that deal in compiling and launching GPU functions,
+like `gpu.launch_func` or `gpu.binary` may assume that the dialect's full layering
+is being used.
+
 [TOC]
 
+## GPU address spaces
+
+The GPU dialect exposes the `gpu.address_space` attribute, which currently has
+three values: `global`, `workgroup`, and `private`.
+
+These address spaces represent the types of buffer commonly seen in GPU compilation:.
+`global` memory is memory that resides in the GPU's global memory and is commonly
+used for function arguments. `workgroup` memory is a limited, per-workgroup resource:
+all threads in a workgroup/thread block access the same values in `worgroup` memory,
+but cannot access the `workgroup` memory of other workgroups. Finally, `private`
+memory is used to represent `alloca`-like buffers that are private to a sigle thread.
----------------
krzysz00 wrote:

Done

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