From 72f3fcea16d63eb41804d6fa44b89f0866c360ee Mon Sep 17 00:00:00 2001 From: Krzysztof Drewniak Date: Tue, 11 Nov 2025 17:43:47 +0000 Subject: [PATCH 1/3] [AMDGPU] Document meaning of alignment of buffer fat pointers, intrinsics 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. --- llvm/docs/AMDGPUUsage.rst | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) 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 From 6c02922656741f9fa20af2aca5be4dd1f46226ee Mon Sep 17 00:00:00 2001 From: Krzysztof Drewniak Date: Wed, 12 Nov 2025 19:00:31 +0000 Subject: [PATCH 2/3] Review feedback, add example --- llvm/docs/AMDGPUUsage.rst | 38 ++++++++++++++++++++++---------------- 1 file changed, 22 insertions(+), 16 deletions(-) diff --git a/llvm/docs/AMDGPUUsage.rst b/llvm/docs/AMDGPUUsage.rst index 53862e8aaeeab..cb35b8fd59cd1 100644 --- a/llvm/docs/AMDGPUUsage.rst +++ b/llvm/docs/AMDGPUUsage.rst @@ -1016,13 +1016,13 @@ 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 + 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 with 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 + aligned loads to ``s_buffer_load``, which requires that both the base pointer and offset be appropriately aligned.) **Buffer Resource** @@ -1048,17 +1048,23 @@ 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 + When buffer resources are passed to buffer intrinsics such as + ``llvm.amdgcn.raw.ptr.buffer.load`` or + ``llvm.amdgcn.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 alignment of the effective + address being loaded from/stored to *and* acts as a guarantee that this is not achieved from adding lower-alignment parts (as hardware may not always - allow for such an addition). + allow for such an addition). For example, if a buffer resource has the base + address ``0xfffe`` and is accessed with a ``raw.ptr.buffer.load`` with an offset + of ``2``, the load must **not** be marked ``align 4`` (even though the + effective adddress ``0x10000`` is so aligned) as this would permit the compiler + to make incorrect transformations (such as promition to ) **Buffer Strided Pointer** The buffer index pointer is an experimental address space. It represents @@ -1080,8 +1086,8 @@ supported for the ``amdgcn`` target. 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 + 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** From fd867ad97494184f28b8113444026ec360f8d68e Mon Sep 17 00:00:00 2001 From: Krzysztof Drewniak Date: Wed, 12 Nov 2025 20:34:47 +0000 Subject: [PATCH 3/3] Forgot to finish my sentence, fix typos --- llvm/docs/AMDGPUUsage.rst | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/llvm/docs/AMDGPUUsage.rst b/llvm/docs/AMDGPUUsage.rst index cb35b8fd59cd1..b8b372d4113c1 100644 --- a/llvm/docs/AMDGPUUsage.rst +++ b/llvm/docs/AMDGPUUsage.rst @@ -1021,9 +1021,9 @@ supported for the ``amdgcn`` target. both have the offset be a multiple of 4 and to have a base pointer with an alignment of 4. - (This componentwise definition of alignment is needed to allow for promotion of + 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.) + offset be appropriately aligned. **Buffer Resource** The buffer resource pointer, in address space 8, is the newer form @@ -1053,7 +1053,7 @@ supported for the ``amdgcn`` target. ``llvm.amdgcn.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 + addrspace(8)`` and the ``offset`` argument have their three lowest bits set to 0. If the stride of the resource is nonzero, the stride must be a multiple of the given alignment. @@ -1064,7 +1064,8 @@ supported for the ``amdgcn`` target. address ``0xfffe`` and is accessed with a ``raw.ptr.buffer.load`` with an offset of ``2``, the load must **not** be marked ``align 4`` (even though the effective adddress ``0x10000`` is so aligned) as this would permit the compiler - to make incorrect transformations (such as promition to ) + to make incorrect transformations (such as promotion to ``s_buffer_load``, + which requires such componentwise alignment). **Buffer Strided Pointer** The buffer index pointer is an experimental address space. It represents