[llvm-branch-commits] [llvm] [AMDGPU][docs] Document the <4 x i32> buffer intrinsic deprecation (PR #231302)

[Krzysztof Drewniak via llvm-branch-commits]

https://github.com/krzysz00 updated https://github.com/llvm/llvm-project/pull/231302

>From e10e2b68139765cdaf1918ef7db0df39ce8c0ba3 Mon Sep 17 00:00:00 2001
From: Krzysztof Drewniak <Krzysztof.Drewniak at amd.com>
Date: Fri, 9 Oct 2026 16:29:02 +0000
Subject: [PATCH] [AMDGPU][docs] Document the <4 x i32> buffer intrinsic
 deprecation

Flag the deprecation of <4 x i32> buffer intrinsics in the release
notes, flagging the migration path and the s.buffer.load subtleties.

AI disclosure: Claude did draft some of this, but I deleted basically
all of it and the words are mine

Co-Authored-By: Claude Opus 5 (1M context) <noreply at anthropic.com>
---
 llvm/docs/AMDGPUUsage.rst | 25 ++++++++++++++++++++++++-
 llvm/docs/ReleaseNotes.md | 31 +++++++++++++++++++++++++++++++
 2 files changed, 55 insertions(+), 1 deletion(-)

diff --git a/llvm/docs/AMDGPUUsage.rst b/llvm/docs/AMDGPUUsage.rst
index 34dc835438378..27f002e4a40ec 100644
--- a/llvm/docs/AMDGPUUsage.rst
+++ b/llvm/docs/AMDGPUUsage.rst
@@ -1355,6 +1355,14 @@ supported for the ``amdgcn`` target.
   to make incorrect transformations (such as promotion to ``s_buffer_load``,
   which requires such componentwise alignment).
 
+  The buffer intrinsics that take their resource as a ``<4 x i32>`` instead of
+  a ``ptr addrspace(8)`` are deprecated and will be removed in a future LLVM
+  release. Add ``ptr`` after the
+  ``raw``/``struct`` component of the intrinsic name for the new version.
+  However, ``llvm.amdgcn.s.buffer.load`` becomes
+  ``llvm.amdgcn.ptr.s.buffer.load`` and needs to be annotated with ``!invariant.load``
+  to preserve the old merging behavior. This migration was already done in clang.
+
 **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
@@ -2231,6 +2239,17 @@ The AMDGPU backend implements the following LLVM IR intrinsics.
 
                                                    * Local pointer to the LDS barrier data.
 
+  llvm.amdgcn.s.buffer.load                        Deprecated. Takes its buffer resource as a ``<4 x i32>``. Use
+                                                   ``llvm.amdgcn.ptr.s.buffer.load``, which takes a ``ptr addrspace(8)``
+                                                   produced by ``llvm.amdgcn.make.buffer.rsrc``.
+                                                   The implicit assumptions encoded by the fact that this intrinsic was tagged as not reading memory are replaced by needing to tag ``llvm.amdgcn.ptr.s.buffer.load`` with ``!invariant.load`` metadata.
+
+  llvm.amdgcn.{raw|struct}.*buffer.*               Deprecated. The ``buffer``, ``tbuffer`` and ``atomic.buffer.load``
+                                                   intrinsics that take their buffer resource as a ``<4 x i32>`` are
+                                                   replaced by the variants with ``ptr`` inserted after the ``raw`` or
+                                                   ``struct`` component of the name, which take a ``ptr addrspace(8)``
+                                                   produced by ``llvm.amdgcn.make.buffer.rsrc``. Codegen warns for their use.
+
   ==============================================   ==========================================================
 
 .. TODO::
@@ -2406,10 +2425,14 @@ registers. See :ref:`amdgpu-dma-operations` for full documentation.
 
   llvm.amdgcn.load[.async].to.lds
   llvm.amdgcn.global.load[.async].lds
-  llvm.amdgcn.{raw|struct}[.ptr].buffer.load[.async].lds
+  llvm.amdgcn.{raw|struct}.ptr.buffer.load[.async].lds
   llvm.amdgcn.{global|cluster}.load.async.to.lds.b{8,32,64,128}
   llvm.amdgcn.global.store.async.from.lds.b{8,32,64,128}
 
+The ``llvm.amdgcn.{raw|struct}.buffer.load[.async].lds`` spellings, which take
+their buffer resource as a ``<4 x i32>`` rather than a ``ptr addrspace(8)``,
+are deprecated.
+
 Tensor Intrinsics
 ~~~~~~~~~~~~~~~~~
 
diff --git a/llvm/docs/ReleaseNotes.md b/llvm/docs/ReleaseNotes.md
index cec21851f0d76..c7366a6af8230 100644
--- a/llvm/docs/ReleaseNotes.md
+++ b/llvm/docs/ReleaseNotes.md
@@ -284,6 +284,37 @@ Makes programs 10x faster by doing Special New Thing.
   * `llvm.amdgcn.icmp`
   * `llvm.amdgcn.fcmp`
 
+* The AMDGPU buffer intrinsics that take their buffer resource (rsrc/V#)
+  argument as a `<4 x i32>` are deprecated and will be removed in a future
+  LLVM release. Codegen now warns for their use once per module.
+
+  They all have `.ptr.` equivalents that take a `ptr addrspace(8)`, produced by
+  `llvm.amdgcn.make.buffer.rsrc`, loaded directly from memory, or, if
+  necessary, converted from an existing descriptor with
+  `bitcast <4 x i32> %rsrc to i128` followed by `inttoptr i128 %i to ptr
+  addrspace(8)`. To migrate, insert `ptr` after the `raw`/`struct` component of
+  the intrinsic name; `llvm.amdgcn.s.buffer.load` is the sole exception and
+  becomes `llvm.amdgcn.ptr.s.buffer.load`.
+
+  ```llvm
+  ; Before
+  %v = call float @llvm.amdgcn.raw.buffer.load.f32(<4 x i32> %rsrc, i32 %off, i32 0, i32 0)
+
+  ; After
+  %p = call ptr addrspace(8) @llvm.amdgcn.make.buffer.rsrc.p8.p1.i32(ptr addrspace(1) %base, i16 0, i32 %numrecords, i32 %flags)
+  %v = call float @llvm.amdgcn.raw.ptr.buffer.load.f32(ptr addrspace(8) %p, i32 %off, i32 0, i32 0)
+  ```
+
+  This migration enables future flexibility in resource size and usage and
+  allows for more accurate analysis of memory usage.
+
+  Note that when emitting `llvm.amdgcn.ptr.s.buffer.load`, you must tag the intrinsic with `!invariant.load` metadata in order to recover the merging and loop hoisting behavior that `llvm.amdgcn.s.buffer.load` had because it lied about 'not reading memory'. Explicitly tagging these buffer loads as invariant will teach LLVM's general infrastructure about the property that users of the old ``s.buffer.load`` intrinsic were already asserting.
+
+  While we do intend to autoupgrade the old intrinsics when they are removed, this upgrade will have to use `inttoptr` to convert buffer resources, losing pointer provenance. Therefore, we strongly encourage users to migrate to the new forms (which have been available for years) before this removal.
+
+  The warning can be suppressed with the
+  `amdgpu-warn-deprecated-buffer-intrinsics=0` option.
+
 ### Changes to the ARM Backend
 
 * Using the hard-float procedure call standard without floating-point registers