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

[Adam Siemieniuk]

================
@@ -12,8 +12,35 @@ 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. `workgroup`
+memory is a limited, per-workgroup resource: all threads in a workgroup/thread
+block access the same values in `worgroup` memory. Finally, `private` memory is
----------------
adam-smnk wrote:

```suggestion
block access the same values in `workgroup` memory. Finally, `private` memory is
```

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