[AMDGPU] Document meaning of alignment of buffer fat pointers, intrinsics

[krzysz00]

This commit adds documentation clarifying the meaning of align on ptr addrpsace(7) (buffer fat pointer) and ptr addrspace(9) (bufferef structured pointer) operations (specifying that both the base and the offset need to be aligned) and documents the meaning of the align attribute when used as an argument on .buffer.ptr. intrinsics.

[llvmbot]

@llvm/pr-subscribers-backend-amdgpu

Author: Krzysztof Drewniak (krzysz00)

Changes

This commit adds documentation clarifying the meaning of align on ptr addrpsace(7) (buffer fat pointer) and ptr addrspace(9) (bufferef structured pointer) operations (specifying that both the base and the offset need to be aligned) and documents the meaning of the align attribute when used as an argument on .buffer.ptr. intrinsics.

---

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

1 Files Affected:

• (modified) llvm/docs/AMDGPUUsage.rst (+27)

diff --git a/llvm/docs/AMDGPUUsage.rst b/llvm/docs/AMDGPUUsage.rst
index ba0e53bceade8..53862e8aaeeab 100644
--- a/llvm/docs/AMDGPUUsage.rst
+++ b/llvm/docs/AMDGPUUsage.rst
@@ -1016,6 +1016,15 @@ supported for the ``amdgcn`` target.
   `ptr addrspace(7)` directly, which produces a buffer fat pointer with an initial
   offset of 0 and prevents the address space cast from being rewritten away.
 
+  The `align` attribute on operations from buffer fat pointers is deemed to apply
+  to all componenents of the pointer - that is, an `align 4` load is expected to
+  both have the offset be a multiple of 4 and to have a base pointer whose an
+  alignment of 4.
+
+  (This componentwise definition of alignment is needed to allow for promotion of
+  aligned loads to `s_buffer_load`, which requires that both the base pointer and
+  offset be appropriately aligned.)
+
 **Buffer Resource**
   The buffer resource pointer, in address space 8, is the newer form
   for representing buffer descriptors in AMDGPU IR, replacing their
@@ -1039,6 +1048,18 @@ supported for the ``amdgcn`` target.
   (bits `127:96`). The specific interpretation of these fields varies by the
   target architecture and is detailed in the ISA descriptions.
 
+  When buffer resourcess are passed to buffer intrinsics such as `raw.ptr.buffer.load`
+  or `struct.ptr.buffer.store`, the `align` attribute on the pointer is assumed to
+  apply to both the offset and the base pointer value. That is, `align 8` means that
+  both the base address within the `ptr addrspace(8)` and the `offset` argument
+  have their three lowesst bits set to 0. If the stride of the resource is nonzero,
+  the stride must be a multiple of the given alignment.
+
+  In other words, the `align` attribute specifies the alignemnt of the effective
+  address being loaded from/stored to *and* acts as a guuarantee that this is
+  not achieved from adding lower-alignment parts (as hardware may not always
+  allow for such an addition).
+
 **Buffer Strided Pointer**
   The buffer index pointer is an experimental address space. It represents
   a 128-bit buffer descriptor and a 32-bit offset, like the **Buffer Fat
@@ -1057,6 +1078,12 @@ supported for the ``amdgcn`` target.
   index and offset values are both 0. This prevents the address space cast from
   being rewritten away.
 
+  As with buffer fat pointers, alignment of a buffer strided pointer applies to
+  both the base pointer address and the offset. In addition, the alignment also
+  constrains the stride of the pointer. That is, if you do an `align 4` load from
+  a buffer strided pointer, this means that the base pointer is `align(4)`, that
+  the offset is a multiple of 4 bytes, and that the stride is a multiple of 4.
+
 **Streamout Registers**
   Dedicated registers used by the GS NGG Streamout Instructions. The register
   file is modelled as a memory in a distinct address space because it is indexed